RNAProductTypeMapper.pm 5.41 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

=head1 LICENSE

Copyright [2018] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

=cut

=head1 CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

=cut

=head1 NAME

Bio::EnsEMBL::Utils::RNAProductTypeMapper - Utility class for mapping
between RNA-product types used in the Ensembl database and respective
Perl API classes.

=head1 DESCRIPTION

The purpose of this class is to hide from the users the mappings
between classes representing various mature RNA products
(e.g. generic, miRNA, circRNA etc.) and their respective identifiers
in the Ensembl database. In principle there should be no need for
users to call the mapper directly; it is invoked internally whenever
such mappings are needed (e.g. in RNAProduct constructor or in
RNAProductAdaptor).

Note that the type_id<->class_name mappings are hardcoded here,
specifically in the constructor, instead of being fetched from the
database. This is so that it is not possible for someone to trigger
construction of arbitrary objects by having modified class names
stored in the database.

=head1 SYNOPSIS

  my $rpt_mapper = Bio::EnsEMBL::Utils::RNAProductTypeMapper->new();

  my $class = $rpt_mapper->type_id_to_class( 1 );
  my $type_id = $rpt_mapper->class_to_type_id( 'Bio::EnsEMBL::MicroRNA' );

=cut

package Bio::EnsEMBL::Utils::RNAProductTypeMapper;

use strict;
use warnings;

use Bio::EnsEMBL::Utils::Exception qw( throw warning );



my $type_mapper;


=head2 mapper

  Example    : my $mapper = Bio::EnsEMBL::Utils::RNAProductTypeMapper->mapper();
  Description: Retrieves an instance of RNAProductTypeMapper from its module,
               reusing an existing one should it exist.
  Returntype : Bio::EnsEMBL::Utils::RNAProductTypeMapper
  Exceptions : none
  Caller     : internal
  Status     : Stable

=cut

sub mapper {
  if ( !defined($type_mapper) ) {
    $type_mapper = Bio::EnsEMBL::Utils::RNAProductTypeMapper->new();
  }
  return $type_mapper;
}


=head2 new

  Example    : my $mapper = Bio::EnsEMBL::Utils::RNAProductTypeMapper->new();
  Description: Constructor.  Creates a new RNAProductTypeMapper object.
               Not particularly useful for end users because all
               RNAProductTypeMapper objects are identical; use mapper()
               instead.
  Returntype : Bio::EnsEMBL::Utils::RNAProductTypeMapper
  Exceptions : none
  Caller     : internal
  Status     : Stable

=cut

sub new {
  my ( $caller ) = @_;
  my $class = ref( $caller ) || $caller;

  # Declare this here rather than in the package scope so that the map
  # cannot be modified (we do not presently use Readonly in the Core
  # API code), accidentally or otherwise.
  my $id_to_class_map = {
    1 => 'Bio::EnsEMBL::RNAProduct',
    2 => 'Bio::EnsEMBL::MicroRNA',
  };

  my $self = bless {
    'id_to_class_map' => $id_to_class_map,
    'class_to_id_map' => undef,
  }, $class;

  return $self;
}


=head2 class_to_type_id

  Arg [1]    : string $class_name - fully qualified rnaproduct class name
  Example    : my $type_id
                 = $mapper->class_to_type_id( 'Bio::EnsEMBL::MicroRNA' );
  Description: For the given name of a class representing a mature RNA
               product, returns the type ID used to reference it in the
               Ensembl database.
  Returntype : int
  Exceptions : throw if the class does not represent known RNA-product type
  Caller     : internal
  Status     : Stable

=cut

sub class_to_type_id {
  my ( $self, $class_name ) = @_;

  if ( !defined( $self->{'class_to_id_map'} ) ) {
    $self->_generate_reverse_map();
  }

  my %map = %{ $self->{'class_to_id_map'} };
  if ( !exists $map{$class_name} ) {
    throw( "Unknown RNA-product class name " . $class_name );
  }

  return $map{$class_name};
}


=head2 type_id_to_class

  Arg [1]    : int $type_id - internal type identified of rnaproduct
  Example    : my $class_name = $mapper->class_to_type_id( 1 );
  Description: For the type ID referencing a mature RNA product in the
               Ensembl database, return its API class name
  Returntype : string
  Exceptions : throw if the ID does not represent known RNA-product type
  Caller     : internal
  Status     : Stable

=cut

sub type_id_to_class {
  my ( $self, $type_id ) = @_;

  my %map = %{ $self->{'id_to_class_map'} };
  if ( !exists $map{$type_id} ) {
    throw( "Unknown RNA-product type ID " . $type_id );
  }

  return $map{$type_id};
}

# _generate_reverse_map

#  Description: PRIVATE generates class_name->type_id map from the
#               type_id->class_name one.
#  Returntype : none
#  Exceptions : none
#  Caller     : internal
#  Status     : Stable

sub _generate_reverse_map {
  my ($self) = @_;

  # Safe to use reverse because both keys and values are unique
  my %reversed_map = reverse %{$self->{'id_to_class_map'}};
  $self->{'class_to_id_map'} = \%reversed_map;

  return;
}


1;