RestHandler::AbstractRestClass Class Reference

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
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
*AbstractRestClass	subClassImpl (string name, hash< auto > cx, *hash< auto > args)
	this method will be called to find a sub-class

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< HttpServer::HttpHandlerResponseInfo >	dispatch (RestHandler rh, string mn, *hash< auto > ah, hash< auto > cx)
	this method is called to dispatch requests on the given object
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< string, bool >	doGetPossibleSubClasses (hash< auto > cx, *hash< auto > ah)
	returns a set of possible subclasses for a particular request
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

Detailed Description

the base abstract class for REST handler classes

Member Function Documentation

dispatch()

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

private

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	the call context hash; see REST Handler Context Argument for information about this value

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 call context hash; see REST Handler Context Argument for information about this value
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

For example 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	the call context hash; see REST Handler Context Argument for information about this value
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

For example 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	the call context hash; see REST Handler Context Argument for information about this value
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 call context hash; see REST Handler Context Argument for information about this value
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