|
0
|
1 =head1 LICENSE
|
|
|
2
|
|
|
3 Copyright (c) 1999-2012 The European Bioinformatics Institute and
|
|
|
4 Genome Research Limited. All rights reserved.
|
|
|
5
|
|
|
6 This software is distributed under a modified Apache license.
|
|
|
7 For license details, please see
|
|
|
8
|
|
|
9 http://www.ensembl.org/info/about/code_licence.html
|
|
|
10
|
|
|
11 =head1 CONTACT
|
|
|
12
|
|
|
13 Please email comments or questions to the public Ensembl
|
|
|
14 developers list at <dev@ensembl.org>.
|
|
|
15
|
|
|
16 Questions may also be sent to the Ensembl help desk at
|
|
|
17 <helpdesk@ensembl.org>.
|
|
|
18
|
|
|
19 =cut
|
|
|
20
|
|
|
21 =head1 NAME
|
|
|
22
|
|
|
23 Bio::EnsEMBL::IdMapping::Serialisable - base class for serialisable objects
|
|
|
24
|
|
|
25 =head1 SYNOPSIS
|
|
|
26
|
|
|
27 # instantiate an object which extends Serialisable
|
|
|
28 my $object = YourObject->new(
|
|
|
29 -DUMP_PATH => '/tmp',
|
|
|
30 -CACHE_FILE => 'object_cache.ser',
|
|
|
31 );
|
|
|
32
|
|
|
33 # serialise object to file
|
|
|
34 my $filesize = $object->write_to_file;
|
|
|
35 print LOG "Serialised object to file of size $filesize.\n";
|
|
|
36
|
|
|
37 # later, create another object defining the same serialisation
|
|
|
38 # location. specifying -LOAD_AUTO will automatically load it from the
|
|
|
39 # serialisation file.
|
|
|
40 my $object1 = YourObject->new(
|
|
|
41 -DUMP_PATH => '/tmp',
|
|
|
42 -CACHE_FILE => 'object_cache.ser',
|
|
|
43 -LOAD_AUTO => 1,
|
|
|
44 );
|
|
|
45
|
|
|
46 # alternatively, manually load the object from file
|
|
|
47 $object1->load_from_file;
|
|
|
48
|
|
|
49 =head1 DESCRIPTION
|
|
|
50
|
|
|
51 This is the base class for serialisable objects used by the
|
|
|
52 stable Id mapping. It's essentially an OO wrapper for Storable,
|
|
|
53 providing a method to store (write_to_file(()) and one to retrieve
|
|
|
54 (read_from_file()) serialised objects.
|
|
|
55
|
|
|
56 This class is not instantiated itself, but rather extended by
|
|
|
57 implementing classes.
|
|
|
58
|
|
|
59 =head1 METHODS
|
|
|
60
|
|
|
61 new
|
|
|
62 write_to_file
|
|
|
63 read_from_file
|
|
|
64 dump_path
|
|
|
65 cache_file_name
|
|
|
66 cache_file
|
|
|
67 loaded
|
|
|
68
|
|
|
69 =cut
|
|
|
70
|
|
|
71 package Bio::EnsEMBL::IdMapping::Serialisable;
|
|
|
72
|
|
|
73 use strict;
|
|
|
74 use warnings;
|
|
|
75 no warnings 'uninitialized';
|
|
|
76
|
|
|
77 use Bio::EnsEMBL::Utils::Argument qw(rearrange);
|
|
|
78 use Bio::EnsEMBL::Utils::Exception qw(throw warning);
|
|
|
79 use Bio::EnsEMBL::Utils::ScriptUtils qw(parse_bytes);
|
|
|
80 use Storable qw(nstore retrieve);
|
|
|
81
|
|
|
82
|
|
|
83 =head2 new
|
|
|
84
|
|
|
85 Arg [DUMP_PATH] : String - path for object serialisation
|
|
|
86 Arg [CACHE_FILE] : String - filename of serialised object
|
|
|
87 Arg [AUTO_LOAD] : Boolean - determines whether object should be automatically
|
|
|
88 loaded on instantiation
|
|
|
89 Description : Constructor.
|
|
|
90 Return type : Bio::EnsEMBL::IdMapping::Serialisable implementing object
|
|
|
91 Exceptions : thrown on missing argument
|
|
|
92 Caller : implementing subclass
|
|
|
93 Status : At Risk
|
|
|
94 : under development
|
|
|
95
|
|
|
96 =cut
|
|
|
97
|
|
|
98 sub new {
|
|
|
99 my $caller = shift;
|
|
|
100 my $class = ref($caller) || $caller;
|
|
|
101
|
|
|
102 my ($dump_path, $cache_file, $auto_load) =
|
|
|
103 rearrange([qw(DUMP_PATH CACHE_FILE AUTO_LOAD)], @_);
|
|
|
104
|
|
|
105 throw("You must provide a cache file name") unless ($cache_file);
|
|
|
106
|
|
|
107 my $self = {};
|
|
|
108 bless ($self, $class);
|
|
|
109
|
|
|
110 # initialise internal datastructure
|
|
|
111 $self->{'dump_path'} = $dump_path || '.';
|
|
|
112 $self->{'cache_file_name'} = $cache_file;
|
|
|
113
|
|
|
114 # automatically load serialised object from file if requested
|
|
|
115 if ($auto_load) {
|
|
|
116 if (-s $self->cache_file) {
|
|
|
117 $self->read_from_file;
|
|
|
118 $self->{'loaded'} = 1;
|
|
|
119 }
|
|
|
120 }
|
|
|
121
|
|
|
122 return $self;
|
|
|
123 }
|
|
|
124
|
|
|
125
|
|
|
126 =head2 write_to_file
|
|
|
127
|
|
|
128 Example : my $filesize = $object->write_to_file;
|
|
|
129 Description : Serialises an object to a file (determined by
|
|
|
130 $self->cache_file).
|
|
|
131 Return type : String - size of serialisation file
|
|
|
132 Exceptions : thrown on I/O errors
|
|
|
133 Caller : general
|
|
|
134 Status : At Risk
|
|
|
135 : under development
|
|
|
136
|
|
|
137 =cut
|
|
|
138
|
|
|
139 sub write_to_file {
|
|
|
140 my $self = shift;
|
|
|
141
|
|
|
142 # create dump directory if it doesn't exist
|
|
|
143 if (my $dump_path = $self->dump_path) {
|
|
|
144 unless (-d $dump_path) {
|
|
|
145 system("mkdir -p $dump_path") == 0 or
|
|
|
146 throw("Unable to create directory $dump_path.\n");
|
|
|
147 }
|
|
|
148 }
|
|
|
149
|
|
|
150 my $cache_file = $self->cache_file;
|
|
|
151
|
|
|
152 eval { nstore($self->{'cache'}, $cache_file) };
|
|
|
153 if ($@) {
|
|
|
154 throw("Unable to store $cache_file: $@\n");
|
|
|
155 }
|
|
|
156
|
|
|
157 my $size = -s $cache_file;
|
|
|
158 return parse_bytes($size);
|
|
|
159 }
|
|
|
160
|
|
|
161
|
|
|
162 =head2 read_from_file
|
|
|
163
|
|
|
164 Example : $object->read_from_file;
|
|
|
165 Description : Reads a serialised object from file (determined by
|
|
|
166 $self->cache_file).
|
|
|
167 Return type : Bio::EnsEMBL::IdMapping::Serialisable implementing object
|
|
|
168 Exceptions : thrown on I/O errors
|
|
|
169 Caller : general
|
|
|
170 Status : At Risk
|
|
|
171 : under development
|
|
|
172
|
|
|
173 =cut
|
|
|
174
|
|
|
175 sub read_from_file {
|
|
|
176 my $self = shift;
|
|
|
177
|
|
|
178 my $cache_file = $self->cache_file;
|
|
|
179
|
|
|
180 unless (-s $cache_file) {
|
|
|
181 throw("No valid cache file found at $cache_file.");
|
|
|
182 }
|
|
|
183
|
|
|
184 eval { $self->{'cache'} = retrieve($cache_file); };
|
|
|
185 if ($@) {
|
|
|
186 throw("Unable to retrieve cache: $@");
|
|
|
187 }
|
|
|
188
|
|
|
189 return $self;
|
|
|
190 }
|
|
|
191
|
|
|
192
|
|
|
193 =head2 dump_path
|
|
|
194
|
|
|
195 Arg[1] : String - dump path for serialisation
|
|
|
196 Example : $object->dump_path('/tmp');
|
|
|
197 Description : Getter/setter for the dump path for serialisation.
|
|
|
198 Return type : String
|
|
|
199 Exceptions : none
|
|
|
200 Caller : general
|
|
|
201 Status : At Risk
|
|
|
202 : under development
|
|
|
203
|
|
|
204 =cut
|
|
|
205
|
|
|
206 sub dump_path {
|
|
|
207 my $self = shift;
|
|
|
208 $self->{'dump_path'} = shift if (@_);
|
|
|
209 return $self->{'dump_path'};
|
|
|
210 }
|
|
|
211
|
|
|
212
|
|
|
213 =head2 cache_file_name
|
|
|
214
|
|
|
215 Arg[1] : String - file name for serialisation
|
|
|
216 Example : $object->cache_file_name('object_cache.ser');
|
|
|
217 Description : Getter/setter for the file name for serialisation.
|
|
|
218 Return type : String
|
|
|
219 Exceptions : none
|
|
|
220 Caller : general
|
|
|
221 Status : At Risk
|
|
|
222 : under development
|
|
|
223
|
|
|
224 =cut
|
|
|
225
|
|
|
226 sub cache_file_name {
|
|
|
227 my $self = shift;
|
|
|
228 $self->{'cache_file_name'} = shift if (@_);
|
|
|
229 return $self->{'cache_file_name'};
|
|
|
230 }
|
|
|
231
|
|
|
232
|
|
|
233 =head2 cache_file
|
|
|
234
|
|
|
235 Example : my $cache_file = $object->cache_file;
|
|
|
236 Description : Returns the path and name of the serialised object file.
|
|
|
237 Return type : String
|
|
|
238 Exceptions : none
|
|
|
239 Caller : general
|
|
|
240 Status : At Risk
|
|
|
241 : under development
|
|
|
242
|
|
|
243 =cut
|
|
|
244
|
|
|
245 sub cache_file {
|
|
|
246 my $self = shift;
|
|
|
247 return $self->dump_path.'/'.$self->cache_file_name;
|
|
|
248 }
|
|
|
249
|
|
|
250
|
|
|
251 =head2 loaded
|
|
|
252
|
|
|
253 Arg[1] : Boolean - "loaded" status
|
|
|
254 Example : if ($object->loaded) {
|
|
|
255 # do something with the object that was loaded from a file
|
|
|
256 } else {
|
|
|
257 # the object wasn't loaded but is new, so fill it
|
|
|
258 }
|
|
|
259 Description : Indicates whether a given object was loaded from its serialised
|
|
|
260 state on disk.
|
|
|
261 Return type : Boolean - TRUE if loaded from disk, FALSE otherwise
|
|
|
262 Exceptions : none
|
|
|
263 Caller : general
|
|
|
264 Status : At Risk
|
|
|
265 : under development
|
|
|
266
|
|
|
267 =cut
|
|
|
268
|
|
|
269 sub loaded {
|
|
|
270 my $self = shift;
|
|
|
271 $self->{'loaded'} = shift if (@_);
|
|
|
272 return $self->{'loaded'};
|
|
|
273 }
|
|
|
274
|
|
|
275
|
|
|
276 1;
|
|
|
277
|
