RNAProductTypeMapper.pm

Go to the documentation of this file.

 
=head1 LICENSE
 
See the NOTICE file distributed with this work for additional information
regarding copyright ownership.
 
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_code<->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_name = $rpt_mapper->type_code_to_class( 'generic' );
  my $type_code = $rpt_mapper->class_to_type_code( '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 $class_attribute_cache_map = {
    'Bio::EnsEMBL::RNAProduct' => { },
    'Bio::EnsEMBL::MicroRNA'   => {
      'arm' => 'mirna_arm',
    },
  };
  my $type_to_class_map = {
    'generic' => 'Bio::EnsEMBL::RNAProduct',
    'miRNA'   => 'Bio::EnsEMBL::MicroRNA',
  };
 
  my $self = bless {
    'class_attribute_cache_map' => $class_attribute_cache_map,
    'type_to_class_map'         => $type_to_class_map,
    'class_to_type_map'         => undef,
  }, $class;
 
  return $self;
}
 
 
=head2 class_attribute_cache_map
 
  Arg [1]    : string $class_name - fully qualified RNA-product class name
  Example    : my $attr_cache_map
                 = $mapper->class_attribute_cache_map( 'Bio::EnsEMBL::MicroRNA' );
  Description: For the given name of a class representing a mature RNA
               product, returns the map indicating which local members variables
               should be synchronised with which Attributes.
  Returntype : hashref
  Exceptions : throw if the class does not represent known RNA-product type
  Caller     : internal
  Status     : Stable
 
=cut
 
sub class_attribute_cache_map {
  my ( $self, $class_name ) = @_;
 
  my %map = %{ $self->{'class_attribute_cache_map'} };
  if ( !exists $map{$class_name} ) {
    throw( "Unknown RNA-product class name " . $class_name );
  }
 
  return $map{$class_name};
}
 
 
=head2 class_to_type_code
 
  Arg [1]    : string $class_name - fully qualified RNA-product class name
  Example    : my $type_code
                 = $mapper->class_to_type_code( 'Bio::EnsEMBL::MicroRNA' );
  Description: For the given name of a class representing a mature RNA
               product, returns the type code used to represent it in the
               Ensembl database.
  Returntype : string
  Exceptions : throw if the class does not represent known RNA-product type
  Caller     : internal
  Status     : Stable
 
=cut
 
sub class_to_type_code {
  my ( $self, $class_name ) = @_;
 
  if ( !defined( $self->{'class_to_type_map'} ) ) {
    $self->_generate_reverse_map();
  }
 
  my %map = %{ $self->{'class_to_type_map'} };
  if ( !exists $map{$class_name} ) {
    throw( "Unknown RNA-product class name " . $class_name );
  }
 
  return $map{$class_name};
}
 
 
=head2 type_code_to_class
 
  Arg [1]    : string $type_code - type code of RNA product
  Example    : my $class_name = $mapper->class_to_type_code( 1 );
  Description: For the type code representing a mature RNA product in the
               Ensembl database, return its API class name
  Returntype : string
  Exceptions : throw if the code does not represent known RNA-product type
  Caller     : internal
  Status     : Stable
 
=cut
 
sub type_code_to_class {
  my ( $self, $type_code ) = @_;
 
  my %map = %{ $self->{'type_to_class_map'} };
  if ( !exists $map{$type_code} ) {
    throw( "Unknown RNA-product type ID " . $type_code );
  }
 
  return $map{$type_code};
}
 
 
=head2 _generate_reverse_map
 
  Description: PRIVATE generates class_name->type_code map from the
               type_code->class_name one.
  Returntype : none
  Exceptions : none
  Caller     : internal
  Status     : Stable
 
=cut
 
sub _generate_reverse_map {
  my ($self) = @_;
 
  # Safe to use reverse because both keys and values are unique
  my %reversed_map = reverse %{$self->{'type_to_class_map'}};
  $self->{'class_to_type_map'} = \%reversed_map;
 
  return;
}
 
 
1;