lib/Bio/DB/UpdateableSeqI.pm

   1 #
   2 #
   3 # BioPerl module for Bio::DB::UpdateableSeqI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Jason Stajich <jason@bioperl.org>
   8 #
   9 # Copyright Jason Stajich
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # _history
  14 # June 18, 2000 - module begun
  15 #
  16 # POD Doc - main docs before code
  17
  18 =head1 NAME
  19
  20 Bio::DB::UpdateableSeqI - An interface for writing to a database of sequences.
  21
  22 =head1 SYNOPSIS
  23
  24     # get a Bio::DB::UpdateableSeqI somehow
  25     eval {
  26         my ( @updatedseqs, @newseqs, @deadseqs);
  27         my $seq = $db->get_Seq_by_id('ROA1_HUMAN');
  28         $seq->desc('a new description');
  29
  30         push @updatedseqs, $seq;
  31
  32         $db->write_seq(\@updatedseqs, \@newseqs, \@deadseqs);
  33     };
  34     if( $@ ) {
  35         print STDERR "an error when trying to write seq : $@\n";
  36     }
  37
  38 =head1 DESCRIPTION
  39
  40 This module seeks to provide a simple method for pushing sequence changes
  41 back to a Sequence Database - which can be an SQL compliant database, a file
  42 based database, AceDB, etc.
  43
  44 =head1 AUTHOR
  45
  46 Jason Stajich E<lt>jason@bioperl.orgE<gt>
  47
  48 =head2 Support
  49
  50 Please direct usage questions or support issues to the mailing list:
  51
  52 I<bioperl-l@bioperl.org>
  53
  54 rather than to the module maintainer directly. Many experienced and
  55 reponsive experts will be able look at the problem and quickly
  56 address it. Please include a thorough description of the problem
  57 with code and data examples if at all possible.
  58
  59 =head2 Reporting Bugs
  60
  61 Report bugs to the Bioperl bug tracking system to help us keep track
  62 the bugs and their resolution. Bug reports can be submitted via the
  63 web:
  64
  65   https://github.com/bioperl/bioperl-live/issues
  66
  67 =head1 APPENDIX
  68
  69 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
  70
  71 =cut
  72
  73 #Lets start some code
  74
  75 package Bio::DB::UpdateableSeqI;
  76
  77 use strict;
  78
  79
  80
  81 use base qw(Bio::DB::SeqI);
  82
  83 =head2 write_seq
  84
  85   Title   : write_seq
  86   Usage   : write_seq(\@updatedseqs, \@addedseqs, \@deadseqs)
  87   Function: updates sequences in first array,
  88             adds sequences in the second array,
  89             and removes sequences in the third array.
  90   Example :
  91   Returns :
  92   Args    : arrays of sequence objects that must be obtained from
  93             Bio::DB::UpdateableSeqI.
  94
  95 =cut
  96
  97 sub write_seq {
  98     my ($self) = @_;
  99
 100     $self->throw("Abstract database call of write_seq. Your database has not implemented this method!");
 101
 102 }
 103
 104 =head2 _add_seq
 105
 106  Title   : _add_seq
 107  Usage   : _add_seq($seq)
 108  Function: Adds a new sequence
 109  Example :
 110  Returns : will throw an exception if
 111            sequences accession number already exists
 112  Args    : a new seq object - should have an accession number
 113
 114 =cut
 115
 116 sub _add_seq {
 117     my ($self ) = @_;
 118
 119     $self->throw("Abstract database call of _add_seq. Your database has not implemented this method!");
 120
 121 }
 122
 123 =head2 _remove_seq
 124
 125  Title   : _remove_seq
 126  Usage   : _remove_seq($seq)
 127  Function: Removes an existing sequence
 128  Example :
 129  Returns : will throw an exception if
 130            sequence does not exists for the primary_id
 131  Args    : a seq object that was retrieved from Bio::DB::UpdateableSeqI
 132
 133 =cut
 134
 135 sub _remove_seq {
 136     my ($self) = @_;
 137
 138     $self->throw("Abstract database call of _remove_seq. Your database has not implemented this method!");
 139
 140 }
 141
 142 =head2 _update_seq
 143
 144  Title   : _update_seq
 145  Usage   : _update_seq($seq)
 146  Function: Updates a sequence
 147  Example :
 148  Returns : will throw an exception if
 149            sequence is out of sync from expected val.
 150  Args    : a seq object that was retrieved from Bio::DB::UpdateableSeqI
 151
 152 =cut
 153
 154 sub _update_seq {
 155     my ($self) = @_;
 156
 157     $self->throw("Abstract database call of _update_seq. Your database has not implemented this method!");
 158
 159 }
 160
 161
 162 =head1 Methods inherieted from Bio::DB::RandomAccessI
 163
 164 =head2 get_Seq_by_id
 165
 166  Title   : get_Seq_by_id
 167  Usage   : $seq = $db->get_Seq_by_id('ROA1_HUMAN')
 168  Function: Gets a Bio::Seq object by its name
 169  Returns : a Bio::Seq object
 170  Args    : the id (as a string) of a sequence
 171  Throws  : "id does not exist" exception
 172
 173
 174 =cut
 175
 176 =head2 get_Seq_by_acc
 177
 178  Title   : get_Seq_by_acc
 179  Usage   : $seq = $db->get_Seq_by_acc('X77802');
 180  Function: Gets a Bio::Seq object by accession number
 181  Returns : A Bio::Seq object
 182  Args    : accession number (as a string)
 183  Throws  : "acc does not exist" exception
 184
 185
 186 =cut
 187
 188 =head1 Methods inheirited from Bio::DB::SeqI
 189
 190 =head2 get_PrimarySeq_stream
 191
 192  Title   : get_PrimarySeq_stream
 193  Usage   : $stream = get_PrimarySeq_stream
 194  Function: Makes a Bio::DB::SeqStreamI compliant object
 195            which provides a single method, next_primary_seq
 196  Returns : Bio::DB::SeqStreamI
 197  Args    : none
 198
 199
 200 =cut
 201
 202 =head2 get_all_primary_ids
 203
 204  Title   : get_all_ids
 205  Usage   : @ids = $seqdb->get_all_primary_ids()
 206  Function: gives an array of all the primary_ids of the
 207            sequence objects in the database. These
 208            maybe ids (display style) or accession numbers
 209            or something else completely different - they
 210            *are not* meaningful outside of this database
 211            implementation.
 212  Example :
 213  Returns : an array of strings
 214  Args    : none
 215
 216
 217 =cut
 218
 219 =head2 get_Seq_by_primary_id
 220
 221  Title   : get_Seq_by_primary_id
 222  Usage   : $seq = $db->get_Seq_by_primary_id($primary_id_string);
 223  Function: Gets a Bio::Seq object by the primary id. The primary
 224            id in these cases has to come from $db->get_all_primary_ids.
 225            There is no other way to get (or guess) the primary_ids
 226            in a database.
 227
 228            The other possibility is to get Bio::PrimarySeqI objects
 229            via the get_PrimarySeq_stream and the primary_id field
 230            on these objects are specified as the ids to use here.
 231  Returns : A Bio::Seq object
 232  Args    : accession number (as a string)
 233  Throws  : "acc does not exist" exception
 234
 235
 236 =cut
 237
 238 1;
 239
 240
 241