Provided by: libweb-mrest-perl_0.290-1_all bug

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.