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

| addClass (AbstractRestClass cls)
| adds a REST class to the handler
| constructor (*HttpServer::AbstractAuthenticator auth)
| create the object optionally with the given HttpServer::AbstractAuthenticator More...
hash | get (hash cx, *hash ah)
| default get handler
hash | handleRequest (HttpListenerInterface listener, Socket s, 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 mn, *hash ah, hash cx)
| this method is called to dispatch requests on the given object
private hash | dispatchStream (HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash ah, hash cx)
| this method is called to dispatch streamed requests on the given object
hash | handleRequest (HttpListenerInterface listener, RestHandler rh, Socket s, *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 n_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:

- 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

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

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

hash RestHandler::RestHandler::handleRequest | ( | HttpListenerInterface | listener,
|  | Socket | s,
|  | 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

  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 parseURL())
  - `id:` the unique HTTP connection ID
  - `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo())
  - `user:` the current RBAC username (if any)

  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