|1. Subclass||Subclass REST::Application, i.e. use base REST::Application.|
|2. Overload setup()||
Overload the setup() method and set up some resource hooks with the
resourceHooks() method. Hooks are mappings of the form:
where handler is either a method name, a code reference, an object which supports a method with the same name as the HTTP method (or getResource if no such method), or a reference to an array of the form: [$objectRef, "methodName"] ($objectRef can be a class name instead).
The regular expressions are applied, by default, to the path info of the HTTP request. Anything captured by parens in the regex will be passed into the handler as arguments.
The above hook will call a method named getPartByNumber on the current object (i.e. $self, an instance of REST::Application) if the path info of the requested URI matches the above regular expression. The first argument to the method will be the part number, since thats the first element captured in the regular expression.
|3. Write code.||Write the code for the handler specified above. So here wed define the getPartByNumber method.|
|4. Create a handler/loader.||
Create an Apache handler, for example:
or a small CGI script with the following code:
In the second case, for a CGI script, youll probably need to do something special to get Apache to load up your script unless you give it a .cgi extension. It would be unRESTful to allow your script to have a .cgi extension, so you should go the extra mile and configure Apache to run your script without it. For example, itd be bad to have your users go to:
|5. Call the run() method.||
When the run() method is called the path info is extracted from the HTTP
request. The regexes specified in step 2 are processed, in order, and if one
matches then the handler is called. If the regex had paren. matching then the
matched elements are passed into the handler. A handler is also passed a copy
of the REST::Application object instance (except for the case when the
handler is a method on the REST::Application object, in that case itd be
redundant). So, when writing a subroutine handler youd do:
|6. Return a representation of the resource.||The handler is processed and should return a string or a scalar reference to a string. Optionally the handler should set any header information via the header() method on instance object pased in.|
The REST::Application base class provides a good number of methods, each of which can be overloaded. By default you only need to overload the setup() method but you may wish to overload others. To help with this the following outline is the calling order of the various methods in the base class. You can find detailed descriptions of each method in the METHODS section of this document.
If a method is followed by the string NOOP then that means it does nothing by default and it exists only to be overloaded.
new() setup() - NOOP run() preRun() - NOOP loadResource() getMatchText() getPathInfo() query() defaultQueryObject() defaultResourceHandler() - NOOP resourceHooks() checkMatch() _setLastRegexMatches() _getHandlerFromHook() resourceHooks() defaultResourceHandler() - NOOP getRequestMethod() query() defaultQueryObject() bestContentType() simpleContentNegotiation getContentPrefs getAcceptHeader scoreType() callHandler() getHandlerArgs _getLastRegexMatches() extraHandlerArgs() preHandler() - NOOP ... your handler called here ... postHandler() - NOOP postRun() - NOOP getHeaders() headerType() query() defaultQueryObject() header() addRepresentation()
The only methods not called as part of the new() or run() methods are the helper methods resetHeader() and setRedirect(), both of which call the header() and headerType() methods.
For example, if you wanted to have your code branch on the entire URI of the HTTP request rather than just the path info youd merely overload getMatchText() to return the URI rather than the path info.
This method creates a new REST::Application object and returns it. The arguments passed in via %args, if any, are passed untouched to the setup() method.
This method retrieves/sets the default query object. This method is called if query() is called for the first time and no query object has been set yet.
This method is used to set the resource hooks. A REST::Application hook is a regex to handler mapping. The hooks are passed in as a hash (or a reference to one) and the keys are treated as regular expressions while the values are treated as handlers should <B>PATH_INFOB> match the regex that maps to that handler.
Handlers can be code references, methods on the current object, methods on other objects, or class methods. Also, handlers can be differ based on what the <B>REQUEST_METHODB> was (e.g. GET, PUT, POST, DELETE, etc).
The handlers types are as follows:
The return value of the handler is expected to be a string, which REST::Application will then send to the browser with the sendRepresentation() method.
string The handler is considered to be a method on the current REST::Application instance. code ref The code ref is considered to be the handler. object ref The object is considered to have a method the same name as the HTTP method. That is, if the object is being called because of GET then GET() is called, if it is called because of a DELETE then DELETE() is called. getResource() method will be used if getRequestMethod() returns false. array ref The array is expected to be two elements long, the first element is a class name or object instance. The 2nd element is a method name on that class/instance. IF the 2nd element is ommitted then the method name is assumed to be the same as the <B>REQUEST_METHODB>, e.g. GET(), PUT(), whatever. hash ref The current <B>REQUEST_METHODB> is used as a key to the hash, the value should be one the four above handler types. In this way you can specify different handlers for each of the request types. The request method can also be specified as *, in which case that is used if a more specific match is not found.
It is possible for the value of the handler to be another hash ref, rather than one of the four above types. In this case it is assumed content-negotion is wanted. The keys of this second hash are MIME types and the values are one of the four above types. For example:
If no argument is supplied to resourceHooks() then the current set of hooks is returned. The returned hash referces is a tied IxHash, so the keys are kept sorted.
This method will take the value of <B>PATH_INFOB>, iterate through the path regexs set in resourceHooks() and if it finds a match call the associated handler and return the handlers value, which should be a scalar. If $path is passed in then that is used instead of <B>PATH_INFOB>.
run()This method calls loadResource() with no arguments and then takes that output and sends it to the remote client. Headers are sent with sendHeaders() and the representation is sent with sendRepresentation().
If the environment variable <B>REST_APP_RETURN_ONLYB> is set then output isnt sent to the client. The return value of this method is the text output it sends (or wouldve sent).
sendHeaders()This method returns the headers as a string.
This method just returns $representation. It is provided soely for overloading purposes.
This accessor/mutator controls the type of header to be returned. This method returns one of header, redirect, or none. If $type is passed in then that is used to set the header type.
This accessor/mutator controls the header values sent. If called without arguments then it simply returns the current header values as a hash, where the keys are the header fields and the values are the header field values.
If this method is called multiple times then the values of %args are additive. So calling $self-header(-type => text/html)> and $self-header(-foo => bar)> results in both the content-type header being set and the foo header being set.
resetHeader()This header causes the current header values to be reset. The previous values are returned.
defaultResourceHandler()This method is called by loadResource() if no regex in resourceHooks() matches the current <B>PATH_INFOB>. It returns undef by default, it exists for overloading.
Given a list of MIME types this function returns the best matching type considering the Accept header of the current request (as returned by getAcceptHeader().
Given a list of MIME types this function returns the same list sorted from best match to least considering the Accept header as returned by getAcceptHeader().
getContentPrefs()Returns the list of MIME types in the Accept header form most preferred to least preferred. Quality weights are taken into account.
getAcceptHeader()Returns the value of the Accept header as a single string.
scoreType($type, CW@accept_types)Returns an integer, only good for sorting, for where $type fits among the @accept_types. This method takes wildcards into account. So text/plain matches text/*. The integer returned is the position in @accept_types of the matching MIME type. It assumped @accept_types is already sorted from best to worst.
getLastMatchPath()Returns the last path passed to checkMatch() which successfully matched against. Unless youre overloading things in funny ways the value returned will be the path that caused the current handler to be invoked.
getLastMatchPattern()Similar to getLastMatchPath() except this is the pattern that was applied to the path.
getRequestMethod()This method tries to be smart and allow tunneling of the other HTTP methods over GET or PUT. You can tunnel three ways with the higher up taking precedence:
1) Pass an X-HTTP-Method header 2) Pass the http_method query parameter 3) Pass a parameter via POST
Matthew OConnor <firstname.lastname@example.org<gt>
This program is free software. It is subject to the same license as Perl itself.
CGI, CGI::Application, Tie::IxHash, CGI::Application::Dispatch
Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 645: You forgot a =back before =head1 Around line 704: =back without =over
|perl v5.20.3||REST::APPLICATION (3)||2007-08-09|