Bio/ParameterBaseI.pm

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