Bio/Tools/Run/AnalysisFactory.pm

   1 #
   2 # BioPerl module for Bio::Tools::Run::AnalysisFactory
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Martin Senger <martin.senger@gmail.com>
   7 # For copyright and disclaimer see below.
   8 #
   9
  10 # POD documentation - main docs before the code
  11
  12 =head1 NAME
  13
  14 Bio::Tools::Run::AnalysisFactory - A directory of analysis tools
  15
  16 =head1 SYNOPSIS
  17
  18   # list all available analyses from the default location,
  19   # using a default (SOAP) access method
  20   use Bio::Tools::Run::AnalysisFactory;
  21   my $list = Bio::Tools::Run::AnalysisFactory->new();
  22                 ->available_analyses;
  23   use Data::Dumper; print Dumper ($list);
  24
  25   # ditto, but from a different location
  26   use Bio::Tools::Run::AnalysisFactory;
  27   my $list =
  28      Bio::Tools::Run::AnalysisFactory->new(-location => 'http://somewhere/something')
  29                 ->available_analyses;
  30
  31   # ...and using a different access method
  32   # (this example is not yet impelmented)
  33   use Bio::Tools::Run::AnalysisFactory;
  34   my $list =
  35      Bio::Tools::Run::AnalysisFactory->new(-location => 'http://somewhere/something',
  36                                            -access => 'novella')
  37                 ->available_analyses;
  38
  39   # list available categories of analyses
  40   use Bio::Tools::Run::AnalysisFactory;
  41   my $categories =
  42      Bio::Tools::Run::AnalysisFactory->new();
  43                 ->available_categories;
  44   use Data::Dumper; print Dumper ($categories);
  45
  46   # show all analyses group by categories
  47   use Bio::Tools::Run::AnalysisFactory;
  48   my $factory = Bio::Tools::Run::AnalysisFactory->new();
  49   foreach $cat ( @{ $factory->available_categories } ) {
  50     my @sublist = @{ $factory->available_analyses ($cat) };
  51     print "$cat:\n\t",
  52           join ("\n\t", @{ $factory->available_analyses ($cat) }),
  53           "\n";
  54   }
  55
  56   # create an analysis object
  57   use Bio::Tools::Run::AnalysisFactory;
  58   $service = Bio::Tools::Run::AnalysisFactory->new();
  59                  ->create_analysis ('edit.seqret');
  60   $service->run (
  61                 #...
  62                 )->results;
  63
  64 =head1 DESCRIPTION
  65
  66 The module represents a list of available analysis tools from a given
  67 location using a given access method. Additionally, for any of the
  68 available analyses, it can create an object of type C<Bio::Tools::Run::Analysis>.
  69
  70 The module is a higher-level abstraction whose main job is to load a
  71 'real-work-doing' implementation. Which one is used, it depends on the
  72 C<-access> parameter. The same design is used here as for
  73 C<Bio::Tools::Run::Analysis> module.
  74
  75 There is available a I<SOAP> access to almost all EMBOSS applications,
  76 running at European Bioinformatics Institute.
  77
  78 The documentation of all C<public> methods are to be found
  79 in C<Bio::Factory::AnalysisI>.
  80
  81 =head1 FEEDBACK
  82
  83 =head2 Mailing Lists
  84
  85 User feedback is an integral part of the evolution of this and other
  86 Bioperl modules. Send your comments and suggestions preferably to
  87 the Bioperl mailing list.  Your participation is much appreciated.
  88
  89   bioperl-l@bioperl.org                  - General discussion
  90   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  91
  92 =head2 Support
  93
  94 Please direct usage questions or support issues to the mailing list:
  95
  96 I<bioperl-l@bioperl.org>
  97
  98 rather than to the module maintainer directly. Many experienced and
  99 reponsive experts will be able look at the problem and quickly
 100 address it. Please include a thorough description of the problem
 101 with code and data examples if at all possible.
 102
 103 =head2 Reporting Bugs
 104
 105 Report bugs to the Bioperl bug tracking system to help us keep track
 106 of the bugs and their resolution. Bug reports can be submitted via the
 107 web:
 108
 109   http://redmine.open-bio.org/projects/bioperl/
 110
 111 =head1 AUTHOR
 112
 113 Martin Senger (martin.senger@gmail.com)
 114
 115 =head1 COPYRIGHT
 116
 117 Copyright (c) 2003, Martin Senger and EMBL-EBI.
 118 All Rights Reserved.
 119
 120 This module is free software; you can redistribute it and/or modify
 121 it under the same terms as Perl itself.
 122
 123 =head1 DISCLAIMER
 124
 125 This software is provided "as is" without warranty of any kind.
 126
 127 =head1 SEE ALSO
 128
 129 =over 4
 130
 131 =item *
 132
 133 http://www.ebi.ac.uk/soaplab/Perl_Client.html
 134
 135 =back
 136
 137 =head1 APPENDIX
 138
 139 Here is the rest of the object methods.  Internal methods are preceded
 140 with an underscore _.
 141
 142 =cut
 143
 144
 145 # Let the code begin...
 146
 147 package Bio::Tools::Run::AnalysisFactory;
 148 use vars qw(@ISA $Revision);
 149 use strict;
 150
 151 use Bio::Root::Root;
 152 use Bio::Factory::AnalysisI;
 153 @ISA = qw(Bio::Root::Root Bio::Factory::AnalysisI);
 154
 155
 156 BEGIN {
 157     $Revision = q$Id$;
 158 }
 159
 160 # -----------------------------------------------------------------------------
 161
 162 # Available (understood) parameters:
 163 # -access
 164 #  (+ parameters used in guessing an access)
 165
 166 # -----------------------------------------------------------------------------
 167
 168 =head2 new
 169
 170  Usage   : my $factory =
 171              Bio::Tools::Run::AnalysisFactory->new(-access => 'soap',
 172                                                    -location => 'http://...');
 173  Returns : a new Bio::Tools::Run::AnalysisFactory object representing a list
 174            of available analyses
 175  Args    : There may be additional arguments which are specific
 176            to the access method (see methods 'new' or '_initialize'
 177            of the access-specific implementations (such as module
 178            Bio::Tools::Run::AnalysisFactory::soap for a SOAP-based access).
 179
 180            The recognised and used arguments are:
 181              -access
 182              -location
 183              -httpproxy
 184              -timeout
 185
 186 It builds, populates and returns a new C<Bio::Tools::Run::AnalysisFactory> object. This
 187 is how it is seen from the outside. But in fact, it builds, populates
 188 and returns a more specific lower-level object, for example
 189 C<Bio::Tools::Run::AnalysisFactory::soap> object - which one it is it depends on the C<-access>
 190 parameter.
 191
 192 =over 4
 193
 194 =item -access
 195
 196 It indicates what lower-level module to load.  Default is 'soap'.
 197 Other (but future) possibilities are:
 198
 199    -access => 'novella'
 200    -access => 'local'
 201
 202 =item -location
 203
 204 A location of the service. The contents is access-specific (see
 205 details in the lower-level implementation modules).
 206
 207 Default is C<http://www.ebi.ac.uk/soaplab/services> (there are
 208 services running at European Bioinformatics Institute on top of most
 209 of EMBOSS analyses, and on some others).
 210
 211 =item -httpproxy
 212
 213 In addition to the I<location> parameter, you may need to specify also
 214 a location/URL of an HTTP proxy server (if your site requires
 215 one). The expected format is C<http://server:port>.  There is no
 216 default value. It is also an access-specific parameter which may not
 217 be used by all access methods.
 218
 219 =item -timeout
 220
 221 For long(er) running jobs the HTTP connection may be time-outed. In
 222 order to avoid it (or, vice-versa, to call timeout sooner) you may
 223 specify C<timeout> with the number of seconds the connection will be
 224 kept alive. Zero means to keep it alive forever. The default value is
 225 two minutes.
 226
 227 =back
 228
 229 =cut
 230
 231 sub new {
 232     my ($caller,@args) = @_;
 233     my $class = ref($caller) || $caller;
 234
 235     if ($class eq 'Bio::Tools::Run::AnalysisFactory') {
 236
 237         # this is called only the first time when somebody calls: 'new
 238         # Bio::Tools::Run::AnalysisFactory (...)', and it actually loads a
 239         # 'real-work-doing' module and call this new() method again
 240         # (unless the loaded module has its own new() method)
 241
 242         my %param = @args;
 243         @param { map { lc $_ } keys %param } = values %param; # lowercase keys
 244         my $access =
 245             $param {'-access'} ||                  # use -access parameter
 246             $class->_guess_access ( \%param ) ||   # or guess from other parameters
 247             'soap';                                # or use a default access method
 248         $access = "\L$access";  # normalize capitalization to lower case
 249
 250         # remember the access method (putting it into @args means that the
 251         # object - when created - will remember it)
 252         push (@args, (-access => $access)) unless $param {'-access'};
 253
 254         # load module with the real implementation - as defined in $access
 255         return undef unless (&_load_access_module ($access));
 256
 257         # this calls this same method new() - but now its object part
 258         # (see the upper branche above) is called
 259         return "Bio::Tools::Run::AnalysisFactory::$access"->new (@args);
 260
 261     } else {
 262
 263         # if $caller is an object, or if it is an underlying
 264         # 'real-work-doing' class (e.g. Bio::Tools::Run::AnalysisFactory::soap)
 265         # then we want to call SUPER to create and bless a new object
 266
 267         my ($self) = $class->SUPER::new (@args);
 268
 269         # now the $self is an empty object - we will populate it from
 270         # the $caller - if $caller is an object (so we do cloning here)
 271
 272         if (ref ($caller)) {
 273             %{ $self } = %{ $caller };
 274         }
 275
 276         # and finally add values from '@args' into the newly created
 277         # object (the values will overwrite the values copied above);
 278         # this is done by calling '_initialize' of the 'real-work-doing'
 279         # class (if there is no one there, there is always an empty one
 280         # in Bio::Root::Root)
 281
 282         $self->_initialize (@args);
 283         return $self;
 284     }
 285
 286 }
 287
 288 # -----------------------------------------------------------------------------
 289
 290 =head2 _load_access_module
 291
 292  Usage   : $class->_load_access_module ($access)
 293  Returns : 1 on success, undef on failure
 294  Args    : 'access' should contain the last part of the
 295            name of a module who does the real implementation
 296
 297 It does (in the run-time) a similar thing as
 298
 299    require Bio::Tools::Run::AnalysisFactory::$access
 300
 301 It prints an error on STDERR if it fails to find and load the module
 302 (for example, because of the compilation errors in the module).
 303
 304 =cut
 305
 306 sub _load_access_module {
 307   my ($access) = @_;
 308
 309   my $load = "Bio/Tools/Run/AnalysisFactory/$access.pm";
 310   eval {
 311     require $load;
 312   };
 313
 314   if ( $@ ) {
 315     Bio::Root::Root->throw (<<END);
 316 $load: $access cannot be found or loaded
 317 Exception $@
 318 For more information about the Analysis system please see the Bio::Tools::Run::AnalysisFactory docs.
 319 END
 320   ;
 321     return;
 322   }
 323   return 1;
 324 }
 325
 326 # -----------------------------------------------------------------------------
 327
 328 =head2 _guess_access
 329
 330  Usage   : $class->_guess_access ($rh_params)
 331  Returns : string with a guessed access protocol (e.g. 'soap'),
 332            or undef if the guessing failed
 333  Args    : 'rh_params' is a hash reference containing parameters given
 334            to the 'new' method.
 335
 336 It makes an expert guess what kind of access/transport protocol should
 337 be used to access the underlying analysis. The guess is based on the
 338 parameters in I<rh_params>. Rememeber that this method is called only
 339 if there was no I<-access> parameter which could tell directly what
 340 access method to use.
 341
 342 =cut
 343
 344 sub _guess_access {
 345    my ($class, $rh_params) = @_;
 346    return undef;
 347 }
 348
 349 # -----------------------------------------------------------------------------
 350
 351 =head2 VERSION and Revision
 352
 353  Usage   : print $Bio::Tools::Run::AnalysisFactory::VERSION;
 354            print $Bio::Tools::Run::AnalysisFactory::Revision;
 355
 356 =cut
 357
 358 1;
 359 __END__