NAME

Bio::BioVeL::AsynchronousService - base class for asynchronous web services

SYNOPSIS

 use Bio::BioVeL::AsynchronousService::Mock; # example class
 
 # this static method returns a writable directory into which
 # service objects are persisted between request/response cycles
 my $wd = Bio::BioVeL::AsynchronousService::Mock->workdir;

 # when instantiating objects, values for the 'parameters' that are defined
 # in their constructors can be provided as named arguments
 my $mock = Bio::BioVeL::AsynchronousService::Mock->new( 'seconds' => 1 );

 # every async service has a record of when it started
 my $epoch_time = $mock->timestamp;

 # can be RUNNING, ERROR or DONE
 if ( $mock->status eq Bio::BioVeL::AsynchronousService::DONE ) {
        print $mock->response_body;
 }

DESCRIPTION

Asynchronous services need to subclass this class and implement at least the following methods: launch and response_body. The parent class makes sure that launch() forks off a process and returns immediately with enough information, stored as object properties, so that update() can check how things are going and update the status(). Once the status set to DONE, response_body is executed to generate the output.

Successful implementations are likely going to have simple, serializable object properties that allow a newly de-serialized object (i.e. during the next polling cycle) to probe the process table or the job directory to check the status.

METHODS

new

The constructor may or may not be passed the named argument 'jobid', which is used to deserialize the job object and check on its status. If no job ID is provided, a new object is created and launched.

launch

The concrete child class needs to implement the launch() method, which presumably will fork off a process, e.g. using system("command &"), such that it will be able to keep track of its status, e.g. by knowing the PID of the child processes.

launch_wrapper

Wraps the service launch() inside a fork() to keep track of the PID.

update

The concrete child class needs to implement the update() method, which will check on the process that was launched by launch(), and will update the status, e.g. from RUNNING to DONE or ERROR.

jobid

The unique ID of the service job.

pid

The process ID of the service job.

timestamp

The launch timestamp of the job.

lasterr

The last error string that occurred.

status

The job status, either RUNNING, DONE or ERROR.

handler

The mod_perl handler. Tries to rebuild the job object, checks its status, returns either a status report or the response body.

workdir

This static method returns a directory inside $ENV{BIOVEL_HOME}, which consequently needs to be defined, for example by specifying it with PerlSetEnv inside httpd.conf. See: http://modperlbook.org/html/4-2-10-PerlSetEnv-and-PerlPassEnv.html. This dir is used for serializing the job object, so its location can be generated/pulled out of the air by static methods (as the object might not exist yet). For job-specific output (e.g. analysis result files), use outdir().

outdir

This object method returns a directory location where the child class can write its output

DESTROY

The object destructor automatically serializes the dying object inside workdir.