Qore RestHandler Module Reference  1.5
RestHandler::RestHandler Class Reference

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

Inheritance diagram for RestHandler::RestHandler:

Public Member Methods

 constructor (*HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator())
 create the object optionally with the given HttpServer::AbstractAuthenticator 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)
 default implementation is empty; this method is called with debug log messages More...
 
 logError (string fmt)
 default implementation is empty; this method is called with error log messages More...
 
 logInfo (string fmt)
 default implementation is empty; 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
 
- Public Member Methods inherited from RestHandler::AbstractRestClass
 addClass (AbstractRestClass cls)
 adds a REST class to the handler
 
hash< HttpServer::HttpHandlerResponseInfohandleRequest (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 Methods

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, AbstractRestClassclass_hash
 class hash: name -> AbstractRestClass
 
const RestBasicMethodSet = map {$1: True}
 set of REST class method names based on basic HTTP methods
 

Private Member Methods

 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...
 
- Private Member Methods inherited from RestHandler::AbstractRestClass
hash< HttpServer::HttpHandlerResponseInfodispatch (RestHandler rh, string mn, *hash< auto > ah, hash< auto > cx)
 this method is called to dispatch requests on the given object More...
 
hash< HttpServer::HttpHandlerResponseInfodispatchStream (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::HttpHandlerResponseInfounknownSubClassError (string cls_name, hash< auto > cx)
 returns a 404 Not Found response when a request tries to access an unknown subclass More...
 

Private Attributes

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:

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

Member Function Documentation

◆ constructor()

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

create the object optionally with the given HttpServer::AbstractAuthenticator

Parameters
auththe 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
validatora 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
methodthe HTTP method; if the the method is unknown, an UNKNOWN-REST-METHOD exception is raised
paththe URI path for the call
bodythe arguments to the call; note that arguments are combined with any arguments provided in path
cxsimulated HTTP call context hash
Returns
the response value of the REST method
Exceptions
UNKNOWN-REST-METHODthe HTTP method is unknown / unsupported
INVALID-URI-PATHURI cannot be parsed
INVALID-REST-ARGSinvalid REST action
REST-CLASS-ERRORinvalid / unknown REST class in URI path
REST-ERRORan 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
listenera listener API object
sthe Socket object serving the request
cxcall 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())
hdrincoming 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")
bmessage 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)

default implementation is empty; this method is called with debug log messages

reimplement in subclasses to provide for logging

◆ logError()

RestHandler::RestHandler::logError ( string  fmt)

default implementation is empty; this method is called with error log messages

reimplement in subclasses to provide for logging

◆ logInfo()

RestHandler::RestHandler::logInfo ( string  fmt)

default implementation is empty; this method is called with informational log messages

reimplement in subclasses to provide for logging

◆ returnRestException()

hash<HttpHandlerResponseInfo> RestHandler::RestHandler::returnRestException ( hash< ExceptionInfo >  ex)
private

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