Bio/Tools/EUtilities/HistoryI.pm

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