Archive Ensembl HomeArchive Ensembl Home
DataFile.pm
Go to the documentation of this file.
00001 package Bio::EnsEMBL::DataFile;
00002 
00003 use strict;
00004 use warnings;
00005 
00006 use base qw/Bio::EnsEMBL::Storable/;
00007 
00008 use Bio::EnsEMBL::ApiVersion;
00009 use Bio::EnsEMBL::Utils::Argument qw/rearrange/;
00010 use Bio::EnsEMBL::Utils::Exception qw/throw warning/;
00011 use Bio::EnsEMBL::Utils::Scalar qw/:assert/;
00012 use Bio::EnsEMBL::Utils::URI qw/is_uri/;
00013 use File::Spec;
00014 use Scalar::Util qw(weaken isweak);
00015 
00016 =head2 new
00017 
00018   Arg [-ADAPTOR]      : Bio::EnsEMBL::DBSQL::DataFileAdaptor
00019   Arg [-DBID]         : Integer $dbID
00020   Arg [-COORD_SYSTEM] : Bio::EnsEMBL::CoordSystem $coord_system
00021   Arg [-ANALYSIS]     : Bio::EnsEMBL::Analysis $analysis
00022   Arg [-NAME]         : String $name
00023   Arg [-VERSION_LOCK] : Boolean $version_lock
00024   Arg [-ABSOLUTE]     : Boolean $absolute
00025   Arg [-URL]          : String $url
00026   Arg [-FILE_TYPE]    : String $file_type
00027   Example                 : Bio::EnsEMBL::DataFile->new();
00028   Description         : Returns a new instance of this object
00029   Returntype          : Bio::EnsEMBL::DataFile
00030   Exceptions          : Thrown if data is not as expected
00031 
00032 =cut
00033 
00034 sub new {
00035   my ($class, @args) = @_;
00036   my $self = $class->SUPER::new(@args);
00037   my ($coord_system, $analysis, $name, $version_lock, $absolute, $url, $file_type) = 
00038     rearrange([qw/coord_system analysis name version_lock absolute url file_type/], @args);
00039   
00040   $self->coord_system($coord_system);
00041   $self->analysis($analysis);
00042   $self->name($name);
00043   $self->version_lock($version_lock);
00044   $self->absolute($absolute);
00045   $self->url($url);
00046   $self->file_type($file_type);
00047   
00048   return $self;
00049 }
00050 
00051 =head2 new_fast
00052 
00053   Arg [1]    : hashref to be blessed
00054   Description: Construct a new Bio::EnsEMBL::Feature using the hashref.
00055   Exceptions : none
00056   Returntype : Bio::EnsEMBL::Feature
00057   Caller     : general, subclass constructors
00058   Status     : Stable
00059 
00060 =cut
00061 
00062 sub new_fast {
00063   my $class = shift;
00064   my $hashref = shift;
00065   my $self = bless $hashref, $class;
00066   weaken($self->{adaptor})  if ( ! isweak($self->{adaptor}) );
00067   return $self;
00068 }
00069 
00070 =head2 get_ExternalAdaptor
00071 
00072   Arg[1]        : Scalar; optional base path. Uses defaults if not given 
00073   Example           : my $ea = $df->get_ExternalAdaptor('/base/path');
00074   Description   : Delegates to the parent adaptor to retrieve the external 
00075                 adaptor for this data type
00076   Returntype    : Any; will be an adaptor that can read the given data file
00077   Exceptions    : Thrown if there is no attached adaptor. Otherwise 
00078 
00079 =cut
00080 
00081 sub get_ExternalAdaptor {
00082   my ($self, $base_path) = @_;
00083   my $adaptor = $self->adaptor();
00084   throw "No DataFileAdaptor found in this object. Cannot request ExternalAdaptor" if ! $adaptor;
00085   return $adaptor->DataFile_to_adaptor($self, $base_path);
00086 }
00087 
00088 =head2 path
00089 
00090   Arg[1]      : Scalar base of the path to use. Can be ignored if the instance
00091                 already represents a canonical path 
00092   Example           : my $f = $df->path();
00093   Description   : Used to generate the path to the file resource. Can return a
00094                 path to the file or a URL but it is up to the using code to
00095                 know how to interprate the different returned forms.
00096                 
00097                 If the data file url is canonical then this is just returned. 
00098                 If not then a path is generated of the form 
00099                 B</base/path/production_name/coord_system_version/[software_version/]db_group/name.ext> 
00100                 
00101   Returntype    : Scalar the absolute path/url to the given resource
00102   Exceptions    : Thrown if the linked Coordinate System lacks a version and the
00103                 current database also lacks a default version
00104   Caller        : public
00105 
00106 =cut
00107 
00108 
00109 sub path {
00110   my ($self, $base) = @_;
00111   
00112   return $self->url() if $self->absolute();
00113   
00114   $base = $self->adaptor()->get_base_path($base) if ! $base;
00115 
00116   my $production_name = $self->adaptor()->db()->get_MetaContainer()->get_production_name();
00117   my $cs_version = $self->coord_system()->version();
00118   if(! $cs_version) {
00119     my ($highest_cs) = @{$self->adaptor()->db()->get_CoordSystemAdaptor()->fetch_all()};
00120     $cs_version = $highest_cs->version();
00121   }
00122   if(!$cs_version) {
00123     my $name = $self->name();
00124     throw "The file '${name}' in species '${$production_name} is attached to a CoordinateSystem lacking a version and has no default assembly. Please fix";
00125   }
00126   
00127   my @portions;
00128   push(@portions, $production_name);
00129   push(@portions, $cs_version);
00130   push(@portions, software_version()) if $self->version_lock();
00131   push(@portions, $self->adaptor()->db()->group());
00132   
00133   #If URL is populated we assume we need to add this onto the end but removing the /
00134   if($self->url()) {
00135     my @split = split(/\//, $self->url());
00136     push(@portions, @split);
00137   }
00138   else {
00139     my $ext = $self->adaptor()->DataFile_to_extension($self);
00140     my $filename = sprintf(q{%s.%s}, $self->name(), $ext);
00141     push(@portions, $filename);
00142   }
00143   
00144   my $is_uri = is_uri($base);
00145   my $path;
00146   if($is_uri) {
00147     $path = join(q{/}, $base, @portions);
00148   }
00149   else {
00150     $path = File::Spec->catfile($base, @portions);
00151   }
00152   return $path;
00153 }
00154 
00155 =head2 coord_system
00156 
00157   Arg[1]      : Bio::EnsEMBL::CoordSystem Optional setter  
00158   Description   : Mutator for the coord system field. All files are linked to one
00159   Returntype    : Bio::EnsEMBL::CoordSystem
00160   Exceptions    : Thrown if not of the expected type
00161 
00162 =cut
00163 
00164 
00165 sub coord_system {
00166   my ($self, $coord_system) = @_;
00167   if(defined $coord_system) {
00168     assert_ref($coord_system, 'Bio::EnsEMBL::CoordSystem', 'coord_system');
00169     $self->{'coord_system'} = $coord_system;
00170   }
00171   return $self->{'coord_system'};
00172 }
00173 
00174 =head2 analysis
00175 
00176   Arg[1]      : Bio::EnsEMBL::Analysis Optional setter  
00177   Description : Mutator for the analysis field. All files are linked to one
00178   Returntype  : Bio::EnsEMBL::Analysis
00179   Exceptions  : Thrown if not of the expected type
00180 
00181 =cut
00182 
00183 sub analysis {
00184   my ($self, $analysis) = @_;
00185   if(defined $analysis) {
00186     assert_ref($analysis, 'Bio::EnsEMBL::Analysis', 'analysis');
00187     $self->{'analysis'} = $analysis;
00188   }
00189   return $self->{'analysis'};
00190 }
00191 
00192 =head2 name
00193 
00194   Arg[1]      : String Optional setter  
00195   Description : Mutator for the name of the file. Can be used in file location
00196                 generation
00197   Returntype  : String
00198 
00199 =cut
00200 
00201 sub name {
00202   my ($self, $name) = @_;
00203   if(defined $name) {
00204     $self->{'name'} = $name;
00205   }
00206   return $self->{'name'};
00207 }
00208 
00209 =head2 version_lock
00210 
00211   Arg[1]      : Boolean Optional setter  
00212   Description : Boolean indicating if the file is linked to the version of the
00213                 database it was found in.
00214   Returntype  : Boolean
00215 
00216 =cut
00217 
00218 sub version_lock {
00219   my ($self, $version_lock) = @_;
00220   if(defined $version_lock) {
00221     assert_boolean($version_lock, 'version_lock');
00222     $self->{'version_lock'} = $version_lock;
00223   }
00224   return $self->{'version_lock'};
00225 }
00226 
00227 =head2 absolute
00228 
00229   Arg[1]      : Boolean Optional setter  
00230   Description : Indicates if the URL of this file is an absolute one i.e. 
00231                 should be used verbatim or not.
00232   Returntype  : Boolean
00233 
00234 =cut
00235 
00236 sub absolute {
00237   my ($self, $absolute) = @_;
00238   if(defined $absolute) {
00239     assert_boolean($absolute, 'absolute');
00240     $self->{'absolute'} = $absolute;
00241   }
00242   return $self->{'absolute'};
00243 }
00244 
00245 =head2 url
00246 
00247   Arg[1]      : String Optional setter  
00248   Description : Location of the file. Can be optional and if set means once
00249                 we are in an automatic location use this value to locate
00250                 the file.
00251   Returntype  : String
00252 
00253 =cut
00254 
00255 sub url {
00256   my ($self, $url) = @_;
00257   $self->{'url'} = $url if defined $url;
00258   return $self->{'url'};
00259 }
00260 
00261 =head2 file_type
00262 
00263   Arg[1]      : String Optional setter  
00264   Description : The type of file we are working with. Can be used to generate
00265                 a file name.
00266   Returntype  : String
00267 
00268 =cut
00269 
00270 sub file_type {
00271   my ($self, $file_type) = @_;
00272   $self->{'file_type'} = $file_type if defined $file_type;
00273   return $self->{'file_type'};
00274 }
00275 
00276 1;