All Classes Namespaces Functions Variables Groups Pages
RestHandler::AbstractRestStreamRequestHandler Class Referenceabstract

the base abstract class for REST stream request handlers More...

## Public Member Functions

| constructor (hash n_cx, *hash n_ah)
| creates the object with the given arguments More...
*code | getPersistentClosedNotification ()
| returns a callable value in case a persistent connection is in progress; NOTHING if not; this method in the base class returns NOTHING
hash | getResponseHeaderMessage ()
| this method returns the response message description hash by calling getResponseHeaderMessageImpl() More...
abstract hash | getResponseHeaderMessageImpl ()
| this method should return the response message description hash More...
*int | getTimeout ()
| returns the timeout in milliseconds or NOTHING if no timeout is set
bool | isPersistent ()
| returns True if the connection is persistent; this method in the base class returns False by default
nothing | recv (hash v)
| this method provides the callback method for receiving chunked data by calling recvImpl() More...
abstract nothing | recvImpl (hash v)
| abstract callback method for receiving chunked data More...
any | send ()
| this method provides the callback method for sending chunked data by calling sendImpl() More...
abstract any | sendImpl ()
| abstract callback method for sending chunked data More...
| setTimeout (timeout n_timeout_ms)
| sets the internal socket I/O timeout value in ms
| streamError (hash n_ex)
| registers stream errors in the send operation with the stream handler if no error is already present

## Private Attributes

*hash | ah
| call argument hash
hash | cx
| call context hash
*hash | ex
| if an exception is raised in a callback then the exception hash is saved here
hash | rhdr
| headers to add in the response
*int | timeout_ms
| socket I/O timeout in milliseconds

## Detailed Description

the base abstract class for REST stream request handlers

The calling order is as follows:

- constructor(): this is called when the request is received; then context argument contains the request header along with other information
- recv(): this is called once for each HTTP chunk (if data is sent chunked), and then once with any message trailer. If data is sent non-chunked, then this method is called with the monolithic message body and then again with NOTHING to signify the end of the transfer and to simulate a chunked transfer. Subclasses should re-implement recvImpl() which is called by this method
- getResponseHeaderMessage(): this is called after the message body has been received to get the response headers and optionally a message body. Subclasses should reimplement getResponseHeaderMessageImpl() which is called by this method
- send(): this is called if no message body is returned by getResponseHeaderMessage(); each time this method returns data, the data is sent in a response chunk; when this method returns NOTHING, then no more data is sent. Subclasses should re-implement sendImpl() which is called by this method

## Member Function Documentation

RestHandler::AbstractRestStreamRequestHandler::constructor | ( | hash | n_cx,
|  | *hash | n_ah
| ) |  |

creates the object with the given arguments

Parameters

  n_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 parseURL())
  - `id:` the unique HTTP connection ID
  - `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo())
  - `user:` the current RBAC username (if any)
  - `hdr:` a hash of header information as returned by Qore::Socket::readHTTPHeader()
  - `body:` the deserialized message body
  - `aih:` a hash of `"Accept"` values

  n_ah | any URI arguments in the request

hash RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage | ( |  | ) |

this method returns the response message description hash by calling getResponseHeaderMessageImpl()

Returns
  a hash with the following keys:
  - `"code"`: the HTTP return code (see HttpServer::HttpCodes)
  - `"body"`: the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  - `"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

Note
  this method is called after the message body has been received

abstract hash RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessageImpl | ( |  | ) |

pure virtual

this method should return the response message description hash

Returns
  a hash with the following keys:
  - `"code"`: the HTTP return code (see HttpServer::HttpCodes)
  - `"body"`: the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  - `"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

Note
  this method is called after the message body has been received

nothing RestHandler::AbstractRestStreamRequestHandler::recv | ( | hash | v | ) |

this method provides the callback method for receiving chunked data by calling recvImpl()

Parameters

  v

  the first time this method is called with a hash of the message headers in the `"hdr"` key, and then with any message body in the `"data"`; if a chunked HTTP message is received, then this method is called once for each chunk; when the message has been received, then this method is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  - `"data"`: the string or binary data, or, in the case of a non-chunked request, the already decoded and deserialized request body, in which case the `"deserialized"` key will be True
  - `"chunked"`: True if the data was received with chunked transfer encoding, False if not
  - `"deserialized"`: present and set to True if a non-chunked request was received, and the body has already been deserialized
  Header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

abstract nothing RestHandler::AbstractRestStreamRequestHandler::recvImpl | ( | hash | v | ) |

pure virtual

abstract callback method for receiving chunked data

Parameters

  v

  the first time this method is called with a hash of the message headers in the `"hdr"` key, and then with any message body in the `"data"`; if a chunked HTTP message is received, then this method is called once for each chunk; when the message has been received, then this method is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  - `"data"`: the string or binary data, or, in the case of a non-chunked request, the already decoded and deserialized request body, in which case the `"deserialized"` key will be True
  - `"chunked"`: True if the data was received with chunked transfer encoding, False if not
  - `"deserialized"`: present and set to True if a non-chunked request was received, and the body has already been deserialized
  Header or trailer data is placed in a hash with the following keys:
  - `"hdr"`: this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  - `"obj"`: this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

any RestHandler::AbstractRestStreamRequestHandler::send | ( |  | ) |

this method provides the callback method for sending chunked data by calling sendImpl()

Returns
  The chunked HTTP data to send; this method must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be returned or simply NOTHING which will close the chunked message

abstract any RestHandler::AbstractRestStreamRequestHandler::sendImpl | ( |  | ) |

pure virtual

abstract callback method for sending chunked data

Returns
  The chunked HTTP data to send; this method must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be returned or simply NOTHING which will close the chunked message