Bio/SearchIO/EventHandlerI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::SearchIO::EventHandlerI
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   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 =head1 NAME
  14
  15 Bio::SearchIO::EventHandlerI - An abstract Event Handler for Search Result parsing
  16
  17 =head1 SYNOPSIS
  18
  19 # do not use this object directly it is an interface
  20 # See Bio::SearchIO::SearchResultEventBuilder for an implementation
  21
  22     use Bio::SearchIO::SearchResultEventBuilder;
  23     my $handler = Bio::SearchIO::SearchResultEventBuilder->new();
  24
  25 =head1 DESCRIPTION
  26
  27 This interface describes the basic methods needed to handle Events
  28 thrown from parsing a Search Result such as FASTA, BLAST, or HMMer.
  29
  30 =head1 FEEDBACK
  31
  32 =head2 Mailing Lists
  33
  34 User feedback is an integral part of the evolution of this and other
  35 Bioperl modules. Send your comments and suggestions preferably to
  36 the Bioperl mailing list.  Your participation is much appreciated.
  37
  38   bioperl-l@bioperl.org                  - General discussion
  39   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  40
  41 =head2 Reporting Bugs
  42
  43 Report bugs to the Bioperl bug tracking system to help us keep track
  44 of the bugs and their resolution. Bug reports can be submitted via the
  45 web:
  46
  47   http://bugzilla.open-bio.org/
  48
  49 =head1 AUTHOR - Jason Stajich
  50
  51 Email jason-at-bioperl.org
  52
  53 =head1 APPENDIX
  54
  55 The rest of the documentation details each of the object methods.
  56 Internal methods are usually preceded with a _
  57
  58 =cut
  59
  60
  61 # Let the code begin...
  62
  63
  64 package Bio::SearchIO::EventHandlerI;
  65 use strict;
  66 use Carp;
  67
  68
  69 use base qw(Bio::Event::EventHandlerI);
  70
  71 =head2 start_result
  72
  73  Title   : start_result
  74  Usage   : $handler->start_result($data)
  75  Function: Begins a result event cycle
  76  Returns : none
  77  Args    : Type of Result
  78
  79 =cut
  80
  81 sub start_result {
  82     my ($self) = @_;
  83     $self->throw_not_implemented();
  84 }
  85
  86 =head2 end_result
  87
  88  Title   : end_result
  89  Usage   : $handler->end_result($data)
  90  Function: Ends a result event cycle
  91  Returns : Bio::Search::Result::ResultI object
  92  Args    : none
  93
  94
  95 =cut
  96
  97 sub end_result{
  98    my ($self,@args) = @_;
  99    $self->throw_not_implemented();
 100 }
 101
 102 =head2 start_hsp
 103
 104  Title   : start_hsp
 105  Usage   : $handler->start_hsp($data)
 106  Function: Start a HSP event cycle
 107  Returns : none
 108  Args    : type of element
 109            associated hashref
 110
 111 =cut
 112
 113 sub start_hsp{
 114    my ($self,@args) = @_;
 115    $self->throw_not_implemented();
 116 }
 117
 118 =head2 end_hsp
 119
 120  Title   : end_hsp
 121  Usage   : $handler->end_hsp()
 122  Function: Ends a HSP event cycle
 123  Returns : Bio::Search::HSP::HSPI object
 124  Args    : type of event and associated hashref
 125
 126 =cut
 127
 128 sub end_hsp{
 129    my ($self,@args) = @_;
 130    $self->throw_not_implemented();
 131 }
 132
 133 =head2 start_hit
 134
 135  Title   : start_hit
 136  Usage   : $handler->start_hit()
 137  Function: Starts a Hit event cycle
 138  Returns : none
 139  Args    : type of event and associated hashref
 140
 141
 142 =cut
 143
 144 sub start_hit {
 145    my ($self,@args) = @_;
 146    $self->throw_not_implemented
 147 }
 148
 149 =head2 end_hit
 150
 151  Title   : end_hit
 152  Usage   : $handler->end_hit()
 153  Function: Ends a Hit event cycle
 154  Returns : Bio::Search::Hit::HitI object
 155  Args    : type of event and associated hashref
 156
 157
 158 =cut
 159
 160 sub end_hit {
 161    my ($self,@args) = @_;
 162    $self->throw_not_implemented();
 163 }
 164
 165 =head2 start_iteration
 166
 167  Title   : start_iteration
 168  Usage   : $handler->start_iteration()
 169  Function: Starts an Iteration event cycle
 170  Returns : none
 171  Args    : type of event and associated hashref
 172
 173
 174 =cut
 175
 176 sub start_iteration {
 177    my ($self,@args) = @_;
 178    $self->throw_not_implemented
 179 }
 180
 181 =head2 end_iteration
 182
 183  Title   : end_iteration
 184  Usage   : $handler->end_iteration()
 185  Function: Ends an Iterationevent cycle
 186  Returns : Bio::Search::Iteration::IterationI object
 187  Args    : type of event and associated hashref
 188
 189
 190 =cut
 191
 192 sub end_iteration {
 193    my ($self,@args) = @_;
 194    $self->throw_not_implemented();
 195 }
 196
 197 =head2 register_factory
 198
 199  Title   : register_factory
 200  Usage   : $handler->register_factory('TYPE',$factory);
 201  Function: Register a specific factory for a object type class
 202  Returns : none
 203  Args    : string representing the class and
 204            Bio::Factory::ObjectFactoryI
 205
 206 See L<Bio::Factory::ObjectFactoryI> for more information
 207
 208 =cut
 209
 210 sub register_factory{
 211    my ($self,@args) = @_;
 212    $self->throw_not_implemented();
 213 }
 214
 215
 216 =head2 factory
 217
 218  Title   : factory
 219  Usage   : my $f = $handler->factory('TYPE');
 220  Function: Retrieves the associated factory for requested 'TYPE'
 221  Returns : a Bio::Factory::ObjectFactoryI
 222  Throws  : Bio::Root::BadParameter if none registered for the supplied type
 223  Args    : name of factory class to retrieve
 224
 225 See L<Bio::Factory::ObjectFactoryI> for more information
 226
 227 =cut
 228
 229 sub factory{
 230    my ($self,@args) = @_;
 231    $self->throw_not_implemented();
 232 }
 233
 234
 235 =head2 Bio::Event::EventHandlerI methods
 236
 237 =cut
 238
 239 =head2 will_handle
 240
 241  Title   : will_handle
 242  Usage   : if( $handler->will_handle($event_type) ) { ... }
 243  Function: Tests if this event builder knows how to process a specific event
 244  Returns : boolean
 245  Args    : event type name
 246
 247
 248 =cut
 249
 250 =head2 SAX methods
 251
 252 See L<Bio::Event::EventHandlerI> for the additional SAX methods.
 253
 254 =cut
 255
 256
 257 1;