Provided by: libweb-mrest-perl_0.290-1_all 
NAME
App::MREST::Dispatch - Resource handlers
DESCRIPTION
Your application should not call any of the routines in this module directly. They are
called by Web::MREST::Resource during the course of request processing. What your
application can do is provide its own resource handlers.
The resource handlers are called as ordinary functions with a sole argument: the MREST
context.
INITIALIZATION/RESOURCE DEFINITIONS
In this section we provide definitions of all resources handled by this module. These are
picked up by Web::MREST::InitRouter.
This resource is the parent of all resources that do not specify a parent in their
resource definition. EOH
},
# bugreport
'bugreport' =>
{
parent => '/',
handler => {
GET => 'handler_bugreport',
},
cli => 'bugreport',
description => 'Display instructions for reporting bugs in Web::MREST',
documentation => <<'EOH',
=pod
Returns a JSON structure containing instructions for reporting bugs. EOH
},
# configinfo
'configinfo' =>
{
parent => '/',
handler => {
GET => 'handler_configinfo',
},
cli => 'configinfo',
description => 'Display information about Web::MREST configuration',
documentation => <<'EOH',
=pod
Returns a list of directories that were scanned for configuration files. EOH
},
# docu
'docu' =>
{
parent => '/',
handler => 'handler_noop',
cli => 'docu',
description => 'Access on-line documentation (via POST to appropriate subresource)',
documentation => <<'EOH',
=pod
This resource provides access to on-line documentation through its subresources:
'docu/pod', 'docu/html', and 'docu/text'.
To get documentation on a resource, send a POST reqeuest for one of these subresources,
including the resource name in the request entity as a bare JSON string (i.e. in double
quotes). EOH
},
# docu/pod
'docu/pod' =>
{
parent => 'docu',
handler => {
POST => 'handler_docu',
},
cli => 'docu pod $RESOURCE',
description => 'Display POD documentation of a resource',
documentation => <<'EOH',
=pod
This resource provides access to on-line help documentation in POD format. It expects to
find a resource name (e.g. "employee/eid/:eid" including the double-quotes, and without
leading or trailing slash) in the request body. It returns a string containing the POD
source code of the resource documentation. EOH
},
# docu/html
'docu/html' =>
{
parent => 'docu',
handler => {
POST => 'handler_docu',
},
cli => 'docu html $RESOURCE',
description => 'Display HTML documentation of a resource',
documentation => <<'EOH',
=pod
This resource provides access to on-line help documentation. It expects to find a resource
name (e.g. "employee/eid/:eid" including the double-quotes, and without leading or
trailing slash) in the request body. It generates HTML from the resource documentation's
POD source code. EOH
},
# docu/text
'docu/text' =>
{
parent => 'docu',
handler => {
POST => 'handler_docu',
},
cli => 'docu text $RESOURCE',
description => 'Display resource documentation in plain text',
documentation => <<'EOH',
=pod
This resource provides access to on-line help documentation. It expects to find a resource
name (e.g. "employee/eid/:eid" including the double-quotes, and without leading or
trailing slash) in the request body. It returns a plain text rendering of the POD source
of the resource documentation. EOH
},
# echo
'echo' =>
{
parent => '/',
handler => {
POST => 'handler_echo',
},
cli => 'echo [$JSON]',
description => 'Echo the request body',
documentation => <<'EOH',
=pod
This resource simply takes whatever content body was sent and echoes it back in the
response body. EOH
},
# noop
'noop' =>
{
parent => '/',
handler => 'handler_noop',
cli => 'noop',
description => 'A resource that does nothing',
documentation => <<'EOH',
=pod
Regardless of anything, this resource does nothing at all. EOH
},
# param/:type/:param
'param/:type/:param' =>
{
parent => '/',
handler => {
'GET' => 'handler_param',
'PUT' => 'handler_param',
'DELETE' => 'handler_param',
},
cli => {
'GET' => 'param $TYPE $PARAM',
'PUT' => 'param $TYPE $PARAM $VALUE',
'DELETE' => 'param $TYPE $PARAM',
},
description => {
'GET' => 'Display value of a meta/core/site parameter',
'PUT' => 'Set value of a parameter (meta only)',
'DELETE' => 'Delete a parameter (meta only)',
},
documentation => <<'EOH',
=pod
This resource can be used to look up (GET) meta, core, and site parameters, as well as to
set (PUT) and delete (DELETE) meta parameters. EOH
validations => {
'type' => qr/^(meta)|(core)|(site)$/,
'param' => qr/^[[:alnum:]_][[:alnum:]_-]+$/,
},
},
# test/?:specs
'test/?:specs' =>
{
parent => '/',
handler => 'handler_test',
cli => 'test [$SPECS]',
description => "Resources for testing resource handling semantics",
},
# version
'version' =>
{
parent => '/',
handler => {
GET => 'handler_version',
},
cli => 'version',
description => 'Display application name and version',
documentation => <<'EOH',
=pod
Shows the software version running on the present instance. The version displayed is taken
from the $VERSION package variable of the package specified in the
"MREST_APPLICATION_MODULE" site parameter. EOH
},
};
FUNCTIONS
init_router
Initialize (populate) the router. Called from Resource.pm when the first request comes
waltzing in.
_first_pass_always_exists
Boilerplate code for use in handlers of resources that always exist
handler_bugreport
Handler for the "bugreport" resource.
handler_configinfo
Handler for the "configinfo" resource.
handler_docu
The definition of resource $docu_resource lacks a 'documentation' property EOH
# if they want POD, give them POD; if they want HTML, give them HTML, etc.
if ( $resource_name eq 'docu/pod' ) {
$pl->{'format'} = 'POD';
$pl->{'documentation'} = $docs;
} elsif ( $resource_name eq 'docu/html' ) {
$pl->{'format'} = 'HTML';
$pl->{'documentation'} = pod_to_html( $docs );
} else {
# fall back to plain text
$pl->{'format'} = 'text';
$pl->{'documentation'} = pod_to_text( $docs );
}
return $CELL->status_ok( 'MREST_DISPATCH_ONLINE_DOCUMENTATION', payload => $pl ); }
handler_echo
Echo request body back in the response
handler_param
Handler for 'param/:type/:param' resource.
handler_noop
Generalized handler for resources that don't do anything.
handler_test
The only purpose of this resource is testing/demonstration of request handling.
handler_version
Handler for the "version" resource.