restcgi::rest Class Reference

List of all members.

Detailed Description

REST processing for application resources.

This uses the underlying CGI functionality of method and its associated classes to call classes derived from the resource base class when an HTTP request is received.

The basic model is that the application uses the resource class as a base classe to code its hierarchically contained resources, or their proxies. The process() method of this class then handles all framework processing except for the method responses for the resources. These are the steps, implemented as overridable methods:

  1. special_case(): Check for and send responses for special cases.
  2. If not special cases:
    1. locate(): Locate resource specified by the URI path in the method.
    2. apply(): Call the appropriate method on the resource.
  3. on_exception(): Exception handler to send the error response using the provided content templates (ctmpl).

Example code using FastCGI: The application-specific class myrootrsc is derived from the resource class to represent its root resource.

 #include <fcgio.h>
 #include <restcgi/endpoint.h>
 #include <restcgi/rest.h>
 #include "myrootrsc.h"
 int main(int argc, char* argv[]) {
     // FastCGI initialization.
     FCGX_Request request;
     FCGX_InitRequest(&request, 0, 0);
     while (FCGX_Accept_r(&request) >= 0) {
         // FastCGI request setup.
         fcgi_streambuf fisbuf(;
         std::istream is(&fisbuf);
         fcgi_streambuf fosbuf(request.out);
         std::ostream os(&fosbuf);
         // restcgi processing. Note rest::process() catches exceptions and 
         // translates them to HTTP error status codes (derive from rest to customize).
         restcgi::endpoint::method_pointer m = restcgi::endpoint::create(is, os)->receive();
         restcgi::resource::pointer root(new myrootrsc());
         restcgi::rest().process(m, root);
     return 0;
 void set_env(char** penv) {
     char buf[4000];
     for (; *penv; ++penv) {
         ::strncpy(buf, *penv, sizeof(buf));
         buf[sizeof(buf) - 1] = 0; // ensure terminated
         char* p = ::strchr(buf, '=');
         const char* v = "";
         if (p) {*p = 0; v = p + 1;}
         ::setenv(buf, v, 1); // makes copy of buf, v
See also:
resource, method

Public Types

typedef restcgi::method method_type
 method type
typedef boost::shared_ptr<
 method shared ptr
typedef restcgi::resource resource_type
 resource type
typedef boost::shared_ptr<
 resource shared ptr
typedef std::map< std::string,
 virtual hosts resources type

Public Member Functions

 rest ()
void process (method_pointer m, resource_pointer root, const sc_ctmpls &sccts=sc_ctmpls())
 Perform processing of the given method starting at the given root resource.
void process (method_pointer m, const vhosts_resources_type &vhrs)
 Perform processing of the given method for the root resouce that matches the HTTP_HOST header.
method_pointer method () const
 Get method (valid after process()).
resource_pointer root () const
 Get root resource (valid after process()).
resource_pointer resource () const
 Get resource (valid after locate()).

Static Public Member Functions

static bool special_case (method_pointer m)
 Default special case.
static resource_pointer locate (method_pointer m, resource_pointer &r)
 Default locate.
static void apply (method_pointer m, resource_pointer r)
 Default apply.
static void on_exception (method_pointer m, const sc_ctmpls &sccts)
 Default exception handler.

Protected Member Functions

virtual bool special_case ()
virtual resource_pointer locate (resource_pointer &r)
virtual void apply ()
virtual void on_exception (const sc_ctmpls &sccts)

Member Function Documentation

virtual void restcgi::rest::apply (  )  [protected, virtual]

Apply the method to the resource. This examines the method type and calls the corresponding resource method to create a response, e.g. calls resource::get() if the method is a GET.

See also:
exception many different kinds if error in processing

virtual resource_pointer restcgi::rest::locate ( resource_pointer r  )  [protected, virtual]

Locate the resource for the method's URI path. This will start with the root and call resource::locate() and the resource it returns, transitively, until either no resource is returned (the previous is used in this case) or uri path is empty. The resource arg should be updated as the algorithm progresses so it is left at the last known good point if an exception is thrown. Sets resource pointer member as it progresses.

See also:

virtual void restcgi::rest::on_exception ( const sc_ctmpls sccts  )  [protected, virtual]

Handle response for exception during processing. This first tests that a method has been received and that there is no response yet. It (internally) rethrows the last exception and then produces an appropriate response based on the exception and the provided content template for the exception based on its status code.

See also:

void restcgi::rest::process ( method_pointer  m,
const vhosts_resources_type vhrs 

Perform processing of the given method for the root resouce that matches the HTTP_HOST header.

This uses the domain name/IP addr plus the ":<port>" if any. (See also other process()).

void restcgi::rest::process ( method_pointer  m,
resource_pointer  root,
const sc_ctmpls sccts = sc_ctmpls() 

Perform processing of the given method starting at the given root resource.

Uses the optional templates on exceptions. See class description. This does not throw any exception.

virtual bool restcgi::rest::special_case (  )  [protected, virtual]

Detect and handle special case methods and return whether special case or not. This handles OPTIONS "*" by sending an empty response ("ping"-like behavior).

Generated on Fri May 15 11:27:12 2009 for restcgi by  doxygen 1.4.7