Qore RestHandler Module Reference 1.6.2
Loading...
Searching...
No Matches
RestHandler::AbstractRestClass Class Referenceabstract

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

#include <RestHandler.qm.dox.h>

Inheritance diagram for RestHandler::AbstractRestClass:
[legend]

Public Member Methods

 addClass (AbstractRestClass cls)
 adds a REST class to the handler
 
hash< HttpServer::HttpHandlerResponseInfohandleRequest (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 More...
 
*AbstractRestClass subClassImpl (string name, hash< auto > cx, *hash< auto > args)
 this method will be called to find a sub-class More...
 

Public Attributes

hash< string, AbstractRestClassclass_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::HttpHandlerResponseInfodispatch (RestHandler rh, string mn, *hash< auto > ah, hash< auto > cx)
 this method is called to dispatch requests on the given object More...
 
hash< HttpServer::HttpHandlerResponseInfodispatchStream (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 More...
 
hash< HttpServer::HttpHandlerResponseInfounknownSubClassError (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()

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
rhthe RestHandler object
mnthe method name
ahthe 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
cxcall context hash; this hash will have the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • 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 Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
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
cxthe HTTP call context hash with the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • arg_path: a list of string URI path segments for any after the current node
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • 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 Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
ahthe 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

◆ 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
namethe name of the subclass
cxcall context hash; this hash will have the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • arg_path: a list of string URI path segments for any after the current node
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • 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 Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
argsthe 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
namethe name of the subclass
cxcall context hash; this hash will have the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • arg_path: a list of string URI path segments for any after the current node
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • 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 Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
argsthe 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_namethe URI path element that could not be matched to a REST subclass
cxthe HTTP call context hash with the following keys:
  • aih: a hash of "Accept" values, keys are hash values, values are boolean True
  • arg_path: a list of string URI path segments for any after the current node
  • body: the deserialized message body
  • hdr: a hash of header information as returned by Socket::readHTTPHeader()
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • peer-info: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo())
  • 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 Socket::getSocketInfo())
  • ssl: True if the request was encrypted with HTTPS, False if not
  • url: a hash of broken-down URL information (as returned from parse_url())
  • user: the current authorized username (if any)
ahthe 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