|
0
|
1 # $Id: Biblio.pm,v 1.7 2002/10/22 07:45:09 lapp Exp $
|
|
|
2 #
|
|
|
3 # BioPerl module Bio::Biblio
|
|
|
4 #
|
|
|
5 # Cared for by Martin Senger <senger@ebi.ac.uk>
|
|
|
6 # For copyright and disclaimer see below.
|
|
|
7 #
|
|
|
8
|
|
|
9 # POD documentation - main docs before the code
|
|
|
10
|
|
|
11 =head1 NAME
|
|
|
12
|
|
|
13 Bio::Biblio - A Bibliographic Query Service module
|
|
|
14
|
|
|
15 =head1 SYNOPSIS
|
|
|
16
|
|
|
17 use Bio::Biblio;
|
|
|
18 my $biblio = new Bio::Biblio;
|
|
|
19
|
|
|
20 print $biblio->find ('perl')->get_count . "\n";
|
|
|
21
|
|
|
22 my $collection = $biblio->find ('brazma', 'authors');
|
|
|
23 while ( $collection->has_next ) {
|
|
|
24 print $collection->get_next;
|
|
|
25 }
|
|
|
26
|
|
|
27 Here are some one-liners:
|
|
|
28
|
|
|
29 perl -MBio::Biblio -e 'print new Bio::Biblio->get_by_id ("94033980")'
|
|
|
30 perl -MBio::Biblio \
|
|
|
31 -e 'print join ("\n", @{ new Bio::Biblio->find ("brazma")->get_all_ids })'
|
|
|
32 perl -MBio::Biblio \
|
|
|
33 -e 'print new Bio::Biblio->find ("Java")->find ("perl")->get_count'
|
|
|
34
|
|
|
35 The C<new> method can get parameters, for example:
|
|
|
36
|
|
|
37 my $biblio = Bio::Biblio
|
|
|
38 (-access => 'soap',
|
|
|
39 -location => 'http://industry.ebi.ac.uk/soap/openBQS',
|
|
|
40 -destroy_on_exit => '0');
|
|
|
41
|
|
|
42 =head1 DESCRIPTION
|
|
|
43
|
|
|
44 This is a class whose instances can access bibliographic
|
|
|
45 repositories. It allows to query a bibliographic database (such as
|
|
|
46 MEDLINE) and then to retrieve resulting citations from it. The
|
|
|
47 citations are returned in an XML format which is native to the
|
|
|
48 repository but there are also supporting modules for converting them
|
|
|
49 into Perl objects.
|
|
|
50
|
|
|
51 The detailed descriptions of all query and retrieval methods are in
|
|
|
52 L<Bio::DB::BiblioI> (an interface). All those methods should be
|
|
|
53 called on instances of this (Bio::Biblio) module.
|
|
|
54
|
|
|
55 The module complies (with some simplifications) with the specification
|
|
|
56 described in the B<OpenBQS> project. Its home page is at
|
|
|
57 I<http://industry.ebi.ac.uk/openBQS>. There are also links to
|
|
|
58 available servers providing access to the bibliographic repositories
|
|
|
59 (namely to I<MEDLINE>).
|
|
|
60
|
|
|
61 The module also gives an access to a set of controlled vocabularies
|
|
|
62 and their values. It allows to introspect bibliographic repositories
|
|
|
63 and to find what citation resource types (such as journal and book
|
|
|
64 articles, patents or technical reports) are provided, and what
|
|
|
65 attributes they have, eventually what attribute values are allowed.
|
|
|
66
|
|
|
67 =head1 OVERVIEW OF CLASSES AND PACKAGES
|
|
|
68
|
|
|
69 =over
|
|
|
70
|
|
|
71 =item B<Bio::Biblio>
|
|
|
72
|
|
|
73 This is the main class to be used by the end users. It
|
|
|
74 loads a real implementation for a particular access protocol according
|
|
|
75 to the argument I<-access>. At the time of writing this documentation
|
|
|
76 there is only one available access module implementing all query and
|
|
|
77 retrieval methods:
|
|
|
78
|
|
|
79 -access => soap
|
|
|
80
|
|
|
81 This module implements all methods defined in the interface
|
|
|
82 I<Bio::DB::BiblioI> (see L<Bio::DB::BiblioI>) by delegating
|
|
|
83 calls to a loaded low-level module (e.g. see
|
|
|
84 L<Bio::DB::Biblio::soap>).
|
|
|
85
|
|
|
86 Note that there is also another module (and perhaps more) which does
|
|
|
87 not use SOAP protocol and do not implement all query methods -
|
|
|
88 nevertheless it has retrieval methods and it can be used in the same
|
|
|
89 way:
|
|
|
90
|
|
|
91 -access => biofetch
|
|
|
92
|
|
|
93
|
|
|
94 =item Bio::DB::BiblioI
|
|
|
95
|
|
|
96 This is an interface defining all methods that can be called on
|
|
|
97 I<Bio::Biblio> instances.
|
|
|
98
|
|
|
99 =item Bio::DB::Biblio::soap
|
|
|
100
|
|
|
101 This is a real implementation of all methods defined in
|
|
|
102 Bio::DB::BiblioI using SOAP protocol (calling a WebService
|
|
|
103 based on SOAP). This class should not be instantiated directly (use
|
|
|
104 I<Bio::Biblio> instead). See L<Bio::DB::BiblioI> for details.
|
|
|
105
|
|
|
106 =item Bio::Biblio::IO
|
|
|
107
|
|
|
108 This module instantiates and uses a converter of the citations read by
|
|
|
109 any of the access methods mentioned above. See L<Bio::Biblio::IO> for
|
|
|
110 details.
|
|
|
111
|
|
|
112 =item Bio::Biblio::IO::medlinexml and Bio::Biblio::IO::medline2ref
|
|
|
113
|
|
|
114 A converter of MEDLINE citations in XML into Perl objects.
|
|
|
115
|
|
|
116 =item Bio::Biblio::IO::pubmedxml and Bio::Biblio::IO::pubmed2ref
|
|
|
117
|
|
|
118 A converter of PUBMED citations in XML into Perl objects.
|
|
|
119
|
|
|
120 =back
|
|
|
121
|
|
|
122 =head1 FEEDBACK
|
|
|
123
|
|
|
124 =head2 Mailing Lists
|
|
|
125
|
|
|
126 User feedback is an integral part of the evolution of this and other
|
|
|
127 Bioperl modules. Send your comments and suggestions preferably to
|
|
|
128 the Bioperl mailing list. Your participation is much appreciated.
|
|
|
129
|
|
|
130 bioperl-l@bioperl.org - General discussion
|
|
|
131 http://bioperl.org/MailList.shtml - About the mailing lists
|
|
|
132
|
|
|
133 =head2 Reporting Bugs
|
|
|
134
|
|
|
135 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
136 of the bugs and their resolution. Bug reports can be submitted via
|
|
|
137 email or the web:
|
|
|
138
|
|
|
139 bioperl-bugs@bioperl.org
|
|
|
140 http://bugzilla.bioperl.org/
|
|
|
141
|
|
|
142 =head1 AUTHOR
|
|
|
143
|
|
|
144 Martin Senger (senger@ebi.ac.uk)
|
|
|
145
|
|
|
146 =head1 COPYRIGHT
|
|
|
147
|
|
|
148 Copyright (c) 2002 European Bioinformatics Institute. All Rights Reserved.
|
|
|
149
|
|
|
150 This module is free software; you can redistribute it and/or modify
|
|
|
151 it under the same terms as Perl itself.
|
|
|
152
|
|
|
153 =head1 DISCLAIMER
|
|
|
154
|
|
|
155 This software is provided "as is" without warranty of any kind.
|
|
|
156
|
|
|
157 =head1 SEE ALSO
|
|
|
158
|
|
|
159 =over
|
|
|
160
|
|
|
161 =item *
|
|
|
162
|
|
|
163 OpenBQS home page: http://industry.ebi.ac.uk/openBQS
|
|
|
164
|
|
|
165 =item *
|
|
|
166
|
|
|
167 Comments to the Perl client: http://industry.ebi.ac.uk/openBQS/Client_perl.html
|
|
|
168
|
|
|
169 =back
|
|
|
170
|
|
|
171 =head1 APPENDIX
|
|
|
172
|
|
|
173 The main documentation details are to be found in
|
|
|
174 L<Bio::DB::BiblioI>.
|
|
|
175
|
|
|
176 Here is the rest of the object methods. Internal methods are preceded
|
|
|
177 with an underscore _.
|
|
|
178
|
|
|
179 =cut
|
|
|
180
|
|
|
181
|
|
|
182 # Let the code begin...
|
|
|
183
|
|
|
184
|
|
|
185 package Bio::Biblio;
|
|
|
186 use vars qw(@ISA $VERSION $Revision);
|
|
|
187 use strict;
|
|
|
188
|
|
|
189 use Bio::Root::Root;
|
|
|
190 use Bio::DB::BiblioI;
|
|
|
191
|
|
|
192 @ISA = qw(Bio::Root::Root Bio::DB::BiblioI);
|
|
|
193
|
|
|
194
|
|
|
195 BEGIN {
|
|
|
196 $VERSION = do { my @r = (q$Revision: 1.7 $ =~ /\d+/g); sprintf "%d.%-02d", @r };
|
|
|
197 $Revision = q$Id: Biblio.pm,v 1.7 2002/10/22 07:45:09 lapp Exp $;
|
|
|
198 }
|
|
|
199
|
|
|
200 # -----------------------------------------------------------------------------
|
|
|
201
|
|
|
202 =head2 new
|
|
|
203
|
|
|
204 Usage : my $obj = new Bio::Biblio (@args);
|
|
|
205 Returns : Bio::Biblio object on success, or undef on failure
|
|
|
206 Args : This module recognizes and uses:
|
|
|
207
|
|
|
208 -access => 'soap'
|
|
|
209 It indicates what lower-level module to load.
|
|
|
210 Default is 'soap'.
|
|
|
211
|
|
|
212 -location => 'http://...'
|
|
|
213 It says where to find a bibliographic query service.
|
|
|
214 The format and contents of this argument is dependent
|
|
|
215 on the '-access' argument.
|
|
|
216
|
|
|
217 For 'soap' access it is a URL of a WebService.
|
|
|
218 Default is http://industry.ebi.ac.uk/soap/openBQS
|
|
|
219
|
|
|
220 Other arguments can be given here but they are
|
|
|
221 recognized by the lower-level module
|
|
|
222 (e.g. see Bio::DB::Biblio::soap).
|
|
|
223
|
|
|
224 It builds, populates and returns a new I<Bio::Biblio> object. This is
|
|
|
225 how it is seen from the outside. But in fact, it builds, populates and
|
|
|
226 returns a more specific lower-level object, for example
|
|
|
227 I<Bio::DB::Biblio::soap> object - which one it is depends on the
|
|
|
228 parameter I<-access>.
|
|
|
229
|
|
|
230 The real initialization is done in the method I<_initialize> of the
|
|
|
231 lower-level object.
|
|
|
232
|
|
|
233 This method can also be used for I<cloning> an existing object and
|
|
|
234 changing or adding new attributes to it in the same time. This is,
|
|
|
235 however, not particulary useful for the casual users of this module,
|
|
|
236 because the query methods (see L<Bio::DB::BiblioI>) themselves
|
|
|
237 already return cloned objects with more refined query
|
|
|
238 collections. Anyway this is how the cloning can be done:
|
|
|
239
|
|
|
240 use Bio::Biblio;
|
|
|
241 my $biblio = new Bio::Biblio;
|
|
|
242
|
|
|
243 # this will create a new object which will NOT send a 'destroy'
|
|
|
244 # message to the remote server when its life ends
|
|
|
245 my $clone = $biblio->new (-destroy-on-exit => '0');
|
|
|
246
|
|
|
247 =cut
|
|
|
248
|
|
|
249 sub new {
|
|
|
250 my ($caller,@args) = @_;
|
|
|
251 my $class = ref($caller) || $caller;
|
|
|
252
|
|
|
253 # if $caller is an object, or if it is an underlying
|
|
|
254 # 'real-work-doing' class (e.g. Bio::DB::Biblio::soap) then
|
|
|
255 # we want to call SUPER to create and bless an object
|
|
|
256
|
|
|
257 if ($class =~ /Bio::DB::Biblio::(\S+)/) {
|
|
|
258 my ($self) = $class->SUPER::new (@args);
|
|
|
259
|
|
|
260 # now the $self is an empty object - we will populate it from
|
|
|
261 # the $caller - if $caller is an object
|
|
|
262
|
|
|
263 if (ref ($caller)) {
|
|
|
264 %{ $self } = %{ $caller };
|
|
|
265 }
|
|
|
266
|
|
|
267 # and finally add values from '@args' into the newly created
|
|
|
268 # object (the values will overwrite the values copied above)
|
|
|
269
|
|
|
270 $self->_initialize (@args);
|
|
|
271 return $self;
|
|
|
272
|
|
|
273 # this is called only the first time when somebody calls: 'new
|
|
|
274 # Bio::Biblio (...)', and it actually loads a 'real-work-doing'
|
|
|
275 # module and call this new() method again (unless the loaded
|
|
|
276 # module has its own new() method)
|
|
|
277
|
|
|
278 } else {
|
|
|
279 my %param = @args;
|
|
|
280 @param { map { lc $_ } keys %param } = values %param; # lowercase keys
|
|
|
281 my $access =
|
|
|
282 $param {'-access'} ||
|
|
|
283 $class->_guess_access ( $param {'-location'} ) ||
|
|
|
284 'soap';
|
|
|
285 $access = "\L$access"; # normalize capitalization to lower case
|
|
|
286
|
|
|
287 # load module with the real implementation - as defined in $access
|
|
|
288 return undef unless (&_load_access_module ($access));
|
|
|
289
|
|
|
290 # this will call this same method new() - but rather its the
|
|
|
291 # upper (object) branche
|
|
|
292 return "Bio::DB::Biblio::$access"->new (@args);
|
|
|
293 }
|
|
|
294 }
|
|
|
295
|
|
|
296 # -----------------------------------------------------------------------------
|
|
|
297
|
|
|
298 =head2 _load_access_module
|
|
|
299
|
|
|
300 Usage : $class->_load_access_module ($access)
|
|
|
301 Returns : 1 on success, undef on failure
|
|
|
302 Args : 'access' should contain the last part of the
|
|
|
303 name of a module who does the real implementation
|
|
|
304
|
|
|
305 It does (in run-time) a similar thing as
|
|
|
306
|
|
|
307 require Bio::DB::Biblio::$access
|
|
|
308
|
|
|
309 It prints an error on STDERR if it fails to find and load the module
|
|
|
310 (for example, because of the compilation errors in the module).
|
|
|
311
|
|
|
312 =cut
|
|
|
313
|
|
|
314 sub _load_access_module {
|
|
|
315 my ($access) = @_;
|
|
|
316 my ($module, $load, $m);
|
|
|
317
|
|
|
318 $module = "_<Bio/DB/Biblio/$access.pm";
|
|
|
319 $load = "Bio/DB/Biblio/$access.pm";
|
|
|
320
|
|
|
321 return 1 if $main::{$module};
|
|
|
322 eval {
|
|
|
323 require $load;
|
|
|
324 };
|
|
|
325
|
|
|
326 if ( $@ ) {
|
|
|
327 Bio::Root::Root->throw (<<END);
|
|
|
328 $load: $access cannot be found or loaded
|
|
|
329 Exception $@
|
|
|
330 For more information about the Biblio system please see the Bio::Biblio docs.
|
|
|
331 END
|
|
|
332 ;
|
|
|
333 return;
|
|
|
334 }
|
|
|
335 return 1;
|
|
|
336 }
|
|
|
337
|
|
|
338 # -----------------------------------------------------------------------------
|
|
|
339
|
|
|
340 =head2 _guess_access
|
|
|
341
|
|
|
342 Usage : $class->_guess_access ($location)
|
|
|
343 Returns : string with a guessed access protocol (e.g. 'soap')
|
|
|
344 Args : 'location' defines where to find a bibliographic service
|
|
|
345 in a protocol-dependent manner (e.g. for SOAP it is
|
|
|
346 a URL of a bibliographic WebService)
|
|
|
347
|
|
|
348 It makes an expert guess what kind of access/transport protocol should
|
|
|
349 be used based on the I<location> of the service (e.g. if the
|
|
|
350 I<location> looks like an IOR then the access protocol is probably
|
|
|
351 CORBA).
|
|
|
352
|
|
|
353 =cut
|
|
|
354
|
|
|
355 # this is kept here for the future when more access protocols
|
|
|
356 # (e.g. CORBA) may be available for accessing bibliographic query
|
|
|
357 # services
|
|
|
358
|
|
|
359 sub _guess_access {
|
|
|
360 # my ($class, $location) = @_;
|
|
|
361 return 'soap';
|
|
|
362 }
|
|
|
363
|
|
|
364 =head2 VERSION and Revision
|
|
|
365
|
|
|
366 Usage : print $Bio::Biblio::VERSION;
|
|
|
367 print $Bio::Biblio::Revision;
|
|
|
368
|
|
|
369 =cut
|
|
|
370
|
|
|
371 1;
|
|
|
372 __END__
|
