| Qore RestHandler Module Reference 1.5.2

Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
RestHandler::RestHandler Class Reference

this is the main handler class to be registered with the HttpServer More...

Inheritance diagram for RestHandler::RestHandler:
[legend]

## Public Member Functions
| constructor (*HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator())
| create the object optionally with the given HttpServer::AbstractAuthenticator More...
| constructor (Logger::Logger logger, *HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator(logger))
| create the object optionally with the given Logger and authenticator More...
hash< auto > | get (hash< auto > cx, *hash< auto > ah)
| default get handler for the base handler class
auto | handleExternalRequest (string method, string path, *hash< auto > body, hash< auto > cx={})
| processes REST API calls outside the HTTP server More...
hash< HttpResponseInfo > | handleRequest (HttpListenerInterface listener, Socket s, hash< auto > cx, hash< auto > hdr, *data b)
| called by the HTTP server to handle incoming HTTP requests More...
| logDebug (string fmt)
| This method is called with debug log messages. More...
| logError (string fmt)
| This method is called with error log messages. More...
| logInfo (string fmt)
| This method is called with informational log messages. More...
string | name ()
| returns the name of the root REST class
| removeRootPath (reference< string > path)
| default implementation is empty
| requestDeserializationError (hash< auto > hdr, hash< auto > cx, string body)
| default implementation is empty
| responseSerializationError (hash< auto > cx, *hash< auto > aih, hash< auto > rv)
| default implementation is empty
| setLogger (Logger::Logger logger)
| Sets a new logger.
Public Member Functions inherited from RestHandler::AbstractRestClass
| addClass (AbstractRestClass cls)
| adds a REST class to the handler
hash< HttpServer::HttpHandlerResponseInfo > | handleRequest (HttpListenerInterface listener, RestHandler rh, Socket s, *list< string > cl, string mn, hash< auto > cx, *hash< auto > args)
| this method is called by the RestHandler class to match the right object with incoming requests

## Static Public Member Functions
static hash< HttpHandlerResponseInfo > | make200 (hash< auto > hdr, string fmt)
| creates a hash for an HTTP 200 OK error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make200 (string fmt)
| creates a hash for an HTTP 200 OK error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make400 (hash< auto > hdr, string fmt)
| creates a hash for an HTTP 400 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make400 (string fmt)
| creates a hash for an HTTP 400 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make500 (hash< auto > hdr, string fmt)
| creates a hash for an HTTP 500 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make500 (string fmt)
| creates a hash for an HTTP 500 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make501 (hash< auto > hdr, string fmt)
| creates a hash for an HTTP 501 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | make501 (string fmt)
| creates a hash for an HTTP 501 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > | makeResponse (int code, auto body, *hash< auto > hdr)
| creates a hash for an HTTP response with the response code and a literal response message body

## Public Attributes
const | Err501 = ...
| a hash for a 501 Unimplemented error message
const | Methods = ...
| supported HTTP methods
Public Attributes inherited from RestHandler::AbstractRestClass
hash< string, AbstractRestClass > | class_hash
| class hash: name -> AbstractRestClass
const | RestBasicMethodSet = map {$1: True}
| set of REST class method names based on basic HTTP methods

## Protected Member Functions
| checkExceptionSerializable (reference< hash< ExceptionInfo >> ex)
| Recursively ensure that exception arguments are serializable.
hash< HttpHandlerResponseInfo > | dispatchRequest (HttpListenerInterface listener, Socket s, *list< string > class_list, string method_name, string path, hash< auto > cx, *hash< auto > args)
| Dispatches the request and returns the response.
hash< HttpHandlerResponseInfo > | returnRestException (hash< ExceptionInfo > ex)
| method that determines how exceptions handling REST requests are returned More...
Protected Member Functions inherited from RestHandler::AbstractRestClass
hash< HttpServer::HttpHandlerResponseInfo > | dispatch (RestHandler rh, string mn, *hash< auto > ah, hash< auto > cx)
| this method is called to dispatch requests on the given object More...
hash< HttpServer::HttpHandlerResponseInfo > | dispatchStream (HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash< auto > ah, hash< auto > cx)
| this method is called to dispatch streamed requests on the given object
*hash< string, bool > | doGetPossibleSubClasses (hash< auto > cx)
| returns a set of possible subclasses for a particular request More...
hash< HttpServer::HttpHandlerResponseInfo > | unknownSubClassError (string cls_name, hash< auto > cx)
| returns a 404 Not Found response when a request tries to access an unknown subclass More...

## Protected Attributes
Logger::Logger | logger
| logger
RestSchemaValidator::AbstractRestSchemaValidator | validator
| REST schema validator.

## Detailed Description

this is the main handler class to be registered with the HttpServer

The RestHandler class should be subclassed to customize its behavior.

To provide for logging; the following methods can be reimplemented in subclasses:

- RestHandler::RestHandler::logInfo()
- RestHandler::RestHandler::logError()
- RestHandler::RestHandler::logDebug()

In order to match REST requests under a root path, reimplement the following method in a subclass:

- RestHandler::RestHandler::removeRootPath()

## Member Function Documentation

## ◆ constructor() [1/2]

RestHandler::RestHandler::constructor | ( | *HttpServer::AbstractAuthenticator | auth,
|  | RestSchemaValidator::AbstractRestSchemaValidator | validator = `new NullRestSchemaValidator()`
| ) |  |

create the object optionally with the given HttpServer::AbstractAuthenticator

Parameters

  auth | the authentication object to use to authenticate connections (see HttpServer::AbstractAuthenticator); if no HttpServer::AbstractAuthenticator object is passed, then by default no authentication will be required
  validator | a REST API schema validator object; if none is present, then the default REST de/serialization support is provided as documented in RestSchemaValidator::NullRestSchemaValidator

## ◆ constructor() [2/2]

RestHandler::RestHandler::constructor | ( | Logger::Logger | logger,
|  | *HttpServer::AbstractAuthenticator | auth,
|  | RestSchemaValidator::AbstractRestSchemaValidator | validator = `new NullRestSchemaValidator(logger)`
| ) |  |

create the object optionally with the given Logger and authenticator

Parameters

  logger | the logger to use for the handler
  auth | the authentication object to use to authenticate connections (see HttpServer::AbstractAuthenticator); if no HttpServer::AbstractAuthenticator object is passed, then by default no authentication will be required
  validator | a REST API schema validator object; if none is present, then the default REST de/serialization support is provided as documented in RestSchemaValidator::NullRestSchemaValidator

## ◆ handleExternalRequest()

auto RestHandler::RestHandler::handleExternalRequest | ( | string | method,
|  | string | path,
|  | *hash< auto > | body,
|  | hash< auto > | cx = `{}`
| ) |  |

processes REST API calls outside the HTTP server

Requests will be dispatched to REST classes registered with this object

Parameters

  method | the HTTP method; if the the method is unknown, an `UNKNOWN-REST-METHOD` exception is raised
  path | the URI path for the call
  body | the arguments to the call; note that arguments are combined with any arguments provided in path
  cx | simulated HTTP call context hash

Returns
  the response value of the REST method

Exceptions

  UNKNOWN-REST-METHOD | the HTTP method is unknown / unsupported
  INVALID-URI-PATH | URI cannot be parsed
  INVALID-REST-ARGS | invalid REST action
  REST-CLASS-ERROR | invalid / unknown REST class in URI path
  REST-ERROR | an error response was returned from the REST handler for the given method

Note
  - the `arg` key of the exception hash in the exceptions above contains the HTTP status code of the response
  - exceptions thrown internally by REST handlers are returned directly; no `409` status code is added in the `arg` key of the exception hash

Since
  RestHandler 1.2

## ◆ handleRequest()

hash<HttpResponseInfo> RestHandler::RestHandler::handleRequest | ( | HttpListenerInterface | listener,
|  | Socket | s,
|  | hash< auto > | cx,
|  | hash< auto > | hdr,
|  | *data | b
| ) |  |

called by the HTTP server to handle incoming HTTP requests

Requests will be dispatched to REST classes registered with this object

Parameters

  listener | a listener API object
  s | the Socket object serving the request
  cx | call context hash; this hash will have the following keys: `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information) `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) `url:` a hash of broken-down URL information (as returned from parse_url()) `id:` the unique HTTP connection ID `ssl:` True if the request was encrypted with HTTPS, False if not `listener-id`: the HTTP server listener ID (see HttpServer::HttpServer::getListenerInfo())
  hdr | incoming header hash; all keys will be converted to lower-case, additionally the following keys will be present: `method:` the HTTP method received (ie `"GET"`, `"POST"`, etc) `path:` the HTTP path given in the request, after processing by decode_url() (Qore function) `http_version:` the HTTP version number in the request (either `"1.0"` or `"1.1"`)
  b | message body, if any

Returns
  a hash with the following keys:
  - `"code"`: the HTTP return code (see HttpServer::HttpCodes)
  - `"body"`: the message body to return in the response
  - `"close"`: (optional) set this key to True if the connection should be unconditionally closed when the handler returns
  - `"hdr"`: (optional) set this key to a hash of extra header information to be returned with the response

## ◆ logDebug()

RestHandler::RestHandler::logDebug | ( | string | fmt | ) |

This method is called with debug log messages.

reimplement in subclasses to provide for logging

## ◆ logError()

RestHandler::RestHandler::logError | ( | string | fmt | ) |

This method is called with error log messages.

reimplement in subclasses to provide for logging

## ◆ logInfo()

RestHandler::RestHandler::logInfo | ( | string | fmt | ) |

This method is called with informational log messages.

reimplement in subclasses to provide for logging

## ◆ returnRestException()

hash<HttpHandlerResponseInfo> RestHandler::RestHandler::returnRestException | ( | hash< ExceptionInfo > | ex | ) |
| protected

method that determines how exceptions handling REST requests are returned

by default a `409 Conflict` response is returned with the serialized exception information in the message body