Bio/IdentifiableI.pm

   1 # $Id$
   2 #
   3 # This module is licensed under the same terms as Perl itself. You use,
   4 # modify, and redistribute it under the terms of the Perl Artistic License.
   5 #
   6
   7 =head1 NAME
   8
   9 Bio::IdentifiableI - interface for objects with identifiers
  10
  11 =head1 SYNOPSIS
  12
  13     # to test this is an identifiable object
  14
  15     $obj->isa("Bio::IdentifiableI") ||
  16       $obj->throw("$obj does not implement the Bio::IdentifiableI interface");
  17
  18     # Accessors
  19
  20     $object_id = $obj->object_id();
  21     $namespace = $obj->namespace();
  22     $authority = $obj->authority();
  23     $version   = $obj->version();
  24     # Gets authority:namespace:object_id
  25     $lsid = $obj->lsid_string();
  26     # Gets namespace:object_id.version
  27     $ns_string = $obj->namespace_string();
  28
  29 =head1 DESCRIPTION
  30
  31 This interface describes methods expected on identifiable objects, i.e.
  32 ones which have identifiers expected to make sense across a number of
  33 instances and/or domains. This interface is modeled after pretty much
  34 ubiquitous ideas for names in bioinformatics being
  35
  36  databasename:object_id.version
  37
  38 Example:
  39
  40  swissprot:P012334.2
  41
  42 or:
  43
  44  GO:0007048
  45
  46 The object will also work with LSID proposals which adds the concept of an
  47 authority, being the DNS name of the organisation assigning the namespace.
  48 See L<http://lsid.sourceforge.net/>.
  49
  50 Helper functions are provided to make useful strings:
  51
  52   lsid_string - string complying to the LSID standard
  53
  54   namespace_string - string complying to the usual convention of
  55                      namespace:object_id.version
  56
  57 =head1 FEEDBACK
  58
  59 =head2 Mailing Lists
  60
  61 User feedback is an integral part of the evolution of this and other
  62 Bioperl modules. Send your comments and suggestions preferably to one
  63 of the Bioperl mailing lists.  Your participation is much appreciated.
  64
  65   bioperl-l@bioperl.org                  - General discussion
  66   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  67
  68 =head2 Reporting Bugs
  69
  70 Report bugs to the Bioperl bug tracking system to help us keep track
  71 the bugs and their resolution.  Bug reports can be submitted via the
  72 web:
  73
  74   http://bugzilla.open-bio.org/
  75
  76 =head1 AUTHOR - Ewan Birney
  77
  78 Email birney@ebi.ac.uk
  79
  80 =cut
  81
  82 package Bio::IdentifiableI;
  83 use strict;
  84
  85
  86 use base qw(Bio::Root::RootI);
  87
  88 =head1 Implementation Specific Functions
  89
  90 These functions are the ones that a specific implementation must
  91 define.
  92
  93 =head2 object_id
  94
  95  Title   : object_id
  96  Usage   : $string    = $obj->object_id()
  97  Function: a string which represents the stable primary identifier
  98            in this namespace of this object. For DNA sequences this
  99            is its accession_number, similarly for protein sequences
 100  Returns : A scalar
 101  Status  : Virtual
 102
 103 =cut
 104
 105 sub object_id {
 106    my ($self) = @_;
 107    $self->throw_not_implemented();
 108 }
 109
 110 =head2 version
 111
 112  Title   : version
 113  Usage   : $version    = $obj->version()
 114  Function: a number which differentiates between versions of
 115            the same object. Higher numbers are considered to be
 116            later and more relevant, but a single object described
 117            the same identifier should represent the same concept
 118  Returns : A number
 119  Status  : Virtual
 120
 121 =cut
 122
 123 sub version {
 124    my ($self) = @_;
 125    $self->throw_not_implemented();
 126 }
 127
 128
 129 =head2 authority
 130
 131  Title   : authority
 132  Usage   : $authority    = $obj->authority()
 133  Function: a string which represents the organisation which
 134            granted the namespace, written as the DNS name for
 135            organisation (eg, wormbase.org)
 136  Returns : A scalar
 137  Status  : Virtual
 138
 139 =cut
 140
 141 sub authority {
 142    my ($self) = @_;
 143    $self->throw_not_implemented();
 144 }
 145
 146
 147 =head2 namespace
 148
 149  Title   : namespace
 150  Usage   : $string    = $obj->namespace()
 151  Function: A string representing the name space this identifier
 152            is valid in, often the database name or the name
 153            describing the collection
 154  Returns : A scalar
 155  Status  : Virtual
 156
 157 =cut
 158
 159 sub namespace {
 160    my ($self) = @_;
 161    $self->throw_not_implemented();
 162 }
 163
 164
 165 =head1 Implementation optional functions
 166
 167 These functions are helper functions that are provided by
 168 the interface but can be overridden if so wished
 169
 170 =head2 lsid_string
 171
 172  Title   : lsid_string
 173  Usage   : $string   = $obj->lsid_string()
 174  Function: a string which gives the LSID standard
 175            notation for the identifier of interest
 176
 177
 178  Returns : A scalar
 179
 180 =cut
 181
 182 sub lsid_string {
 183   my ($self) = @_;
 184
 185   return $self->authority.":".$self->namespace.":".$self->object_id;
 186 }
 187
 188
 189
 190 =head2 namespace_string
 191
 192  Title   : namespace_string
 193  Usage   : $string   = $obj->namespace_string()
 194  Function: a string which gives the common notation of
 195            namespace:object_id.version
 196  Returns : A scalar
 197
 198 =cut
 199
 200 sub namespace_string {
 201   my ($self) = @_;
 202
 203   return $self->namespace.":".$self->object_id .
 204       (defined($self->version()) ? ".".$self->version : '');
 205 }
 206
 207 1;