NAME

Bio::BioVeL::Service - base class for synchronous web services

DESCRIPTION

The BioVeL API makes a distinction between "synchronised" and "asynchronous" services. Synchronised services produce their final result within a single HTTP request/response cycle by generating a response_body that is returned to the client at the end of the cycle. Asynchronous services produce a result at the end of a longer running, forked process, which needs to be tracked between request/response cycles.

All concrete service classes need to inherit from either one of these service type superclasses (Bio::BioVeL::Service or Bio::BioVeL::AsynchronousService) so that all the bookkeeping (processing request parameters, managing forked processes) is taken care of and the concrete child class only needs to worry about producing its result.

METHODS

new

The constructor takes at least one named argument, parameters, whose value is an array reference of names. The constructor then tries to obtain the values for these named parameters. It does in a number of ways: 1. by probing the @ARGV command line argument array, 2. by probing the apache request object (if provided), 3. by instantiating and querying a CGI object. Once the constructor returns, the object will have properties whose values are available to the child class for constructing its response body.

get_handle

Given a string parameter name, such as 'tree', returns a readable handle that corresponds with the specified data.

handler

This method is triggered by mod_perl when a URL path fragment is encountered that matches the mapping specified in httpd.conf. Example:

 <Location /foo>
         SetHandler perl-script
         PerlResponseHandler Bio::BioVeL::Service::Foo
 </Location>

In this case, requests to http://example.com/foo will be dispatched to Bio::BioVeL::Service::Foo::handler.

The method instantiates a concrete service class based on the request parameter service, passes in the Apache2::Request object and expects the concrete service to produce a response body, which the handler prints out. The return value, Apache2::Const::OK, indicates to mod_perl that everything went well.

response_header

Returns the HTTP response header. This might include the content-type.

response_body

Returns the response body as a big string.

logger

Returns a logger object.

CLONING

The following methods read and write service objects to/from YAML. This is used for (de-)serializing objects so that they can be persisted between HTTP request cycles.

to_string

Returns a YAML string representation of the object.

to_file

Writes the object as YAML to the provided file location.

from_string

Instantiates an object from the provided YAML string.

from_file

Instantiates an object from the provided location.