RestHandler::AbstractRestStreamRequestHandler Class Reference

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

#include <RestHandler.qm.dox.h>

Public Member Methods
	constructor (hash< auto > cx, *hash< auto > ah)
	creates the object with the given arguments
*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< HttpServer::HttpHandlerResponseInfo >	getResponseHeaderMessage ()
	this method returns the response message description hash by calling getResponseHeaderMessageImpl()
abstract hash< auto >	getResponseHeaderMessageImpl ()
	this method should return the response message description hash
*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< auto > v)
	this method provides the callback method for receiving chunked data by calling recvImpl()
abstract nothing	recvImpl (hash< auto > v)
	abstract callback method for receiving chunked data
auto	send ()
	this method provides the callback method for sending chunked data by calling sendImpl()
abstract auto	sendImpl ()
	abstract callback method for sending chunked data
	setTimeout (timeout n_timeout_ms)
	sets the internal socket I/O timeout value in ms
	streamError (hash< auto > n_ex)
	registers stream errors in the send operation with the stream handler if no error is already present

Private Attributes
*hash< auto >	ah
	call argument hash
hash< auto >	cx
	call context hash
*hash< auto >	ex
	if an exception is raised in a callback then the exception hash is saved here
hash< auto >	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

constructor()

RestHandler::AbstractRestStreamRequestHandler::constructor	(	hash< auto >	cx,
		*hash< auto >	ah
	)

creates the object with the given arguments

Parameters

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)

ah

any URI arguments in the request

getResponseHeaderMessage()

hash< HttpServer::HttpHandlerResponseInfo > RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage

(

)

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

Returns

a HttpHandlerResponseInfo 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

getResponseHeaderMessageImpl()

abstract hash< auto > RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessageImpl

(

)

this method should return the response message description hash

Returns

an HttpServer::HttpHandlerResponseInfo 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

recv()

nothing RestHandler::AbstractRestStreamRequestHandler::recv

(

hash< auto >

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)

recvImpl()

abstract nothing RestHandler::AbstractRestStreamRequestHandler::recvImpl

(

hash< auto >

v

)

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)

send()

auto 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

sendImpl()

abstract auto RestHandler::AbstractRestStreamRequestHandler::sendImpl

(

)

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