Bio/Tools/EUtilities/Cookie.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::Cookie
   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::Cookie - lightweight implementation of HistoryI
  18 interface (not bound to filehandles, extraneous methods, etc).
  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 This class is the simplest implementation and merely holds data for future
  46 queries from any HistoryI. 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::History;
  83 use strict;
  84 use warnings;
  85
  86 use base qw(Bio::Root::Root Bio::Tools::EUtilities::HistoryI);
  87 use Data::Dumper;
  88
  89 sub new {
  90     my ($class, @args) = @_;
  91     my $self = $class->SUPER::new(@args);
  92     my ($eutil) = $self->_rearrange([qw(eutil)],@args);
  93     $eutil || $self->throw('eutil not defined');
  94     $self->eutil($eutil);
  95     $self->datatype('cookie');
  96     return $self;
  97 }
  98
  99 =head2 history
 100
 101  Title    : history
 102  Usage    : my ($webenv, $qk) = $hist->history
 103  Function : Get/Set two-element list of webenv() and query_key()
 104  Returns  : array
 105  Args     : two-element list of webenv, query key
 106
 107 =cut
 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 =head2 get_query_key
 121
 122  Title    : get_query_key
 123  Usage    : my $qk = $hist->get_query_key
 124  Function : returns query key (integer) for the history number for this session
 125  Returns  : integer
 126  Args     : none
 127
 128 =cut
 129
 130 sub _add_data {
 131     my ($self, $simple) = @_;
 132     if (!exists $simple->{WebEnv} || !exists $simple->{QueryKey}) {
 133         $self->debug("Data:",Dumper($simple));
 134         $self->throw("Missing webenv/query key in history output");
 135     }
 136     $self->{_webenv} = $simple->{WebEnv} && delete $simple->{WebEnv};
 137     $self->{_querykey} = $simple->{QueryKey} && delete $simple->{QueryKey};
 138 }
 139
 140 1;
 141 __END__