Qore RestHandler Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
RestHandler::RestHandler Class Reference

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

Inheritance diagram for RestHandler::RestHandler:

Public Member Functions

 addClass (AbstractRestClass cls)
 adds a REST class to the handler
 
 constructor (*AbstractAuthenticator auth)
 create the object optionally with the given AbstractAuthenticator More...
 
hash handleRequest (hash cx, hash 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; reimplement in subclasses to provide for logging
 
 logError (string fmt)
 default implementation is empty; this method is called with error log messages; reimplement in subclasses to provide for logging
 
 logInfo (string fmt)
 default implementation is empty; this method is called with informational log messages; reimplement in subclasses to provide for logging
 
string name ()
 returns the name of the root REST class
 
 removeRootPath (reference path)
 default implementation is empty
 
 requestDeserializationError (hash hdr, hash cx, string body)
 default implementation is empty
 
 responseSerializationError (hash cx, *hash aih, hash rv)
 default implementation is empty
 
- Public Member Functions inherited from RestHandler::AbstractRestClass
private hash dispatch (RestHandler rh, *string oname, string mn, *hash ah, hash cx)
 this method is called to dispatch requests on the given object
 
hash handleRequest (RestHandler rh, *list cl, string mn, hash cx, *hash args)
 this method is called by the RestHandler class to match the right object with incoming requests
 
*AbstractRestClass subClass (string name, hash cx, *hash args)
 this method will be called to find a sub-class (ie with GET /invoices/1 - if this class represents "invoices", then subClass("1") will be called to return invoice 1; return NOTHING if the object doesn't exist More...
 
private hash unknownSubClassError (string name)
 throws a "REST-CLASS-ERROR" exception when a request tries to access an unknown subclass
 

Static Public Member Functions

static hash makeResponse (int code, any body, *hash 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
 
const MimeDataTypes
 supported mime types for de/serializing responses
 

Private Member Functions

Mutex mx ()
 mutex lock
 

Private Attributes

hash ch
 class hash: name -> AbstractRestClass
 

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

RestHandler::RestHandler::constructor ( *AbstractAuthenticator  auth)

create the object optionally with the given AbstractAuthenticator

Parameters
auththe authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
hash RestHandler::RestHandler::handleRequest ( hash  cx,
hash  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
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 parseURL())
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • user: the current RBAC username (if any)
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