the base abstract class for REST handler classes More...

#include <RestHandler.qm.dox.h>

Inheritance diagram for RestHandler::AbstractRestClass:

Public Member Methods
	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...

Public Attributes
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
*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...

Detailed Description

the base abstract class for REST handler classes

Member Function Documentation

◆ dispatch()

private hash< HttpServer::HttpHandlerResponseInfo > RestHandler::AbstractRestClass::dispatch	(	RestHandler	rh,
		string	mn,
		*hash< auto >	ah,
		hash< auto >	cx
	)

inline

this method is called to dispatch requests on the given object

Parameters

rh	the RestHandler object
mn	the method name
ah	the holds URI and / or message body arguments for the REST call; if a request has both URI query arguments and message body arguments, then this value will be a combination of URI query arguments and deserialized message body arguments with URI query arguments taking precedence over the message body arguments
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())

Returns: the return value is the same as the return value for HttpServer::AbstractHttpRequestHandler::handleRequest()

◆ doGetPossibleSubClasses()

*hash< string, bool > RestHandler::AbstractRestClass::doGetPossibleSubClasses	(	hash< auto >	cx,
		*hash< auto >	ah
	)

private

returns a set of possible subclasses for a particular request

Parameters

cx	the HTTP call context hash
ah	the holds URI and / or message body arguments for the REST call; if a request has both URI query arguments and message body arguments, then this value will be a combination of URI query arguments and deserialized message body arguments with URI query arguments taking precedence over the message body arguments

Returns: a set of possible subclasses for the request

Since

RestHandler 1.3
RestHandler 1.6 added the ah argument

◆ subClass()

*AbstractRestClass RestHandler::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

Parameters

name	the name of the subclass
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:` a hash of header information as returned by Qore::Socket::readHTTPHeader() `body:` the deserialized message body `aih:` a hash of `"Accept"` values
args	the holds URI and / or message body arguments for the REST call; if a request has both URI query arguments and message body arguments, then this value will be a combination of URI query arguments and deserialized message body arguments with URI query arguments taking precedence over the message body arguments

Returns: an object corresponding to the name argument or NOTHING if none can be matched

This method first looks for a static subclass in the class_hash member (as populated by addClass() for example), and then if no match is found calls subClassImpl() for a potential dynamic lookup.

Note: it's recommended to reimplement subClassImpl() instead of this method to leave the static subclass lookup in place

◆ subClassImpl()

*AbstractRestClass RestHandler::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

Parameters

name	the name of the subclass
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:` a hash of header information as returned by Qore::Socket::readHTTPHeader() `body:` the deserialized message body `aih:` a hash of `"Accept"` values
args	the holds URI and / or message body arguments for the REST call; if a request has both URI query arguments and message body arguments, then this value will be a combination of URI query arguments and deserialized message body arguments with URI query arguments taking precedence over the message body arguments

Returns: an object corresponding to the name argument or NOTHING if none can be matched; this base class method returns NOTHING by default; override in subclasses to provide programmatic support for REST subclasses

Note: Use addClass() for fast static subclass lookups

◆ unknownSubClassError()

hash< HttpServer::HttpHandlerResponseInfo > RestHandler::AbstractRestClass::unknownSubClassError	(	string	cls_name,
		hash< auto >	cx,
		*hash< auto >	ah
	)

private

returns a 404 Not Found response when a request tries to access an unknown subclass

Parameters

cls_name	the URI path element that could not be matched to a REST subclass
cx	the HTTP call context hash
ah	the holds URI and / or message body arguments for the REST call; if a request has both URI query arguments and message body arguments, then this value will be a combination of URI query arguments and deserialized message body arguments with URI query arguments taking precedence over the message body arguments

Returns: REST response information

Since

RestHandler 1.3 added the cx argument
RestHandler 1.6 added the ah argument

Public Member Methods

Public Attributes

Private Member Methods

Detailed Description

Member Function Documentation

◆ dispatch()

◆ doGetPossibleSubClasses()

◆ subClass()

◆ subClassImpl()

◆ unknownSubClassError()