Bio::AnalysisI JobI
Other packages in the module: Bio::AnalysisI
Included librariesPackage variablesGeneral documentationMethods
Toolbar
WebCvsRaw content
Package variables
No package variables defined.
Included modules
Bio::Root::RootI
Inherit
Bio::Root::RootI
Synopsis
No synopsis!
Description
No description!
Methods
createdDescriptionCode
elapsedDescriptionCode
endedDescriptionCode
idDescriptionCode
last_eventDescriptionCode
removeDescriptionCode
resultDescriptionCode
resultsDescriptionCode
runDescriptionCode
startedDescriptionCode
statusDescriptionCode
terminateDescriptionCode
timesDescriptionCode
wait_forDescriptionCode
Methods description
createdcode    nextTop
 Usage   : $job->created (1)
 Returns : time when this job was created
 Args    : optional
Without any argument it returns a time of creation of this job in
seconds, counting from the beginning of the UNIX epoch
(1.1.1970). With a true argument it returns a formatted time, using
rules described in Bio::Tools::Run::Analysis::Utils::format_time.
elapsedcodeprevnextTop
 Usage   : $job->elapsed
 Returns : elapsed time of the execution of the given job
           (in milliseconds), or 0 of job was not yet started
 Args    : none
Note that some server implementations cannot count in millisecond - so
the returned time may be rounded to seconds.
endedcodeprevnextTop
 Usage   : $job->ended (1)
 Returns : time when this job was terminated
 Args    : optional
See created.
idcodeprevnextTop
 Usage   : $job->id;
 Returns : this job ID
 Args    : none
Each job (an execution) is identifiable by this unique ID which can be
used later to re-create the same job (in other words: to re-connect to
the same job). It is useful in cases when a job takes long time to
finish and your client program does not want to wait for it within the
same session.
last_eventcodeprevnextTop
 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)">
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;

   
   
     Mar 3, 2003 5:17:14 PM (Europe/London)
removecodeprevnextTop
 Usage   : $job->remove
 Returns : 1
 Args    : none
The job object is not actually removed in this time but it is marked
(setting 1 to _destroy_on_exit attribute) as ready for deletion when
the client program ends (including a request to server to forget the job
mirror object on the server side).
resultcodeprevnextTop
 Usage   : $job->result (...)
 Returns : the first result
 Args    : see 'results'
resultscodeprevnextTop
 Usage   : $job->results (...)
 Returns : one or more results created by this job
 Args    : various, see belou
This is a complex method trying to make sense for all kinds of
results. Especially it tries to help to put binary results (such as
images) into local files. Generally it deals with fhe following facts:
    *(1)
    Each analysis tool may produce more results.
    *(2)
    Some results may contain binary data not suitable for printing into a
terminal window.
    *(3)
    Some results may be split into variable number of parts (this is
mainly true for the image results that can consist of more *.png
files).
Note also that results have names to distinguish if there are more of
them. The names can be obtained by method result_spec.
Here are the rules how the method works:
    Retrieving NAMED results:
    -------------------------
     results ('name1', ...)   => return results as they are, no storing into files

     results ( { 'name1' => 'filename', ... } )  => store into 'filename', return 'filename'
     results ( 'name1=filename', ...)            => ditto

     results ( { 'name1' => '-', ... } )         => send result to the STDOUT, do not return anything
     results ( 'name1=-', ...)                   => ditto

     results ( { 'name1' => '@', ... } )  => store into file whose name is invented by
                                             this method, perhaps using RESULT_NAME_TEMPLATE env
     results ( 'name1=@', ...)            => ditto

     results ( { 'name1' => '?', ... } )  => find of what type is this result and then use
                                             {'name1'=>'@' for binary files, and a regular
                                             return for non-binary files
     results ( 'name=?', ...)             => ditto

    Retrieving ALL results:
    -----------------------
     results()     => return all results as they are, no storing into files

     results ('@') => return all results, as if each of them given
                      as {'name' => '@'} (see above)

     results ('?') => return all results, as if each of them given
                      as {'name' => '?'} (see above)

    Misc:
    -----
     * any result can be returned as a scalar value, or as an array reference
       (the latter is used for results consisting of more parts, such images);
       this applies regardless whether the returned result is the result itself
       or a filename created for the result

     * look in the documentation of the panalysis[.PLS] script for examples
       (especially how to use various templates for inventing file names)
runcodeprevnextTop
 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
Bio::Tools::Run::Analysis object where the run method creates
also a new job allowing to set input data.
startedcodeprevnextTop
 Usage   : $job->started (1)
 Returns : time when this job was started
 Args    : optional
See created.
statuscodeprevnextTop
 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
terminatecodeprevnextTop
 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.
timescodeprevnextTop
 Usage   : $job->times ('formatted')
 Returns : a hash refrence with all time characteristics
 Args    : optional
It is a convenient method returning a hash reference with the folowing
keys:
   created
   started
   ended
   elapsed
See create for remarks on time formating.
An example - both for unformatted and formatted times:
   use Data::Dumper;
   use Bio::Tools::Run::Analysis;
   my $rh = new Bio::Tools::Run::Analysis (-name => 'nucleic_cpg_islands::cpgplot')
             ->wait_for ( { 'sequence_usa' => 'embl:hsu52852' } )
	     ->times (1);
   print Data::Dumper->Dump ( [$rh], ['Times']);
   $rh = new Bio::Tools::Run::Analysis (-name => 'nucleic_cpg_islands::cpgplot')
             ->wait_for ( { 'sequence_usa' => 'embl:AL499624' } )
	     ->times;
   print Data::Dumper->Dump ( [$rh], ['Times']);

   $Times = {
           'ended'   => 'Mon Mar  3 17:52:06 2003',
           'started' => 'Mon Mar  3 17:52:05 2003',
           'elapsed' => '1000',
           'created' => 'Mon Mar  3 17:52:05 2003'
         };
   $Times = {
           'ended'   => '1046713961',
           'started' => '1046713926',
           'elapsed' => '35000',
           'created' => '1046713926'
         };
wait_forcodeprevnextTop
 Usage   : $job->wait_for
 Returns : itself
 Args    : none
It waits until a previously started execution of this job finishes.
Methods code
createddescriptionprevnextTop
sub created {
 shift->throw_not_implemented();
}
elapseddescriptionprevnextTop
sub elapsed {
 shift->throw_not_implemented();
}
endeddescriptionprevnextTop
sub ended {
 shift->throw_not_implemented();
}
iddescriptionprevnextTop
sub id {
 shift->throw_not_implemented();
}
last_eventdescriptionprevnextTop
sub last_event {
 shift->throw_not_implemented();
}
removedescriptionprevnextTop
sub remove {
 shift->throw_not_implemented();
}
resultdescriptionprevnextTop
sub result {
 shift->throw_not_implemented();
}
resultsdescriptionprevnextTop
sub results {
 shift->throw_not_implemented();
}
rundescriptionprevnextTop
sub run {
 shift->throw_not_implemented();
}
starteddescriptionprevnextTop
sub started {
 shift->throw_not_implemented();
}
statusdescriptionprevnextTop
sub status {
 shift->throw_not_implemented();
}
terminatedescriptionprevnextTop
sub terminate {
 shift->throw_not_implemented();
}
timesdescriptionprevnextTop
sub times {
 shift->throw_not_implemented();
}
wait_fordescriptionprevnextTop
sub wait_for {
 shift->throw_not_implemented();
}
General documentation
Module Bio::AnalysisI::JobITop
An interface to the public methods provided by Bio::Tools::Run::Analysis::Job
objects.
The Bio::Tools::Run::Analysis::Job objects represent a created,
running, or finished execution of an analysis tool.
The factory for these objects is module Bio::Tools::Run::Analysis
where the following methods return an
Bio::Tools::Run::Analysis::Job object:
    create_job   (returning a prepared job)
    run          (returning a running job)
    wait_for     (returning a finished job)