The application uses this as the base class for its resources or as the base class for proxies for its resources (non-intrusive).
The basic operation of resources is as follows:
Note that the web server handles the TRACE method without calling the application.
Public Types | |
|
typedef boost::shared_ptr< resource > | pointer |
| shared ptr | |
|
typedef boost::shared_ptr< const resource > | const_pointer |
| const shared ptr | |
| typedef restcgi::method | method_type |
| method type | |
|
typedef boost::shared_ptr< method_type > | method_pointer |
| method shared ptr | |
| typedef uripp::path | uri_path_type |
| URI path type. | |
| typedef restcgi::uri_info | uri_info_type |
| uri_info type | |
| typedef restcgi::version | version_type |
| version type | |
| typedef restcgi::version_tag | version_tag_type |
| version tag type | |
| typedef restcgi::version_constraint | version_constraint_type |
| version_constraint type | |
Public Member Functions | |
| void | method (method_pointer m) |
| Set method (called before locate() by rest processing). | |
| method_pointer | method () const |
| virtual pointer | locate (uri_path_type &path) |
| virtual void | get_method () |
| virtual void | put_method () |
| virtual void | post_method () |
| virtual void | del_method () |
| virtual void | options_method () |
| virtual void | head_method () |
| int | methods_allowed_mask () const |
| Get methods-allowed mask. | |
| pointer | child () const |
| Get child pointer (MUST set chain_children in root). | |
| pointer | parent () const |
| Get parent pointer (MUST set chain_children in root). | |
| bool | chain_children () const |
| Chain children? | |
| void | child (pointer rthis, pointer cr) |
| Set child. | |
Protected Types | |
| typedef uripp::query | uri_query_type |
| typedef std::pair< uri_path_type, version_type > | id_version_type |
Protected Member Functions | |
| resource (int methods_allowed_mask, bool chain_children=false) | |
| const method_e & | me () const |
| Get method enum, for example method_e::GET (valid after locate()). | |
| const uri_info_type & | uri_info () const |
| version_constraint_type | version_constraint () const |
| Get version constraint (valid after locate()). | |
| void | default_response (bool v) |
| virtual version_type | read (bool veronly) |
| virtual version_type | update (icontent::pointer ic) |
| virtual pointer | create_child () |
| virtual id_version_type | create (icontent::pointer ic) |
| virtual void | del () |
| virtual void | on_responding (status_code_e &sc, response_hdr &rh, content_hdr &ch) |
| virtual void | write (ocontent::pointer oc) |
typedef std::pair<uri_path_type, version_type> restcgi::resource::id_version_type [protected] |
id version pair type
typedef uripp::query restcgi::resource::uri_query_type [protected] |
uri_query type
| restcgi::resource::resource | ( | int | methods_allowed_mask, | |
| bool | chain_children = false | |||
| ) | [protected] |
Construct. The methods that this resource supports must be declared by or'ing the corresponding method_e enums into the mask argument, e.g. method_e::GET | method_e::DEL. This base class has default implementations for OPTIONS and HEAD (if GET is implemented), but they must be put into the given mask by the derived class in order for this class to use them. If chain_children is set in root (MUST be root) all resources located along URI path are linked. This will enable the child() and parent() methods.
Application programming note: THE MASK MUST BE KEPT IN SYNC WITH METHOD IMPLEMENTATIONS!!!
| virtual id_version_type restcgi::resource::create | ( | icontent::pointer | ic | ) | [protected, virtual] |
Create the resource from the input content and save to the application store, returning the id and version information. This is called on the child resource for a POST on th parent. The id is a single-segment URI path and is used to set the content-location response hdr field (the parent path plus this child id). If versioning is not being used a null version can be returned.
Default is to throw internal_server_error.
| exception | application can throw any exception |
| virtual pointer restcgi::resource::create_child | ( | ) | [protected, virtual] |
Create a child resource. This is called for post().
Default is to throw internal_server_error.
| exception | application can throw any exception |
| void restcgi::resource::default_response | ( | bool | v | ) | [protected] |
Set default response. Seting to true causes on_responding() and write() methods to be skipped. This is convenient for resources that handle multiple methods when some do not require a custom response. (See above.)
| virtual void restcgi::resource::del | ( | ) | [protected, virtual] |
Delete the resource from the application store.
Default is to throw internal_server_error.
| exception | application can throw any exception |
| virtual void restcgi::resource::del_method | ( | ) | [virtual] |
Delete this resource.
Unless overridden (usually not necessary), this will call the following methods:
| virtual void restcgi::resource::get_method | ( | ) | [virtual] |
Respond with a representation of this resource in the output content.
Unless overridden (usually not necessary), this will call the following methods:
| virtual void restcgi::resource::head_method | ( | ) | [virtual] |
Respond with header fields the same as if this were a get() but do not return output content. The application may be able to optimize the read for the HEAD case.
Unless overridden (usually not necessary), this will call the following methods:
| virtual pointer restcgi::resource::locate | ( | uri_path_type & | path | ) | [virtual] |
Locate the resource at the given path relative to this and update path. This method provides the main means for navigating to the resource specified by the client in terms of the URI path. The application should organize its resources in a hierarchy (basic REST architecture) which can be descended by repeated calls to this method on the returned resources and the updated path (typically using pop_front() at each step).
Result possibilities:
The default is to perform the method on this, but will result in bad_request if path is not empty.
| exception | restcgi exceptions are rethrown, others wrapped and rethrown as a bad_request |
| method_pointer restcgi::resource::method | ( | ) | const [inline] |
Get method (valid before and after locate()).
| virtual void restcgi::resource::on_responding | ( | status_code_e & | sc, | |
| response_hdr & | rh, | |||
| content_hdr & | ch | |||
| ) | [protected, virtual] |
Modify status code and response and content hdrs prior to responding. This class sends the response but calls this before doing it so that the derived class can add header fields, e.g. content-type. The version information, if any has already been added to the hdrs. Note methods that do not write output content, e.g. del(), will ignore any changes to the content_hdr. In other words, the content-type can always be set regardless of method type.
"hello, world" example (see also write()). This is all that is needed here:
ch.content_type("text/plain");
If needed, the method type can be checked as follows:
if (me() == method_e::GET) ...
Default is to do nothing (use status code and hdrs as they are).
| virtual void restcgi::resource::options_method | ( | ) | [virtual] |
Respond with the "options" available for the resource and, optionally, send a representation of the "options" in the output content.
The required, minimum response, and the default behavior of this base class, is to return the Allow header field based on the "methods allowed mask" set at construction and not send content (note that Content-Length must be explicitly set to 0). See RFC. The special case of the URI path "*", essentially a "ping", is handled elsewhere and does not result in a call to any of the resource objects.
Unless overridden (usually not necessary), this will call the following methods:
| virtual void restcgi::resource::post_method | ( | ) | [virtual] |
Create a subordinate (child) resource with the input content and, optionally, send a representation of the child resource in the output content. Note that the URI path points to the containing (parent) resource which is this resource.
Unless overridden (usually not necessary), this will call the following methods:
| virtual void restcgi::resource::put_method | ( | ) | [virtual] |
Update the resource with the input content and, optionally, send a representation of the updated resource in the output content. The resource must already exist and this is designed to change one or more of its attributes.
Unless overridden (usually not necessary), this will call the following methods:
| virtual version_type restcgi::resource::read | ( | bool | veronly | ) | [protected, virtual] |
Read the attributes of the resource from the application store and return the current version information. This is called for get(), put(), del(), and head(). But, note that for del() this is only called if there is a version constraint and then veronly is set to true to indicate that all the attributes are not needed. For head() the application may be able to optimize the resource read. If versioning is not being used a null version can be returned and constraints will be ignored.
Default is to throw internal_server_error.
| exception | application can throw any exception |
| virtual version_type restcgi::resource::update | ( | icontent::pointer | ic | ) | [protected, virtual] |
Update the attributes of the resource and save to the application store, returning the new version information. This is called for put(). If versioning is not being used a null version can be returned.
Default is to throw internal_server_error.
| exception | application can throw any exception |
| const uri_info_type& restcgi::resource::uri_info | ( | ) | const [inline, protected] |
Get URI info (valid after locate()).
| virtual void restcgi::resource::write | ( | ocontent::pointer | oc | ) | [protected, virtual] |
Write the resouce as an output content stream. Called by get(), post() on the child, and put(). Note that exceptions are ignored here because the response hdr has already been sent.
"hello, world" example, continued:
*oc << "hello, world!";
Default is to do nothing (send no content).
1.4.7