lib/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
 149 use vars qw(@ISA $Revision);
 150 use strict;
 151
 152 use Bio::Root::Root;
 153 use Bio::Factory::AnalysisI;
 154 @ISA = qw(Bio::Root::Root Bio::Factory::AnalysisI);
 155
 156
 157 BEGIN {
 158     $Revision = q$Id$;
 159 }
 160
 161 # -----------------------------------------------------------------------------
 162
 163 # Available (understood) parameters:
 164 # -access
 165 #  (+ parameters used in guessing an access)
 166
 167 # -----------------------------------------------------------------------------
 168
 169 =head2 new
 170
 171  Usage   : my $factory =
 172              Bio::Tools::Run::AnalysisFactory->new(-access => 'soap',
 173                                                    -location => 'http://...');
 174  Returns : a new Bio::Tools::Run::AnalysisFactory object representing a list
 175            of available analyses
 176  Args    : There may be additional arguments which are specific
 177            to the access method (see methods 'new' or '_initialize'
 178            of the access-specific implementations (such as module
 179            Bio::Tools::Run::AnalysisFactory::soap for a SOAP-based access).
 180
 181            The recognised and used arguments are:
 182              -access
 183              -location
 184              -httpproxy
 185              -timeout
 186
 187 It builds, populates and returns a new C<Bio::Tools::Run::AnalysisFactory> object. This
 188 is how it is seen from the outside. But in fact, it builds, populates
 189 and returns a more specific lower-level object, for example
 190 C<Bio::Tools::Run::AnalysisFactory::soap> object - which one it is it depends on the C<-access>
 191 parameter.
 192
 193 =over 4
 194
 195 =item -access
 196
 197 It indicates what lower-level module to load.  Default is 'soap'.
 198 Other (but future) possibilities are:
 199
 200    -access => 'novella'
 201    -access => 'local'
 202
 203 =item -location
 204
 205 A location of the service. The contents is access-specific (see
 206 details in the lower-level implementation modules).
 207
 208 Default is C<http://www.ebi.ac.uk/soaplab/services> (there are
 209 services running at European Bioinformatics Institute on top of most
 210 of EMBOSS analyses, and on some others).
 211
 212 =item -httpproxy
 213
 214 In addition to the I<location> parameter, you may need to specify also
 215 a location/URL of an HTTP proxy server (if your site requires
 216 one). The expected format is C<http://server:port>.  There is no
 217 default value. It is also an access-specific parameter which may not
 218 be used by all access methods.
 219
 220 =item -timeout
 221
 222 For long(er) running jobs the HTTP connection may be time-outed. In
 223 order to avoid it (or, vice-versa, to call timeout sooner) you may
 224 specify C<timeout> with the number of seconds the connection will be
 225 kept alive. Zero means to keep it alive forever. The default value is
 226 two minutes.
 227
 228 =back
 229
 230 =cut
 231
 232 sub new {
 233     my ($caller,@args) = @_;
 234     my $class = ref($caller) || $caller;
 235
 236     if ($class eq 'Bio::Tools::Run::AnalysisFactory') {
 237
 238         # this is called only the first time when somebody calls: 'new
 239         # Bio::Tools::Run::AnalysisFactory (...)', and it actually loads a
 240         # 'real-work-doing' module and call this new() method again
 241         # (unless the loaded module has its own new() method)
 242
 243         my %param = @args;
 244         @param { map { lc $_ } keys %param } = values %param; # lowercase keys
 245         my $access =
 246             $param {'-access'} ||                  # use -access parameter
 247             $class->_guess_access ( \%param ) ||   # or guess from other parameters
 248             'soap';                                # or use a default access method
 249         $access = "\L$access";  # normalize capitalization to lower case
 250
 251         # remember the access method (putting it into @args means that the
 252         # object - when created - will remember it)
 253         push (@args, (-access => $access)) unless $param {'-access'};
 254
 255         # load module with the real implementation - as defined in $access
 256         return undef unless (&_load_access_module ($access));
 257
 258         # this calls this same method new() - but now its object part
 259         # (see the upper branche above) is called
 260         return "Bio::Tools::Run::AnalysisFactory::$access"->new (@args);
 261
 262     } else {
 263
 264         # if $caller is an object, or if it is an underlying
 265         # 'real-work-doing' class (e.g. Bio::Tools::Run::AnalysisFactory::soap)
 266         # then we want to call SUPER to create and bless a new object
 267
 268         my ($self) = $class->SUPER::new (@args);
 269
 270         # now the $self is an empty object - we will populate it from
 271         # the $caller - if $caller is an object (so we do cloning here)
 272
 273         if (ref ($caller)) {
 274             %{ $self } = %{ $caller };
 275         }
 276
 277         # and finally add values from '@args' into the newly created
 278         # object (the values will overwrite the values copied above);
 279         # this is done by calling '_initialize' of the 'real-work-doing'
 280         # class (if there is no one there, there is always an empty one
 281         # in Bio::Root::Root)
 282
 283         $self->_initialize (@args);
 284         return $self;
 285     }
 286
 287 }
 288
 289 # -----------------------------------------------------------------------------
 290
 291 =head2 _load_access_module
 292
 293  Usage   : $class->_load_access_module ($access)
 294  Returns : 1 on success, undef on failure
 295  Args    : 'access' should contain the last part of the
 296            name of a module who does the real implementation
 297
 298 It does (in the run-time) a similar thing as
 299
 300    require Bio::Tools::Run::AnalysisFactory::$access
 301
 302 It prints an error on STDERR if it fails to find and load the module
 303 (for example, because of the compilation errors in the module).
 304
 305 =cut
 306
 307 sub _load_access_module {
 308   my ($access) = @_;
 309
 310   my $load = "Bio/Tools/Run/AnalysisFactory/$access.pm";
 311   eval {
 312     require $load;
 313   };
 314
 315   if ( $@ ) {
 316     Bio::Root::Root->throw (<<END);
 317 $load: $access cannot be found or loaded
 318 Exception $@
 319 For more information about the Analysis system please see the Bio::Tools::Run::AnalysisFactory docs.
 320 END
 321   ;
 322     return;
 323   }
 324   return 1;
 325 }
 326
 327 # -----------------------------------------------------------------------------
 328
 329 =head2 _guess_access
 330
 331  Usage   : $class->_guess_access ($rh_params)
 332  Returns : string with a guessed access protocol (e.g. 'soap'),
 333            or undef if the guessing failed
 334  Args    : 'rh_params' is a hash reference containing parameters given
 335            to the 'new' method.
 336
 337 It makes an expert guess what kind of access/transport protocol should
 338 be used to access the underlying analysis. The guess is based on the
 339 parameters in I<rh_params>. Remember that this method is called only
 340 if there was no I<-access> parameter which could tell directly what
 341 access method to use.
 342
 343 =cut
 344
 345 sub _guess_access {
 346    my ($class, $rh_params) = @_;
 347    return undef;
 348 }
 349
 350 # -----------------------------------------------------------------------------
 351
 352 =head2 VERSION and Revision
 353
 354  Usage   : print $Bio::Tools::Run::AnalysisFactory::VERSION;
 355            print $Bio::Tools::Run::AnalysisFactory::Revision;
 356
 357 =cut
 358
 359 1;
 360 __END__