Bio/ParameterBaseI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::ParameterBaseI
   4 #
   5 # Cared for by Chris Fields <cjfields at uiuc dot edu>
   6 #
   7 # Copyright Chris Fields
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10 #
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::ParameterBaseI - Simple interface class for any parameter-related data such
  16 as IDs, database name, program arguments, and other odds and ends.
  17
  18 =head1 SYNOPSIS
  19
  20   # Bio::DB::MyParams implements Bio::ParameterBaseI
  21
  22   @params = (-db   => 'protein',
  23              -id   => \@ids,
  24              -retmax => 10);
  25
  26   $pobj->Bio::DB::MyDBParams->new();
  27
  28   # sets only parameters passed; results in a state change if any parameter
  29   # passed is new or differs from previously set value
  30
  31   $pobj->set_params(@params);
  32
  33   # reset all parameters (sets to undef); results in a state change
  34
  35   $pobj->reset_params();
  36
  37   # resets parameters to those in %param (sets all others to undef); resets the
  38   # object state to indicate change.
  39
  40   $pobj->reset_params(@params);
  41
  42   # direct get/set; results in a state change if any parameter passed is new or
  43   # differs from previously set value
  44
  45   $pobj->db('nucleotide');
  46   @ids = $pobj->id();
  47
  48   # retrieve list containing set defined parameters
  49
  50   %myparams = $pobj->get_parameters();
  51
  52   # checks whether the state of the object has changed (i.e. parameter has
  53   # changed, so on)
  54
  55   if ($pobj->parameters_changed) {
  56      # run new search
  57   } else {
  58      # return cached search
  59   }
  60
  61   # available parameters
  62
  63   @params = $pobj->available_parameters();
  64
  65   # retrieve string (URI, query, etc); calling to* methods changes object state
  66   # to indicate data hasn't changed (so future calls to parameters_changed()
  67   # will return FALSE)
  68
  69   $query = $pobj->to_string(); # returns raw string
  70   $uri = $pobj->to_uri(); #  returns URI-based object
  71   $uri = $pobj->to_my_data_struct(); #  returns implemenation-specific data structure
  72   ...
  73
  74 =head1 DESCRIPTION
  75
  76 This is a class interface which focuses on common parameter-related tasks such
  77 as building simple database queries, URI-related requests, program arguments,
  78 etc.
  79
  80 Implementing classes use the following ways to set parameters:
  81
  82 1) Create a new instance of a ParameterBaseI-implementing object.
  83
  84   $pobj->Bio::DB::MyParamClass->new(-db => 'local', -id => \@ids);
  85
  86 2) Pass the parameters as a hash or array to set_parameters(), which sets the
  87 parameters listed in the hash but leaves all others as is.
  88
  89   $pobj->set_parameters(-retmax => 100, -retstart => 20);
  90
  91 3) Pass the parameters as a hash or array to reset_parameters(), which sets the
  92 parameters listed in the hash and resets everything else.
  93
  94   $pobj->reset_parameters(-term => 'pyrimidine'); # sets db and id to undef
  95
  96 4) Pass values using specific getter/setters.
  97
  98   $pobj->id(\@ids); # sets IDs
  99
 100 There is no restriction on what one uses to set up individual parameter
 101 getter/setters, though there are some other options implemented in BioPerl (for
 102 instance, Bio::Root::RootI::_set_from_args()).
 103
 104 A key requirement is there be a way to detect changes in the state of the
 105 ParameterBaseI object so that any object with a Bio::ParameterBaseI can decide
 106 whether to submit a new request or return cached data. State changes are
 107 revealed by the returned values of the parameters_changed() method, which is a
 108 simple boolean set to TRUE when the object is first instantiated or parameters
 109 have changed.
 110
 111 When retrieving anything using the implementation-specific to_* methods (such as
 112 to_query, to_string, to_uri, to_request, etc), the ParameterBaseI object state
 113 is set to FALSE to indicate the data has been accessed and indicate reaccessing
 114 will retrieve the same value. The observing object can then independently decide
 115 whether to rerun the cached query or return a previously cached result.
 116
 117 One can also use indiviual getter/setters to retrieve single parameter values as
 118 well as use parameter_hash() to retrieve all of the parameters in one go as a
 119 hash. To check which parameters are available use available_parameters().  Args
 120 passed to
 121
 122 =head1 FEEDBACK
 123
 124 =head2 Mailing Lists
 125
 126 User feedback is an integral part of the
 127 evolution of this and other Bioperl modules. Send
 128 your comments and suggestions preferably to one
 129 of the Bioperl mailing lists. Your participation
 130 is much appreciated.
 131
 132   bioperl-l@lists.open-bio.org               - General discussion
 133   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
 134
 135 =head2 Reporting Bugs
 136
 137 Report bugs to the Bioperl bug tracking system to
 138 help us keep track the bugs and their resolution.
 139 Bug reports can be submitted via the web.
 140
 141   http://bugzilla.open-bio.org/
 142
 143 =head1 AUTHOR
 144
 145 Email cjfields at uiuc dot edu
 146
 147 =head1 APPENDIX
 148
 149 The rest of the documentation details each of the
 150 object methods. Internal methods are usually
 151 preceded with a _
 152
 153 =cut
 154
 155 # Let the code begin...
 156
 157 package Bio::ParameterBaseI;
 158 use strict;
 159 use warnings;
 160
 161 use base qw(Bio::Root::RootI);
 162
 163 =head2 set_parameters
 164
 165  Title   : set_parameters
 166  Usage   : $pobj->set_parameters(%params);
 167  Function: sets the parameters listed in the hash or array
 168  Returns : None
 169  Args    : [optional] hash or array of parameter/values.
 170
 171 =cut
 172
 173 sub set_parameters {
 174     shift->throw_not_implemented;
 175 }
 176
 177 =head2 reset_parameters
 178
 179  Title   : reset_parameters
 180  Usage   : resets values
 181  Function: resets parameters to either undef or value in passed hash
 182  Returns : none
 183  Args    : [optional] hash of parameter-value pairs
 184
 185 =cut
 186
 187 sub reset_parameters {
 188     shift->throw_not_implemented;
 189 }
 190
 191 =head2 parameters_changed
 192
 193  Title   : parameters_changed
 194  Usage   : if ($pobj->parameters_changed) {...}
 195  Function: Returns boolean true (1) if parameters have changed
 196  Returns : Boolean (0 or 1)
 197  Args    : [optional] Boolean
 198
 199 =cut
 200
 201 sub parameters_changed {
 202     shift->throw_not_implemented;
 203 }
 204
 205 =head2 available_parameters
 206
 207  Title   : available_parameters
 208  Usage   : @params = $pobj->available_parameters()
 209  Function: Returns a list of the available parameters
 210  Returns : Array of parameters
 211  Args    : [optional, implementation-dependent] string for returning subset of
 212            parameters
 213
 214 =cut
 215
 216 sub available_parameters {
 217     shift->throw_not_implemented;
 218 }
 219
 220 =head2 get_parameters
 221
 222  Title   : get_parameters
 223  Usage   : %params = $pobj->get_parameters;
 224  Function: Returns list of key-value pairs of parameter => value
 225  Returns : List of key-value pairs
 226  Args    : [optional] A string is allowed if subsets are wanted or (if a
 227            parameter subset is default) 'all' to return all parameters
 228
 229 =cut
 230
 231 sub get_parameters {
 232     shift->throw_not_implemented;
 233 }
 234
 235 =head1 to* methods
 236
 237 All to_* methods are implementation-specific
 238
 239 =cut
 240
 241 1;
 242