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

#include <RestHandler.qm.dox.h>

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...

	constructor (Logger::Logger logger, *HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator(logger))
	create the object optionally with the given Logger and authenticator More...

private 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< 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 Methods inherited from RestHandler::AbstractRestClass
	addClass (AbstractRestClass cls)
	adds a REST class to the handler

private 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...

private 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< 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

abstract string	name ()
	this provides the name of the REST class

*AbstractRestClass	subClass (string name, hash< auto > cx, *hash< auto > 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...

*AbstractRestClass	subClassImpl (string name, hash< auto > cx, *hash< auto > 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...

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, AbstractRestClass >	class_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< auto >	errorResponseHeaders (hash< auto > cx)
	Retrieves headers for an error response. More...

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< string, bool >	doGetPossibleSubClasses (hash< auto > cx, *hash< auto > ah)
	returns a set of possible subclasses for a particular request More...

hash< HttpServer::HttpHandlerResponseInfo >	unknownSubClassError (string cls_name, hash< auto > cx, *hash< auto > ah)
	returns a 404 Not Found response when a request tries to access an unknown subclass More...

Private 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:

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

◆ errorResponseHeaders()

*hash< auto > RestHandler::RestHandler::errorResponseHeaders ( hash< auto > cx )

private

Retrieves headers for an error response.

Returns: the base method returns NOTHING; override to return additional headers for an error response

◆ 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
	)

inline

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 )

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

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods

Private Attributes

Detailed Description

Member Function Documentation

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ errorResponseHeaders()

◆ handleExternalRequest()

◆ handleRequest()

◆ logDebug()

◆ logError()

◆ logInfo()

◆ returnRestException()