view release on metacpan or  search on metacpan

Bio/AnalysisI.pm  view on Meta::CPAN

sub id { shift->throw_not_implemented(); }

# -----------------------------------------------------------------------------

=head2 Bio::AnalysisI::JobI::run

 Usage   : $job->run
 Returns : itself
 Args    : none

It starts previously created job.  The job already must have all input
data filled-in. This differs from the method of the same name of the
C<Bio::Tools::Run::Analysis> object where the C<Bio::AnalysisI::JobI::run> method
creates also a new job allowing to set input data.

=cut

sub run { shift->throw_not_implemented(); }

# -----------------------------------------------------------------------------

=head2 Bio::AnalysisI::JobI::wait_for

 Usage   : $job->wait_for
 Returns : itself
 Args    : none

It waits until a previously started execution of this job finishes.

=cut

sub wait_for { shift->throw_not_implemented(); }

# -----------------------------------------------------------------------------

=head2 terminate

 Usage   : $job->terminate
 Returns : itself
 Args    : none

Stop the currently running job (represented by this object). This is a
definitive stop, there is no way to resume it later.

=cut

sub terminate { shift->throw_not_implemented(); }

# -----------------------------------------------------------------------------

=head2 last_event

 Usage   : $job->last_event
 Returns : an XML string
 Args    : none

It returns a short XML document showing what happened last with this
job. This is the used DTD:

   <!-- place for extensions -->
   <!ENTITY % event_body_template "(state_changed | heartbeat_progress | percent_progress | time_progress | step_progress)">

   <!ELEMENT analysis_event (message?, (%event_body_template;)?)>

   <!ATTLIST analysis_event
       timestamp  CDATA #IMPLIED>

   <!ELEMENT message (#PCDATA)>

   <!ELEMENT state_changed EMPTY>
   <!ENTITY % analysis_state "created | running | completed | terminated_by_request | terminated_by_error">
   <!ATTLIST state_changed
       previous_state  (%analysis_state;) "created"
       new_state       (%analysis_state;) "created">

   <!ELEMENT heartbeat_progress EMPTY>

   <!ELEMENT percent_progress EMPTY>
   <!ATTLIST percent_progress
       percentage CDATA #REQUIRED>

   <!ELEMENT time_progress EMPTY>
   <!ATTLIST time_progress
       remaining CDATA #REQUIRED>

   <!ELEMENT step_progress EMPTY>
   <!ATTLIST step_progress
       total_steps      CDATA #IMPLIED
       steps_completed CDATA #REQUIRED>

Here is an example what is returned after a job was created and
started, but before it finishes (note that the example uses an
analysis 'showdb' which does not need any input data):

   use Bio::Tools::Run::Analysis;
   print new Bio::Tools::Run::Analysis (-name => 'display.showdb')
             ->run
	     ->last_event;

It prints:

   <?xml version = "1.0"?>
   <analysis_event>
     <message>Mar 3, 2003 5:14:46 PM (Europe/London)</message>
     <state_changed previous_state="created" new_state="running"/>
   </analysis_event>

The same example but now after it finishes:

   use Bio::Tools::Run::Analysis;
   print new Bio::Tools::Run::Analysis (-name => 'display.showdb')
             ->wait_for
	     ->last_event;

   <?xml version = "1.0"?>
   <analysis_event>
     <message>Mar 3, 2003 5:17:14 PM (Europe/London)</message>
     <state_changed previous_state="running" new_state="completed"/>
   </analysis_event>

=cut

sub last_event { shift->throw_not_implemented(); }

# -----------------------------------------------------------------------------

=head2 status

 Usage   : $job->status
 Returns : string describing the job status
 Args    : none

It returns one of the following strings (and perhaps more if a server
implementation extended possible job states):

   CREATED
   RUNNING
   COMPLETED
   TERMINATED_BY_REQUEST
   TERMINATED_BY_ERROR