Bio/Tools/EUtilities/HistoryI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::HistoryI
   4 #
   5 # Cared for by Chris Fields
   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 # Part of the EUtilities BioPerl package
  14
  15 =head1 NAME
  16
  17 Bio::Tools::EUtilities::HistoryI - simple extension of EUtilDataI interface
  18 class for classes which hold NCBI server history data
  19
  20 =head1 SYNOPSIS
  21
  22   #should work for any class which is-a HistoryI
  23
  24   if ($obj->has_History) {
  25       # do something here
  26   }
  27
  28   ($webenv, $querykey) = $obj->history;
  29
  30   $obj->history($webenv, $querykey);
  31
  32   $webenv = $obj->get_webenv;
  33
  34   $query_key = $obj->get_query_key;
  35
  36 =head1 DESCRIPTION
  37
  38 This class extends methods for any EUtilDataI implementation allow instances to
  39 dealwith NCBI history data (WebEnv and query_key).  These can be used as
  40 parameters for further queries against data sets stored on the NCBI server, much
  41 like NCBI's Entrez search history. These are important when one wants to run
  42 complex queries using esearch, retrieve related data using elink, and retrieve
  43 large datasets using epost/efetch.
  44
  45 The simplest implementation is Bio::Tools::EUtilities::History, which holds the
  46 history data for epost.  See also Bio::Tools::EUtilities::Query (esearch) and
  47 Bio::Tools::EUtilities::LinkSet (elink), which also implement HistoryI.
  48
  49 =cut
  50
  51 =head1 FEEDBACK
  52
  53 =head2 Mailing Lists
  54
  55 User feedback is an integral part of the evolution of this and other Bioperl
  56 modules. Send your comments and suggestions preferably to one of the Bioperl
  57 mailing lists. Your participation is much appreciated.
  58
  59   bioperl-l@lists.open-bio.org               - General discussion
  60   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  61
  62 =head2 Reporting Bugs
  63
  64 Report bugs to the Bioperl bug tracking system to help us keep track the bugs
  65 and their resolution. Bug reports can be submitted via the web.
  66
  67   http://bugzilla.open-bio.org/
  68
  69 =head1 AUTHOR
  70
  71 Email cjfields at uiuc dot edu
  72
  73 =head1 APPENDIX
  74
  75 The rest of the documentation details each of the object methods. Internal
  76 methods are usually preceded with a _
  77
  78 =cut
  79
  80 # Let the code begin...
  81
  82 package Bio::Tools::EUtilities::HistoryI;
  83 use strict;
  84 use warnings;
  85
  86 use base qw(Bio::Tools::EUtilities::EUtilDataI);
  87
  88 =head2 history
  89
  90  Title    : history
  91  Usage    : my ($webenv, $qk) = $hist->history
  92  Function : Get/Set two-element list of webenv() and query_key()
  93  Returns  : array
  94  Args     : two-element list of webenv, querykey
  95
  96 =cut
  97
  98 sub history {
  99     my $self = shift;
 100     $self->parse_data if ($self->can('parse_data') && !$self->data_parsed);
 101     if (@_) {
 102         my ($webenv, $querykey) = (shift, shift);
 103         $self->throw("Missing part of cookie!") if (!$webenv || !$querykey);
 104         ($self->{'_webenv'}, $self->{'_querykey'}) = ($webenv, $querykey);
 105     }
 106     return ($self->get_webenv, $self->get_query_key);
 107 }
 108
 109 =head2 get_webenv
 110
 111  Title    : get_webenv
 112  Usage    : my $webenv = $hist->get_webenv
 113  Function : returns web environment key needed to retrieve results from
 114             NCBI server
 115  Returns  : string (encoded key)
 116  Args     : none
 117
 118 =cut
 119
 120 sub get_webenv {
 121     my $self = shift;
 122     $self->parse_data if ($self->can('parse_data') && !$self->data_parsed);
 123     return $self->{'_webenv'};
 124 }
 125
 126 =head2 get_query_key
 127
 128  Title    : get_query_key
 129  Usage    : my $qk = $hist->get_query_key
 130  Function : returns query key (integer) for the history number for this session
 131  Returns  : integer
 132  Args     : none
 133
 134 =cut
 135
 136 sub get_query_key {
 137     my $self = shift;
 138     $self->parse_data if ($self->can('parse_data') && !$self->data_parsed);
 139     return $self->{'_querykey'};
 140 }
 141
 142 1;
 143 __END__