Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 555 lines (442 sloc) 17.039 kb
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
1 # $Id$
2 #
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
3 # BioPerl module Bio::DB::Biblio::soap.pm
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
4 #
5 # Cared for by Martin Senger <senger@ebi.ac.uk>
6 # For copyright and disclaimer see below.
7
8 # POD documentation - main docs before the code
9
10 =head1 NAME
11
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
12 Bio::DB::Biblio::soap - A SOAP-based access to a bibliographic query service
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
13
14 =head1 SYNOPSIS
15
16 Do not use this object directly, it is recommended to access it and use
17 it through the I<Bio::Biblio> module:
18
19 use Bio::Biblio;
20 my $biblio = new Bio::Biblio (-access => 'soap');
21
22 =head1 DESCRIPTION
23
24 This object contains the real implementation of a Bibliographic Query
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
25 Service as defined in L<Bio::DB::BiblioI> - using a SOAP protocol
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
26 to access a WebService (a remote server) that represents a
27 bibliographic repository.
28
29 =head1 FEEDBACK
30
31 =head2 Mailing Lists
32
33 User feedback is an integral part of the evolution of this and other
34 Bioperl modules. Send your comments and suggestions preferably to
35 the Bioperl mailing list. Your participation is much appreciated.
36
37 bioperl-l@bioperl.org - General discussion
38 http://bioperl.org/MailList.shtml - About the mailing lists
39
40 =head2 Reporting Bugs
41
42 Report bugs to the Bioperl bug tracking system to help us keep track
6e62c574 » hyphaltip
2004-11-16 fix Revision string problems
43 of the bugs and their resolution. Bug reports can be submitted via the
44 web:
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
45
f0ecfe6f » hlapp
2002-10-22 Replaced bioperl.org/bioperl-bugs/ with bugzilla.bioperl.org.
46 http://bugzilla.bioperl.org/
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
47
48 =head1 AUTHOR
49
50 Martin Senger (senger@ebi.ac.uk)
51
52 =head1 COPYRIGHT
53
54 Copyright (c) 2002 European Bioinformatics Institute. All Rights Reserved.
55
56 This module is free software; you can redistribute it and/or modify
57 it under the same terms as Perl itself.
58
59 =head1 DISCLAIMER
60
61 This software is provided "as is" without warranty of any kind.
62
63 =head1 BUGS AND LIMITATIONS
64
65 =over
66
67 =item *
68
69 Methods returning a boolean value (I<has_next>, I<exists> and
70 I<contains>) can be used only with SOAP::Lite version 0.52 and newer
71 (probably due to a bug in the older SOAP::Lite).
72
73 =item *
74
75 It does not use WSDL. Coming soon...
76
77 =item *
78
79 There is an open question to discuss: should the service return
80 citations as type I<string> or rather as type I<base64>? What is
81 faster? What is better for keeping non-ASCII characters untouched? How
82 the decision would be influenced if the transparent compression
83 support is introduced?
84
85 =item *
86
87 More testing and debugging needed to ensure that returned citations
88 are properly transferred even if they contain foreign characters.
89
90 =back
91
92 =head1 APPENDIX
93
94 The main documentation details are to be found in
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
95 L<Bio::DB::BiblioI>.
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
96
97 Here is the rest of the object methods. Internal methods are preceded
98 with an underscore _.
99
100 =cut
101
102
103 # Let the code begin...
104
105
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
106 package Bio::DB::Biblio::soap;
1e68457e » heikkil
2003-06-04 removed module specific $VERSION, all modules now use global one from…
107 use vars qw(@ISA $Revision $DEFAULT_SERVICE $DEFAULT_NAMESPACE);
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
108 use strict;
109
110 use Bio::Biblio; # TBD: ?? WHY SHOULD I DO THIS ??
111 use SOAP::Lite
112 on_fault => sub {
113 my $soap = shift;
114 my $res = shift;
115 my $msg =
116 ref $res ? "--- SOAP FAULT ---\n" . $res->faultcode . " " . $res->faultstring
117 : "--- TRANSPORT ERROR ---\n" . $soap->transport->status;
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
118 Bio::DB::Biblio::soap->throw ( -text => $msg );
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
119 }
120 ;
121
122 @ISA = qw(Bio::Biblio);
123
1e68457e » heikkil
2003-06-04 removed module specific $VERSION, all modules now use global one from…
124 BEGIN {
6e62c574 » hyphaltip
2004-11-16 fix Revision string problems
125 $Revision = q[$Id$];
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
126
127 # where to go...
128 $DEFAULT_SERVICE = 'http://industry.ebi.ac.uk/soap/openBQS';
129
130 # ...and what to find there
131 $DEFAULT_NAMESPACE = 'http://industry.ebi.ac.uk/openBQS';
132 }
133
134 # -----------------------------------------------------------------------------
135
136 =head2 _initialize
137
138 Usage : my $obj = new Bio::Biblio (-access => 'soap' ...);
139 (_initialize is internally called from this constructor)
140 Returns : nothing interesting
141 Args : This module recognises and uses following arguments:
142
143 -namespace => 'urn'
144 The namespace used by the WebService that is being
145 accessed. It is a string which guarantees its world-wide
146 uniqueness - therefore it often has a style of a URL -
147 but it does not mean that such pseudo-URL really exists.
148
149 Default is 'http://industry.ebi.ac.uk/openBQS'
150 (which well corresponds with the default '-location' -
151 see module Bio::Biblio).
152
153 -destroy_on_exit => '0'
154 Default value is '1' which means that all Bio::Biblio
155 objects - when being finalised - will send a request
156 to the remote WebService to forget the query collections
157 they represent.
158
159 If you change it to '0' make sure that you know the
160 query collection identification - otherwise you will
161 not be able to re-established connection with it.
162 This can be done by calling method get_collection_id.
163
164 -collection_id => '...'
165 It defines what query collection will this object work
166 with. Use this argument when you know a collection ID
167 of an existing query collection and when you wish to
168 re-established connection with it.
169
170 By default, the collection IDs are set automatically
171 by the query methods - they return Bio::Biblio objects
172 already having a collection ID.
173
174 A missing or undefined collection ID means that the
175 object represents the whole bibliographic repository
176 (which again means that some methods, like get_all,
177 will be probably refused).
178
179 -soap => a SOAP::Lite object
180 Usually all Bio::Biblio objects share an instance of
181 the underlying SOAP::Lite module. But you are free
182 to have more - perhaps with different characteristics.
183
184 See the code for attributes of the default SOAP::Lite
185 object.
186
d8f2e7db » senger
2002-04-09 notion of the HTTP proxy added
187 -httpproxy => 'http://server:port'
188 In addition to the 'location' parameter, you may need
189 to specify also a location/URL of a HTTP proxy server
190 (if your site requires one).
191
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
192 Additionally, the main module Bio::Biblio recognises
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
193 also:
194 -access => '...'
195 -location => '...'
196
197 It populates calling object with the given arguments, and then - for
198 some attributes and only if they are not yet populated - it assigns
199 some default values.
200
201 This is an actual new() method (except for the real object creation
202 and its blessing which is done in the parent class Bio::Root::Root in
203 method _create_object).
204
205 Note that this method is called always as an I<object> method (never as
206 a I<class> method) - and that the object who calls this method may
207 already be partly initiated (from Bio::Biblio::new method); so if you
208 need to do some tricks with the 'class invocation' you need to change
209 Bio::Biblio::new method, not this one.
210
211 =cut
212
213 sub _initialize {
214 my ($self, @args) = @_;
215
216 # make a hashtable from @args
217 my %param = @args;
218 @param { map { lc $_ } keys %param } = values %param; # lowercase keys
219
220 # copy all @args into this object (overwriting what may already be
221 # there) - changing '-key' into '_key'
222 my $new_key;
223 foreach my $key (keys %param) {
224 ($new_key = $key) =~ s/^-/_/;
225 $self->{ $new_key } = $param { $key };
226 }
227
228 # finally add default values for those keys who have default value
229 # and who are not yet in the object
230 $self->{'_location'} = $DEFAULT_SERVICE unless $self->{'_location'};
231 $self->{'_namespace'} = $DEFAULT_NAMESPACE unless $self->{'_namespace'};
232 $self->{'_destroy_on_exit'} = 1 unless defined $self->{'_destroy_on_exit'};
d8f2e7db » senger
2002-04-09 notion of the HTTP proxy added
233 unless ($self->{'_soap'}) {
234 if (defined $self->{'_httpproxy'}) {
235 $self->{'_soap'} = SOAP::Lite
236 -> uri ($self->{'_namespace'})
237 -> proxy ($self->{'_location'},
238 proxy => ['http' => $self->{'_httpproxy'}]);
239 } else {
240 $self->{'_soap'} = SOAP::Lite
241 -> uri ($self->{'_namespace'})
242 -> proxy ($self->{'_location'});
243 }
244 }
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
245 }
246
247 # -----------------------------------------------------------------------------
248
249 #
250 # objects representing query collections are being destroyed if they
251 # have attribute '_destroy_on_exit' set to true - which is a default
252 # value
253 #
254 sub DESTROY {
255 my $self = shift;
256 my $soap = $self->{'_soap'};
257 my $destroy = $self->{'_destroy_on_exit'};
258 return unless $destroy;
259 my $collection_id = $self->{'_collection_id'};
260 return unless $collection_id;
261
262 # ignore all errors here
263 eval {
264 $soap->destroy (SOAP::Data->type (string => $collection_id));
265 }
266 }
267
268 #
269 # some methods must be called with an argument containing a collection
270 # ID; here we return a proper error message explaining it
271 #
272 sub _no_id_msg {
273 my $self = shift;
274 my $package = ref $self;
275 my $method = (caller(1))[3];
276 my $strip_method = $method;
277 $strip_method =~ s/^$package\:\://;
278
279 return <<"END_OF_MSG";
280 Method '$method' works only if its object has a query collection ID.
281 Perhaps you need to use:
282 \tnew Bio::Biblio (-collection_id => '1234567')->$strip_method;
283 or to obtain a collection ID indirectly from a query method:
284 \tnew Bio::Biblio->find ('keyword')->$strip_method;
285 END_OF_MSG
286 }
287
288 #
289 # some methods do not work with older SOAP::Lite version; here we
290 #return message explaining it
291 #
292 sub _old_version_msg {
293 my $self = shift;
294 my $method = (caller(1))[3];
295
296 return <<"END_OF_MSG";
297 Method '$method' works only with SOAP::Lite
298 version 0.52 and newer (the problem is with returning a boolean value from the server).
299 END_OF_MSG
300 }
301
302 #
303 # some controlled vocabulary methods needs two parameters; here we
304 # return message explaining it
305 #
306 sub _two_params_msg {
307 my $self = shift;
308 my $method = (caller(1))[3];
309
310 return <<"END_OF_MSG";
311 Method '$method' expects two parameters: vocabulary name and a value.
312 END_OF_MSG
313 }
314
315 #
316 # some controlled vocabulary methods needs a vocabulary name; here we
317 # return message explaining it
318 #
319 sub _missing_name_msg {
320 my $self = shift;
321 my $method = (caller(1))[3];
322
323 return <<"END_OF_MSG";
324 Method '$method' expects vocabulary name as parameter.
325 END_OF_MSG
326 }
327
1236001b » senger
2002-06-21 Fixed: looking for keywords with numeric values
328 #
329 # return a copy of a given array, with all its elements replaced
330 # with the SOAP-Data objects defining elements type as 'string'
331 #
332 sub _as_strings {
333 my ($ref_input_array) = @_;
334 my (@result) = map { SOAP::Data->new (type => 'string', value => $_) } @$ref_input_array;
335 return \@result;
336 }
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
337
338 # ---------------------------------------------------------------------
339 #
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
340 # Here are the methods implementing Bio::DB::BiblioI interface
341 # (documentation is in Bio::DB::BiblioI)
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
342 #
343 # ---------------------------------------------------------------------
344
345 sub get_collection_id {
346 my ($self) = @_;
347 $self->{'_collection_id'};
348 }
349
350 sub get_count {
351 my ($self) = @_;
352 my $soap = $self->{'_soap'};
353 my ($collection_id) = $self->{'_collection_id'};
354 if ($collection_id) {
355 $soap->getBibRefCount (SOAP::Data->type (string => $collection_id))->result;
356 } else {
357 $soap->getBibRefCount->result;
358 }
359 }
360
361 # try: 94033980
362 sub get_by_id {
363 my ($self, $citation_id) = @_;
364 $self->throw ("Citation ID is expected as a parameter of method 'get_by_id'.")
365 unless $citation_id;
366 my $soap = $self->{'_soap'};
367 $soap->getById (SOAP::Data->type (string => $citation_id))->result;
368 }
369
370 sub find {
371 my ($self, $keywords, $attrs) = @_;
372 my (@keywords, @attrs);
373
374 # $keywords can be a comma-delimited scalar or a reference to an array
375 if ($keywords) {
376 my $ref = ref $keywords;
377 @keywords = split (/,/, $keywords) unless $ref;
378 @keywords = @$keywords if $ref =~ /ARRAY/;
379 }
380 $self->throw ("No keywords given in 'find' method.\n")
381 unless (@keywords);
382
383 # ...and the same with $attrs
384 if ($attrs) {
385 my $ref = ref $attrs;
386 @attrs = split (/,/, $attrs) unless $ref;
387 @attrs = @$attrs if $ref =~ /ARRAY/;
388 }
389
390 my $soap = $self->{'_soap'};
391 my $collection_id = $self->{'_collection_id'};
392 my $new_id;
393 if ($collection_id) {
394 if (@attrs) {
1236001b » senger
2002-06-21 Fixed: looking for keywords with numeric values
395 $new_id = $soap->find (SOAP::Data->type (string => $collection_id),
396 &_as_strings (\@keywords),
397 &_as_strings (\@attrs))->result;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
398 } else {
1236001b » senger
2002-06-21 Fixed: looking for keywords with numeric values
399 $new_id = $soap->find (SOAP::Data->type (string => $collection_id),
400 &_as_strings (\@keywords))->result;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
401 }
402 } else {
403 if (@attrs) {
1236001b » senger
2002-06-21 Fixed: looking for keywords with numeric values
404 $new_id = $soap->find (&_as_strings (\@keywords),
405 &_as_strings (\@attrs))->result;
406
407
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
408 } else {
1236001b » senger
2002-06-21 Fixed: looking for keywords with numeric values
409 $new_id = $soap->find (&_as_strings (\@keywords))->result;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
410 }
411 }
412
413 # clone itself but change the collection ID to a new one
414 return $self->new (-collection_id => $new_id,
415 -parent_collection_d => $collection_id);
416 }
417
418 sub get_all_ids {
419 my ($self) = @_;
420 my $soap = $self->{'_soap'};
421 my ($collection_id) = $self->{'_collection_id'};
422 $self->throw ($self->_no_id_msg) unless $collection_id;
423 $soap->getAllIDs (SOAP::Data->type (string => $collection_id))->result;
424 }
425
426 sub get_all {
427 my ($self) = @_;
428 my $soap = $self->{'_soap'};
429 my ($collection_id) = $self->{'_collection_id'};
430 $self->throw ($self->_no_id_msg) unless $collection_id;
431 $soap->getAllBibRefs (SOAP::Data->type (string => $collection_id))->result;
432 }
433
434 sub has_next {
435 my ($self) = @_;
436 my $soap = $self->{'_soap'};
437 my ($collection_id) = $self->{'_collection_id'};
438 $self->throw ($self->_no_id_msg) unless $collection_id;
439 $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION < 0.52;
440 $soap->hasNext (SOAP::Data->type (string => $collection_id))->result;
441 }
442
443 sub get_next {
444 my ($self) = @_;
445 my $soap = $self->{'_soap'};
446 my ($collection_id) = $self->{'_collection_id'};
447 $self->throw ($self->_no_id_msg) unless $collection_id;
9ef8781e » senger
2002-03-11 changes in web-service interface and in documentation
448 my $ra = $soap->getNext (SOAP::Data->type (string => $collection_id))->result;
449 $self->{'_collection_id'} = shift @{ $ra };
450 shift @{ $ra };
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
451 }
452
453 sub get_more {
454 my ($self, $how_many) = @_;
455 my $soap = $self->{'_soap'};
456 my $collection_id = $self->{'_collection_id'};
457 $self->throw ($self->_no_id_msg) unless $collection_id;
458
459 unless (defined ($how_many) and $how_many =~ /^\d+$/) {
460 warn ("Method 'get_more' expects a numeric argument. Changing to 1.\n");
461 $how_many = 1;
462 }
463 unless ($how_many > 0) {
464 warn ("Method 'get_more' expects a positive argument. Changing to 1.\n");
465 $how_many = 1;
466 }
467
9ef8781e » senger
2002-03-11 changes in web-service interface and in documentation
468 my $ra = $soap->getMore (SOAP::Data->type (string => $collection_id),
469 SOAP::Data->type (int => $how_many))->result;
470 $self->{'_collection_id'} = shift @{ $ra };
471 $ra;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
472 }
473
474 sub reset_retrieval {
475 my ($self) = @_;
476 my $soap = $self->{'_soap'};
477 my ($collection_id) = $self->{'_collection_id'};
478 $self->throw ($self->_no_id_msg) unless $collection_id;
9ef8781e » senger
2002-03-11 changes in web-service interface and in documentation
479 $self->{'_collection_id'} = $soap->resetRetrieval (SOAP::Data->type (string => $collection_id))->result;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
480 }
481
482 sub exists {
483 my ($self) = @_;
484 my $soap = $self->{'_soap'};
485 my ($collection_id) = $self->{'_collection_id'};
486 $self->throw ($self->_no_id_msg) unless $collection_id;
487 $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION < 0.52;
488 $soap->exists (SOAP::Data->type (string => $collection_id))->result;
489 }
490
491 sub destroy {
492 my ($self) = @_;
493 my $soap = $self->{'_soap'};
494 my ($collection_id) = $self->{'_collection_id'};
495 $self->throw ($self->_no_id_msg) unless $collection_id;
496 $soap->destroy (SOAP::Data->type (string => $collection_id));
497 }
498
499 sub get_vocabulary_names {
500 my ($self) = @_;
501 my $soap = $self->{'_soap'};
502 $soap->getAllVocabularyNames->result;
503 }
504
505 sub contains {
506 my ($self, $vocabulary_name, $value) = @_;
507 my $soap = $self->{'_soap'};
508 $self->throw ($self->_old_version_msg) if $SOAP::Lite::VERSION < 0.52;
509 $self->throw ($self->_two_params_msg)
510 unless defined $vocabulary_name and defined $value;
511 $soap->contains (SOAP::Data->type (string => $vocabulary_name),
512 SOAP::Data->type (string => $value))->result;
513 }
514
515 sub get_entry_description {
516 my ($self, $vocabulary_name, $value) = @_;
517 my $soap = $self->{'_soap'};
518 $self->throw ($self->_two_params_msg)
519 unless defined $vocabulary_name and defined $value;
520 $soap->getEntryDescription (SOAP::Data->type (string => $vocabulary_name),
521 SOAP::Data->type (string => $value))->result;
522 }
523
524 sub get_all_values {
525 my ($self, $vocabulary_name) = @_;
526 my $soap = $self->{'_soap'};
527 $self->throw ($self->_missing_name_msg)
528 unless defined $vocabulary_name;
529 $soap->getAllValues (SOAP::Data->type (string => $vocabulary_name))->result;
530 }
531
532 sub get_all_entries {
533 my ($self, $vocabulary_name) = @_;
534 my $soap = $self->{'_soap'};
535 $self->throw ($self->_missing_name_msg)
536 unless defined $vocabulary_name;
537 $soap->getAllEntries (SOAP::Data->type (string => $vocabulary_name))->result;
538 }
539
540 =head2 VERSION and Revision
541
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
542 Usage : print $Bio::DB::Biblio::soap::VERSION;
543 print $Bio::DB::Biblio::soap::Revision;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
544
545 =cut
546
547 =head2 Defaults
548
d0f2a61a » senger
2002-02-28 soap.pm moved from Factory to DB
549 Usage : print $Bio::DB::Biblio::soap::DEFAULT_SERVICE;
550 print $Bio::DB::Biblio::soap::DEFAULT_NAMESPACE;
9d5b8c13 » senger
2002-02-22 Bibliography query modules added
551
552 =cut
553
554 1;
555 __END__
Something went wrong with that request. Please try again.