Loading...
Searching...
No Matches
RestHandler::AbstractRestClass Class Referenceabstract

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

Inheritance diagram for RestHandler::AbstractRestClass:
[legend]

## Public Member Functions

| 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

## Protected Member Functions

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

protected

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:
  - `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
| ) |  |

protected

returns a set of possible subclasses for a particular request

Parameters

  cx

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

  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

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

  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

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

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

protected

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

  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