Bio/Map/PositionHandlerI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Map::PositionHandlerI
   4 #
   5 # Cared for by Sendu Bala <bix@sendu.me.uk>
   6 #
   7 # Copyright Sendu Bala
   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::Map::PositionHandlerI - A Position Handler Interface
  16
  17 =head1 SYNOPSIS
  18
  19     # do not use this module directly
  20     # See Bio::Map::PositionHandler for an example of
  21     # implementation.
  22
  23 =head1 DESCRIPTION
  24
  25 This interface describes the basic methods required for Position Handlers. A
  26 Position Handler copes with the coordination of different Bio::Map::EntityI
  27 objects, adding and removing them from each other and knowning who belongs to
  28 who. These relationships between objects are based around shared Positions,
  29 hence PositionHandler.
  30
  31 =head1 FEEDBACK
  32
  33 =head2 Mailing Lists
  34
  35 User feedback is an integral part of the evolution of this and other
  36 Bioperl modules. Send your comments and suggestions preferably to
  37 the Bioperl mailing list.  Your participation is much appreciated.
  38
  39   bioperl-l@bioperl.org                  - General discussion
  40   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  41
  42 =head2 Reporting Bugs
  43
  44 Report bugs to the Bioperl bug tracking system to help us keep track
  45 of the bugs and their resolution. Bug reports can be submitted via the
  46 web:
  47
  48   http://bugzilla.open-bio.org/
  49
  50 =head1 AUTHOR - Sendu Bala
  51
  52 Email bix@sendu.me.uk
  53
  54 =head1 APPENDIX
  55
  56 The rest of the documentation details each of the object methods.
  57 Internal methods are usually preceded with a _
  58
  59 =cut
  60
  61 # Let the code begin...
  62
  63 package Bio::Map::PositionHandlerI;
  64 use strict;
  65
  66 use base qw(Bio::Root::RootI);
  67
  68 =head2 General methods
  69
  70 =cut
  71
  72 =head2 register
  73
  74  Title   : register
  75  Usage   : $position_handler->register();
  76  Function: Ask this Position Handler to look after your entity relationships.
  77  Returns : n/a
  78  Args    : none
  79
  80 =cut
  81
  82 sub register {
  83     my $self = shift;
  84     $self->throw_not_implemented();
  85 }
  86
  87 =head2 index
  88
  89  Title   : index
  90  Usage   : my $index = $position_handler->index();
  91  Function: Get the unique registry index for yourself, generated during the
  92            resistration process.
  93  Returns : int
  94  Args    : none
  95
  96 =cut
  97
  98 sub index {
  99     my $self = shift;
 100     $self->throw_not_implemented();
 101 }
 102
 103 =head2 get_entity
 104
 105  Title   : get_entity
 106  Usage   : my $entity = $position_handler->get_entity($index);
 107  Function: Get the entity that corresponds to the supplied registry index.
 108  Returns : Bio::Map::EntityI object
 109  Args    : int
 110
 111 =cut
 112
 113 sub get_entity {
 114         my $self = shift;
 115     $self->throw_not_implemented();
 116 }
 117
 118 =head2 Methods for Bio::Map::PositionI objects
 119
 120 =cut
 121
 122 =head2 map
 123
 124  Title   : map
 125  Usage   : my $map = $position_handler->map();
 126            $position_handler->map($map);
 127  Function: Get/Set the map you are on. You must be a Position.
 128  Returns : L<Bio::Map::MapI>
 129  Args    : none to get, OR
 130            new L<Bio::Map::MapI> to set
 131
 132 =cut
 133
 134 sub map {
 135     my $self = shift;
 136     $self->throw_not_implemented();
 137 }
 138
 139 =head2 element
 140
 141  Title   : element
 142  Usage   : my $element = $position_handler->element();
 143            $position_handler->element($element);
 144  Function: Get/Set the map element you are for. You must be a Position.
 145  Returns : L<Bio::Map::MappableI>
 146  Args    : none to get, OR
 147            new L<Bio::Map::MappableI> to set
 148
 149 =cut
 150
 151 sub element {
 152     my $self = shift;
 153     $self->throw_not_implemented();
 154 }
 155
 156 =head2 Methods for all other Bio::Map::EntityI objects
 157
 158 =cut
 159
 160 =head2 add_positions
 161
 162  Title   : add_positions
 163  Usage   : $position_handler->add_positions($pos1, $pos2, ...);
 164  Function: Add some positions to yourself. You can't be a position.
 165  Returns : n/a
 166  Args    : Array of Bio::Map::PositionI objects
 167
 168 =cut
 169
 170 sub add_positions {
 171     my $self = shift;
 172     $self->throw_not_implemented();
 173 }
 174
 175 =head2 get_positions
 176
 177  Title   : get_positions
 178  Usage   : my @positions = $position_handler->get_positions();
 179  Function: Get all your positions. You can't be a Position.
 180  Returns : Array of Bio::Map::PositionI objects
 181  Args    : none for all, OR
 182            Bio::Map::EntityI object to limit the Positions to those that
 183            are shared by you and this other entity.
 184
 185 =cut
 186
 187 sub get_positions {
 188     my $self = shift;
 189     $self->throw_not_implemented();
 190 }
 191
 192 =head2 purge_positions
 193
 194  Title   : purge_positions
 195  Usage   : $position_handler->purge_positions();
 196  Function: Remove all positions from yourself. You can't be a Position.
 197  Returns : n/a
 198  Args    : none to remove all, OR
 199            Bio::Map::PositionI object to remove only that entity, OR
 200            Bio::Map::EntityI object to limit the removal to those Positions that
 201            are shared by you and this other entity.
 202
 203 =cut
 204
 205 sub purge_positions {
 206     my $self = shift;
 207     $self->throw_not_implemented();
 208 }
 209
 210 =head2 get_other_entities
 211
 212  Title   : get_other_entities
 213  Usage   : my @entities = $position_handler->get_other_entities();
 214  Function: Get all the entities that share your Positions. You can't be a
 215            Position.
 216  Returns : Array of Bio::Map::EntityI objects
 217  Args    : none
 218
 219 =cut
 220
 221 sub get_other_entities {
 222     my $self = shift;
 223     $self->throw_not_implemented();
 224 }
 225
 226 1;