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 Support
  69
  70 Please direct usage questions or support issues to the mailing list:
  71
  72 I<bioperl-l@bioperl.org>
  73
  74 rather than to the module maintainer directly. Many experienced and
  75 reponsive experts will be able look at the problem and quickly
  76 address it. Please include a thorough description of the problem
  77 with code and data examples if at all possible.
  78
  79 =head2 Reporting Bugs
  80
  81 Report bugs to the Bioperl bug tracking system to help us keep track
  82 the bugs and their resolution.  Bug reports can be submitted via the
  83 web:
  84
  85   http://bugzilla.open-bio.org/
  86
  87 =head1 AUTHOR - Ewan Birney
  88
  89 Email birney@ebi.ac.uk
  90
  91 =cut
  92
  93 package Bio::IdentifiableI;
  94 use strict;
  95
  96
  97 use base qw(Bio::Root::RootI);
  98
  99 =head1 Implementation Specific Functions
 100
 101 These functions are the ones that a specific implementation must
 102 define.
 103
 104 =head2 object_id
 105
 106  Title   : object_id
 107  Usage   : $string    = $obj->object_id()
 108  Function: a string which represents the stable primary identifier
 109            in this namespace of this object. For DNA sequences this
 110            is its accession_number, similarly for protein sequences
 111  Returns : A scalar
 112  Status  : Virtual
 113
 114 =cut
 115
 116 sub object_id {
 117    my ($self) = @_;
 118    $self->throw_not_implemented();
 119 }
 120
 121 =head2 version
 122
 123  Title   : version
 124  Usage   : $version    = $obj->version()
 125  Function: a number which differentiates between versions of
 126            the same object. Higher numbers are considered to be
 127            later and more relevant, but a single object described
 128            the same identifier should represent the same concept
 129  Returns : A number
 130  Status  : Virtual
 131
 132 =cut
 133
 134 sub version {
 135    my ($self) = @_;
 136    $self->throw_not_implemented();
 137 }
 138
 139
 140 =head2 authority
 141
 142  Title   : authority
 143  Usage   : $authority    = $obj->authority()
 144  Function: a string which represents the organisation which
 145            granted the namespace, written as the DNS name for
 146            organisation (eg, wormbase.org)
 147  Returns : A scalar
 148  Status  : Virtual
 149
 150 =cut
 151
 152 sub authority {
 153    my ($self) = @_;
 154    $self->throw_not_implemented();
 155 }
 156
 157
 158 =head2 namespace
 159
 160  Title   : namespace
 161  Usage   : $string    = $obj->namespace()
 162  Function: A string representing the name space this identifier
 163            is valid in, often the database name or the name
 164            describing the collection
 165  Returns : A scalar
 166  Status  : Virtual
 167
 168 =cut
 169
 170 sub namespace {
 171    my ($self) = @_;
 172    $self->throw_not_implemented();
 173 }
 174
 175
 176 =head1 Implementation optional functions
 177
 178 These functions are helper functions that are provided by
 179 the interface but can be overridden if so wished
 180
 181 =head2 lsid_string
 182
 183  Title   : lsid_string
 184  Usage   : $string   = $obj->lsid_string()
 185  Function: a string which gives the LSID standard
 186            notation for the identifier of interest
 187
 188
 189  Returns : A scalar
 190
 191 =cut
 192
 193 sub lsid_string {
 194   my ($self) = @_;
 195
 196   return $self->authority.":".$self->namespace.":".$self->object_id;
 197 }
 198
 199
 200
 201 =head2 namespace_string
 202
 203  Title   : namespace_string
 204  Usage   : $string   = $obj->namespace_string()
 205  Function: a string which gives the common notation of
 206            namespace:object_id.version
 207  Returns : A scalar
 208
 209 =cut
 210
 211 sub namespace_string {
 212   my ($self) = @_;
 213
 214   return $self->namespace.":".$self->object_id .
 215       (defined($self->version()) ? ".".$self->version : '');
 216 }
 217
 218 1;