Qore WebUtil Module Reference  1.0
 All Classes Namespaces Functions Variables Groups Pages
WebUtil Namespace Reference

the WebUtil namespace contains all the objects in the WebUtil module More...

Classes

class  FileHandler
 this class serves files from the file system based on a root location More...
 
class  FileTemplate
 manages a template resource that may need to be recompiled if the file is updated in the filesystem; used by WebUtil::TemplateFileManager More...
 
class  StaticTemplateManager
 A container for holding static text templates (ie that do not change once created in the template manager) with mixed text and Qore code. More...
 
class  TemplateFileManager
 this class manages templates based on files More...
 
class  TextTemplateBase
 this is the base class for all template Program container classes More...
 

Functions

 constructor (string file_root, string url_root="/", *hash opt)
 create the object optionally with the given AbstractAuthenticator More...
 
hash fileError (hash cx, hash sh)
 this method returns a 400 "Bad Request" error code when a file should be served that's not a regular file More...
 
hash handleRequest (hash cx, hash hdr, *data body)
 this method calls handleRequestImpl() to service the request, if handleRequestImpl() returns NOTHING, then it tries to automatically serve a matching template or files from the filesystem or serve the default resource if no resource can be matched More...
 
*hash handleRequestImpl (reference cx, hash hdr, *data body)
 this method is called by this class's handleRequest() before trying to service the request automatically based on file resources More...
 
 logDebug (string fmt)
 default implementation is empty; this method is called with debug log messages; reimplement in subclasses to provide for logging
 
 logError (string fmt)
 default implementation is empty; this method is called with error log messages; reimplement in subclasses to provide for logging
 
 logInfo (string fmt)
 default implementation is empty; this method is called with informational log messages; reimplement in subclasses to provide for logging
 
*hash renderDirectory (hash cx, string path)
 this method is called when a directory should be rendered More...
 
hash serverError (hash cx, hash ex)
 this method returns a 500 "Internal Server Error" error code when an exception occurs More...
 
WebUtil::FileHandler
HttpServer::AbstractUrlHandler,
WebUtil::TemplateFileManager 
stm ()
 static templates
 
hash unhandledRequest (hash cx, hash hdr, *data body)
 this method returns a 404 "Not Found" error code to GET requests and a 501 "Not Implemented" error code to all other requests More...
 

Detailed Description

the WebUtil namespace contains all the objects in the WebUtil module

Function Documentation

WebUtil::constructor ( string  file_root,
string  url_root = "/",
*hash  opt 
)

create the object optionally with the given AbstractAuthenticator

Parameters
file_rootthe filesystem root directory for serving files
url_rootthe root part of the URL path without the leading "/"
optionsan optional with one or more of the following option keys:
  • default_target: the default relative path to use if a request cannot be satisfied
  • po: the Program parse options for the template file programs
  • psetup: an optional closure or call reference taking a single Program argument to be called when initializing template programs to set up a custom template API, etc
  • auth: the authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
  • error_level: the level of error reporting (0, 1, or 2)
hash WebUtil::fileError ( hash  cx,
hash  sh 
)
private

this method returns a 400 "Bad Request" error code when a file should be served that's not a regular file

this method is called when a file cannot be served because it's not a regular file; reimplement this method in subclasses to customize error handling

hash WebUtil::handleRequest ( hash  cx,
hash  hdr,
*data  body 
)

this method calls handleRequestImpl() to service the request, if handleRequestImpl() returns NOTHING, then it tries to automatically serve a matching template or files from the filesystem or serve the default resource if no resource can be matched

Parameters
cxcall 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 Qore::parse_url())
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • user: the current RBAC username (if any)
hdrincoming header hash; all keys will be converted to lower-case, additionally the following keys will be present:
  • method: the HTTP method received (ie "GET", "POST", etc)
  • path: the HTTP path given in the request, after processing by Qore::decode_url()
  • http_version: the HTTP version number in the request (either "1.0" or "1.1")
bodymessage body, if any
Returns
a hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response
  • "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

The following keys are added to the cx argument when calling handleRequestImpl():

  • resource_path: the relative path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed)
  • url_root: the root URL
  • file_root: the root directory for serving files
  • isregex: if the url_root string is a regular expression or not (this is always False when this class is used)
  • hdr: this is added to the cx argument directly from the hdr argument, however it also includes the "params" key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()

If handleRequestImpl() returns NOTHING and the requested path cannot be matched and served, then unhandledRequest() is called to handle the error

*hash WebUtil::handleRequestImpl ( reference  cx,
hash  hdr,
*data  body 
)
private

this method is called by this class's handleRequest() before trying to service the request automatically based on file resources

Parameters
cxcall 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 Qore::parse_url())
  • id: the unique HTTP connection ID
  • listener-id: the HTTP server listener ID (see HttpServer::getListenerInfo())
  • user: the current RBAC username (if any)
  • resource_path: the relative path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed)
  • url_root: the root URL
  • file_root: the root directory for serving files
  • isregex: if the url_root string is a regular expression or not (this is always False when this class is used)
  • hdr: this is a copy of the hdr argument, however it also includes the "params" key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()
hdrincoming header hash; all keys will be converted to lower-case, additionally the following keys will be present:
  • method: the HTTP method received (ie "GET", "POST", etc)
  • path: the HTTP path given in the request, after processing by Qore::decode_url()
  • http_version: the HTTP version number in the request (either "1.0" or "1.1")
  • params: holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()
bodymessage body, if any
Returns
a hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response
  • "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 has the following additional keys in the cx hash: resource_path, url_root, and isregex
  • the default implementation simply returns NOTHING all requests; reimplement this method in a subclass to provide the required functionality
*hash WebUtil::renderDirectory ( hash  cx,
string  path 
)

this method is called when a directory should be rendered

if this method returns NOTHING then any default_target will be used, so to turn off directory rendering, subclass this class and have the reimplemented method return NOTHING

hash WebUtil::serverError ( hash  cx,
hash  ex 
)
private

this method returns a 500 "Internal Server Error" error code when an exception occurs

this method is called when an exception occurs; reimplement this method in subclasses to customize error handling

hash WebUtil::unhandledRequest ( hash  cx,
hash  hdr,
*data  body 
)
private

this method returns a 404 "Not Found" error code to GET requests and a 501 "Not Implemented" error code to all other requests

this method is called when a request cannot be handled; reimplement this method in subclasses to customize unhandled request error handling