Bio/DB/GenericWebAgent.pm

filter: Statementstmt 23.6% 22 / 93 Branchbran 2.1% 1 / 46 Conditioncond 0.0% 0 / 33 MC/DCmcdc 0.0% 0 / 20 Subroutinesub 35.2% 6 / 17 Podpod 100% 9 / 9 totaltotal 17.4% 38 / 218 CC 35 SCAR 48.6
CC
35
Cov
13%
get_Response
342.0
proxy
30.0
authentication
20.0
CRAP 128.6
« Bio/Search/HSP/PsiBlastHSP.pm ↑ Summary Bio/SeqFeatureI.pm »
1 #
2 # BioPerl module for Bio::DB::GenericWebAgent
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Chris Fields <cjfields at bioperl dot org>
7 #
8 # Copyright Chris Fields
9 #
10 # You may distribute this module under the same terms as perl itself
11 #
12 # POD documentation - main docs before the code
13 #
14 # Interfaces with new GenericWebAgent interface
15  
16 =head1 NAME
17  
18 Bio::DB::GenericWebAgent - helper base class for parameter-based remote server
19 access and response retrieval.
20  
21 =head1 SYNOPSIS
22  
23 # DO NOT USE DIRECTLY
24  
25 See Bio::DB::EUtilities for an example implementation
26  
27 =head1 DESCRIPTION
28  
29 WARNING: Please do B<NOT> spam the web servers with multiple requests.
30  
31 Bio::DB::GenericWebAgent is a generic wrapper around a web agent
32 (LWP::UserAgent), an object which can retain, format, and build parameters for
33 the user agent (Bio::ParameterBaseI), and a BioPerl class parser that processes
34 response content received by the user agent. The Bio::ParameterBaseI object
35 should be state-aware, e.g. know when changes occur to parameters, so that
36 identical requests are not repeatedly sent to the server (this base class takes
37 this into consideration).
38  
39 =head1 FEEDBACK
40  
41 =head2 Mailing Lists
42  
43 User feedback is an integral part of the
44 evolution of this and other Bioperl modules. Send
45 your comments and suggestions preferably to one
46 of the Bioperl mailing lists. Your participation
47 is much appreciated.
48  
49 bioperl-l@lists.open-bio.org - General discussion
50 http://bioperl.org/Support.html - About the mailing lists
51  
52 =head2 Support
53  
54 Please direct usage questions or support issues to the mailing list:
55  
56 I<bioperl-l@bioperl.org>
57  
58 rather than to the module maintainer directly. Many experienced and
59 reponsive experts will be able look at the problem and quickly
60 address it. Please include a thorough description of the problem
61 with code and data examples if at all possible.
62  
63 =head2 Reporting Bugs
64  
65 Report bugs to the Bioperl bug tracking system to
66 help us keep track the bugs and their resolution.
67 Bug reports can be submitted via the web.
68  
69 https://github.com/bioperl/bioperl-live/issues
70  
71 =head1 AUTHOR
72  
73 Email cjfields at bioperl dot org
74  
75 =head1 APPENDIX
76  
77 The rest of the documentation details each of the
78 object methods. Internal methods are usually
79 preceded with a _
80  
81 =cut
82  
83 # Let the code begin...
84  
85 package Bio::DB::GenericWebAgent;
86 1 $Bio::DB::GenericWebAgent::VERSION = '1.7.8';
87 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
88 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
89 1 ▶use base qw(Bio::Root::Root);
Subroutine BEGIN: called CC=1 SCAR=0.0
90 1 ▶use LWP::UserAgent;
Subroutine BEGIN: called CC=1 SCAR=0.0
91  
92 1 my $LAST_INVOCATION_TIME = 0;
93  
94 1 my $TIME_HIRES = 0;
95  
96 1 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=7.0
97 eval {
98 1 ▶ use Time::HiRes;
Subroutine BEGIN: called CC=1 SCAR=0.0
99 1 };
100 1 ▶ unless ($@) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($@) 1 0 1
101 1 $TIME_HIRES = 1;
102 }
103 }
104  
105 =head2 new
106  
107 Title : new
108 Usage : Bio::DB::GenericWebAgent->new(@args);
109 Function: Create new Bio::DB::GenericWebAgent instance.
110 Returns :
111 Args : None specific to this base class. Inheriting classes will
112 likely set specific parameters in their constructor;
113 Bio::DB::GenericWebAgent is primarily a test bed.
114  
115 =cut
116  
117 0 ▶sub new {
Subroutine new: not called CC=1 SCAR=6.9
Pod documented
118 0 my ($class, @args) = @_;
119 0 my $self = $class->SUPER::new(@args);
120 0 $self->ua(LWP::UserAgent->new(env_proxy => 1,
121 agent => ref($self)));
122 0 $self->delay($self->delay_policy);
123 0 return $self;
124 }
125  
126 =head1 GenericWebAgent methods
127  
128 =head2 parameter_base
129  
130 Title : parameter_base
131 Usage : $dbi->parameter_base($pobj);
132 Function: Get/Set Bio::ParameterBaseI.
133 Returns : Bio::ParameterBaseI object
134 Args : Bio::ParameterBaseI object
135  
136 =cut
137  
138 # this will likely be overridden in subclasses
139  
140 0 ▶sub parameter_base {
Subroutine parameter_base: not called CC=3 SCAR=24.8
Pod documented
141 0 my ($self, $pobj) = @_;
142 0 ▶ if ($pobj) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pobj) 0 0 0
143 0 ▶ $self->throw('Not a Bio::ParameterBaseI')
Branch: 1 branch
BranchTrueFalseTotal
unless $pobj->isa("Bio::ParameterBaseI") 0 0 0
144 if !$pobj->isa('Bio::ParameterBaseI');
145 0 $self->{'_parameter_base'} = $pobj;
146 }
147 0 return $self->{'_parameter_base'};
148 }
149  
150 =head2 ua
151  
152 Title : ua
153 Usage : $dbi->ua;
154 Function: Get/Set LWP::UserAgent.
155 Returns : LWP::UserAgent
156 Args : LWP::UserAgent
157  
158 =cut
159  
160 0 ▶sub ua {
Subroutine ua: not called CC=3 SCAR=24.8
Pod documented
161 0 my ($self, $ua) = @_;
162 0 ▶ if( defined $ua && $ua->isa("LWP::UserAgent") ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $ua and $ua->isa("LWP::UserAgent")) 0 0 0
Condition0%0/3
defined $ua and $ua->isa("LWP::UserAgent")
!ll&&!rl&&r
000
MC/DC0%0/2
defined $ua and $ua->isa("LWP::UserAgent")
defined $ua $ua->isa("LWP::UserAgent")
Truth table0%0/3
A and B
A= defined $uaB= $ua->isa("LWP::UserAgent")
ABresult
0X0
100
111
163 0 $self->{'_ua'} = $ua;
164 }
165 0 return $self->{'_ua'};
166 }
167  
168 =head2 get_Response
169  
170 Title : get_Response
171 Usage : $agent->get_Response;
172 Function: Get the HTTP::Response object by passing it an HTTP::Request (generated from
173 Bio::ParameterBaseI implementation).
174 Returns : HTTP::Response object or data if callback is used
175 Args : (optional)
176  
177 -cache_response - flag to cache HTTP::Response object;
178 Default is 1 (TRUE, caching ON)
179  
180 These are passed on to LWP::UserAgent::request() if stipulated
181  
182 -cb - use a LWP::UserAgent-compliant callback
183 -file - dumps the response to a file (handy for large responses)
184 Note: can't use file and callback at the same time
185 -read_size_hint - bytes of content to read in at a time to pass to callback
186 Note : Caching and parameter checking are set
187  
188 =cut
189  
190 # TODO deal with small state-related bug with file
191  
192 0 ▶sub get_Response {
Subroutine get_Response: not called CC=18 SCAR=58.3
Pod documented
193 0 my ($self, @args) = @_;
194 0 my ($cache, $file, $cb, $size) = $self->_rearrange([qw(CACHE_RESPONSE FILE CB READ_SIZE_HINT)],@args);
195 0 ▶ $self->throw("Can't have both callback and file") if $file && $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $file and $cb 0 0 0
Condition0%0/3
$file and $cb
!ll&&!rl&&r
000
MC/DC0%0/2
$file and $cb
$file $cb
Truth table0%0/3
A and B
A= $fileB= $cb
ABresult
0X0
100
111
196 # make -file accept more perl-like write-append type data.
197 0 ▶ $file =~ s{^>}{} if $file;
Branch: 1 branch
BranchTrueFalseTotal
if $file 0 0 0
198 0 ▶ my @opts = grep {defined $_} ($file || $cb, $size);
Condition0%0/3
$file || $cb
l!l&&r!l&&!r
000
MC/DC0%0/2
$file || $cb
$file $cb
Truth table0%0/3
A || B
A= $fileB= $cb
ABresult
1X1
011
000
199 0 ▶ $cache = (defined $cache && $cache == 0) ? 0 : 1;
Branch: 1 branch
BranchTrueFalseTotal
defined $cache && $cache == 0 ? : 0 0 0
Condition0%0/3
defined $cache and $cache == 0
!ll&&!rl&&r
000
MC/DC0%0/2
defined $cache and $cache == 0
defined $cache $cache == 0
Truth table0%0/3
A and B
A= defined $cacheB= $cache == 0
ABresult
0X0
100
111
200 0 my $pobj = $self->parameter_base;
201 0 ▶ if ($pobj->parameters_changed ||
Branch: 1 branch
BranchTrueFalseTotal
if ($pobj->parameters_changed or not $cache or not $self->{'_response_cache'} or not $self->{'_response_cache'}->content) { } 0 0 0
Condition0%0/9
$pobj->parameters_changed or not $cache or not $self->{"_response_cache"} or not $self->{"_response_cache"}->content
l!l&&r!l&&!r
000
$pobj->parameters_changed or not $cache or not $self->{"_response_cache"}
l!l&&r!l&&!r
000
$pobj->parameters_changed or not $cache
l!l&&r!l&&!r
000
MC/DC0%0/4
$pobj->parameters_changed or not $cache or not $self->{"_response_cache"} or not $self->{"_response_cache"}->content
$pobj->parameters_changed not $cache not $self->{"_response_cache"} not $self->{"_response_cache"}->content
Truth table0%0/5
A or not(B) or not(C) or not(D)
A= $pobj->parameters_changedB= not $cacheC= not $self->{"_response_cache"}D= not $self->{"_response_cache"}->content
ABCDresult
1XXX1
01XX1
001X1
00011
00000
202 !$cache ||
203 !$self->{_response_cache} ||
204 !$self->{_response_cache}->content) {
205 0 my $ua = $self->ua;
206 0 $self->_sleep; # institute delay policy
207 0 ▶ $self->throw('No parameter object set; cannot form a suitable remote request') unless $pobj;
Branch: 1 branch
BranchTrueFalseTotal
unless $pobj 0 0 0
208 0 my $request = $pobj->to_request;
209 0 ▶ if ($self->authentication) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->authentication) 0 0 0
210 0 $request->proxy_authorization_basic($self->authentication)
211 }
212 0 $self->debug("Request is: \n",$request->as_string);
213 # I'm relying on the useragent to throw the proper errors here
214 0 my $response = $ua->request($request, @opts);
215 0 ▶ if ($response->is_error) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response->is_error) 0 0 0
216 0 $self->throw("Response Error\n".$response->message);
217 }
218 0 return $self->{_response_cache} = $response;
219 } else {
220 0 $self->debug("Returning cached HTTP::Response object\n");
221 0 ▶ if ($file) {
Branch: 2 branches
BranchTrueFalseTotal
if ($file) { } 0 0 0
elsif ($cb) { } 0 0 0
222 0 $self->_dump_request_content($file);
223 # size isn't passed here, as the content is completely retrieved above
224 } elsif ($cb) {
225 0 ▶ $cb && ref($cb) eq 'CODE' && $cb->($self->{_response_cache}->content);
Branch: 1 branch
BranchTrueFalseTotal
$cb and ref $cb eq "CODE" and &$cb($self->{"_response_cache"}->content) 0 0 0
Condition0%0/3
$cb and ref $cb eq "CODE"
!ll&&!rl&&r
000
MC/DC0%0/2
$cb and ref $cb eq "CODE"
$cb ref $cb eq "CODE"
Truth table0%0/3
A and B
A= $cbB= ref $cb eq "CODE"
ABresult
0X0
100
111
226 }
227 0 return $self->{_response_cache};
228 }
229 }
230  
231 =head2 get_Parser
232  
233 Title : get_Parser
234 Usage : $agent->get_Parser;
235 Function: Return HTTP::Response content (file, fh, object) attached to defined parser
236 Returns : None
237 Args : None
238 Note : Abstract method; defined by implementation
239  
240 =cut
241  
242 0 ▶sub get_Parser {
Subroutine get_Parser: not called CC=1 SCAR=6.9
Pod documented
243 0 shift->throw_not_implemented;
244 }
245  
246 =head2 delay
247  
248 Title : delay
249 Usage : $secs = $self->delay($secs)
250 Function: get/set number of seconds to delay between fetches
251 Returns : number of seconds to delay
252 Args : new value
253  
254 NOTE: the default is to use the value specified by delay_policy().
255 This can be overridden by calling this method.
256  
257 =cut
258  
259 0 ▶sub delay {
Subroutine delay: not called CC=2 SCAR=17.9
Pod documented
260 0 my $self = shift;
261 0 ▶ return $self->{'_delay'} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 0 0
262 0 return $self->{'_delay'};
263 }
264  
265 =head2 delay_policy
266  
267 Title : delay_policy
268 Usage : $secs = $self->delay_policy
269 Function: return number of seconds to delay between calls to remote db
270 Returns : number of seconds to delay
271 Args : none
272  
273 NOTE: The default delay policy is 3s. Override in subclasses to
274 implement delays. The timer has only second resolution, so the delay
275 will actually be +/- 1s.
276  
277 =cut
278  
279 0 ▶sub delay_policy {
Subroutine delay_policy: not called CC=1 SCAR=6.9
Pod documented
280 0 my $self = shift;
281 0 return 3;
282 }
283  
284 =head2 _sleep
285  
286 Title : _sleep
287 Usage : $self->_sleep
288 Function: sleep for a number of seconds indicated by the delay policy
289 Returns : none
290 Args : none
291  
292 NOTE: This method keeps track of the last time it was called and only
293 imposes a sleep if it was called more recently than the delay_policy()
294 allows.
295  
296 =cut
297  
298 0 ▶sub _sleep {
Subroutine _sleep: not called CC=3 SCAR=24.8
299 0 my $self = shift;
300 0 my $last_invocation = $LAST_INVOCATION_TIME;
301 0 ▶ if (time - $LAST_INVOCATION_TIME < $self->delay) {
Branch: 1 branch
BranchTrueFalseTotal
if (time - $LAST_INVOCATION_TIME < $self->delay) 0 0 0
302 0 my $delay = $self->delay - (time - $LAST_INVOCATION_TIME);
303 0 $self->debug("sleeping for $delay seconds\n");
304 0 ▶ if ($TIME_HIRES) {
Branch: 1 branch
BranchTrueFalseTotal
if ($TIME_HIRES) { } 0 0 0
305 # allows precise sleep timeout (builtin only allows integer seconds)
306 0 Time::HiRes::sleep($delay);
307 } else {
308 # allows precise sleep timeout (builtin only allows integer seconds)
309  
310 # I hate this hack , but needed if we support 5.6.1 and
311 # don't want additional Time::HiRes prereq
312 0 select undef, undef, undef, $delay;
313 }
314 }
315 0 $LAST_INVOCATION_TIME = time;
316 }
317  
318 =head1 LWP::UserAgent related methods
319  
320 =head2 proxy
321  
322 Title : proxy
323 Usage : $httpproxy = $db->proxy('http') or
324 $db->proxy(['http','ftp'], 'http://myproxy' )
325 Function: Get/Set a proxy for use of proxy
326 Returns : a string indicating the proxy
327 Args : $protocol : an array ref of the protocol(s) to set/get
328 $proxyurl : url of the proxy to use for the specified protocol
329 $username : username (if proxy requires authentication)
330 $password : password (if proxy requires authentication)
331  
332 =cut
333  
334 0 ▶sub proxy {
Subroutine proxy: not called CC=5 SCAR=34.0
Pod documented
335 0 my ($self,$protocol,$proxy,$username,$password) = @_;
336 0 ▶ return if ( !defined $protocol || !defined $proxy );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $protocol and defined $proxy 0 0 0
Condition0%0/3
defined $protocol and defined $proxy
!ll&&!rl&&r
000
MC/DC0%0/2
defined $protocol and defined $proxy
defined $protocol defined $proxy
Truth table0%0/3
A and B
A= defined $protocolB= defined $proxy
ABresult
0X0
100
111
337 0 ▶ $self->authentication($username, $password)
Branch: 1 branch
BranchTrueFalseTotal
if $username and $password 0 0 0
Condition0%0/3
$username and $password
!ll&&!rl&&r
000
MC/DC0%0/2
$username and $password
$username $password
Truth table0%0/3
A and B
A= $usernameB= $password
ABresult
0X0
100
111
338 if ($username && $password);
339 0 return $self->ua->proxy($protocol,$proxy);
340 }
341  
342 =head2 authentication
343  
344 Title : authentication
345 Usage : $db->authentication($user,$pass)
346 Function: Get/Set authentication credentials
347 Returns : Array of user/pass
348 Args : Array or user/pass
349  
350 =cut
351  
352 0 ▶sub authentication{
Subroutine authentication: not called CC=4 SCAR=30.0
Pod documented
353 0 my ($self,$u,$p) = @_;
354 0 ▶ if( defined $u && defined $p ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $u and defined $p) 0 0 0
Condition0%0/3
defined $u and defined $p
!ll&&!rl&&r
000
MC/DC0%0/2
defined $u and defined $p
defined $u defined $p
Truth table0%0/3
A and B
A= defined $uB= defined $p
ABresult
0X0
100
111
355 0 $self->{'_authentication'} = [ $u,$p];
356 }
357 0 ▶ $self->{'_authentication'} && return @{$self->{'_authentication'}};
Branch: 1 branch
BranchTrueFalseTotal
$self->{"_authentication"} and return @{$self->{"_authentication"};} 0 0 0
358 }
359  
360 # private method to dump any cached request data content into a passed filename
361  
362 0 ▶sub _dump_request_content {
Subroutine _dump_request_content: not called CC=3 SCAR=24.8
363 0 my ($self, $file) = @_;
364 0 ▶ return unless defined $self->{_response_cache};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_response_cache"} 0 0 0
365 0 ▶ $self->throw("Must pass file name") unless $file;
Branch: 1 branch
BranchTrueFalseTotal
unless $file 0 0 0
366 0 require Bio::Root::IO;
367 0 my $out = Bio::Root::IO->new(-file => ">$file");
368 0 $out->_print($self->{_response_cache}->content);
369 0 $out->flush();
370 0 $out->close;
371 }
372  
373 1 1;
« Bio/Search/HSP/PsiBlastHSP.pm ↑ Summary Bio/SeqFeatureI.pm »