Phylo/PhyloWS/Service.pm untested

filter: Statementstmt 0.0% 0 / 101 Branchbran 0.0% 0 / 20 Conditioncond 0.0% 0 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 0.0% 0 / 17 Podpod 0.0% 0 / 8 totaltotal 0.0% 0 / 151 CC 11 SCAR 24.2
CC
11
Cov
0%
_process_request_params
30.0
handle_request
20.0
get_result
12.0
CRAP 11.3
1 package Bio::Phylo::PhyloWS::Service;
2 use strict;
3 use warnings;
4 use base 'Bio::Phylo::PhyloWS';
5 use Bio::Phylo::Factory;
6 use Bio::Phylo::IO 'unparse';
7 use Bio::Phylo::Util::CONSTANT qw'looks_like_hash _HTTP_SC_SEE_ALSO_';
8 use Bio::Phylo::Util::Exceptions 'throw';
9 use Bio::Phylo::Util::Dependency 'URI::Escape';
10 use Bio::Phylo::Util::Logger;
11 {
12 my $fac = Bio::Phylo::Factory->new;
13 my $logger = Bio::Phylo::Util::Logger->new;
14  
15 =head1 NAME
16  
17 Bio::Phylo::PhyloWS::Service - Base class for phylogenetic web services
18  
19 =head1 SYNOPSIS
20  
21 # inside a CGI script:
22 use CGI;
23 use Bio::Phylo::PhyloWS::Service::${child};
24  
25 my $service = Bio::Phylo::PhyloWS::Service::${child}->new( '-url' => $url );
26 $service->handle_request(CGI->new);
27  
28 =head1 DESCRIPTION
29  
30 This is the base class for services that implement
31 the PhyloWS (L<http://evoinfo.nescent.org/PhyloWS>) recommendations.
32 Such services should subclass this class and implement any relevant
33 abstract methods. Examples of this are L<Bio::Phylo::PhyloWS::Service::Tolweb>
34 and L<Bio::Phylo::PhyloWS::Service::Ubio>.
35  
36 PhyloWS services are web services for phylogenetics that provide two types of
37 functionality:
38  
39 =over
40  
41 =item Record lookup
42  
43 Services that implement record lookups are services that know how to process
44 URL requests of the form C</phylows/$object_type/$authority:$identifier?format=$format>,
45 where C<$object_type> is a string representing the type of object that is
46 returned, e.g. 'tree', 'matrix', 'taxon', etc., $authority is a naming authority
47 such as TB2 for TreeBASE2, $identifier is a local identifier for the object,
48 for example an accession number, and $format is a serialization format such as
49 'nexml'.
50  
51 In order to provide this functionality, subclasses of this class must implement
52 a method called C<get_record> which is passed at least a named C<-guid> argument
53 that provides the local identifier. The C<get_record> method must return a
54 L<Bio::Phylo::Project> object, which is subsequently serialized in the requested
55 format by the C<handle_request> method provided here.
56  
57 =item Record search
58  
59 Services that implement record searches are services that know how to process
60 URL requests of the form C</phylows/$object_type/find?query=$query&format=$format>,
61 where $object_type is a string representing the type of object to search for,
62 $query is a CQL query (L<http://www.loc.gov/standards/sru/specs/cql.html>), and
63 $format is the serialization format in which the returned results are represented.
64  
65 In order to provide this functionality, subclasses of this class must implement
66 a method called C<get_query_result>, which is passed the $query parameter and
67 which must return a L<Bio::Phylo::Project> object that combines the search
68 results (e.g. in a single taxa block for taxon searches).
69  
70 CQL has different levels of support, services may only implement certain levels
71 of support. The example services L<Bio::Phylo::PhyloWS::Service::Tolweb>
72 and L<Bio::Phylo::PhyloWS::Service::Ubio> only proved Level 0, term-only support,
73 meaning that C<$query> is simply a term such as C<Homo+sapiens>.
74  
75 =back
76  
77 Child classes that implement some or all of the functionality described above
78 can subsequently be made operational on a web server by calling them from a
79 simple CGI script as shown in the SYNOPSIS section, where C<$child> must be
80 substituted by the actual class name of the child class (e.g. C<Tolweb>). The
81 C<$url> parameter that is passed to the constructor is usually simply the URI
82 of the CGI script, i.e. the environment variable C<$ENV{'SCRIPT_URI'}> under
83 most standard HTTP servers.
84  
85 =head2 REQUEST HANDLER
86  
87 =over
88  
89 =item handle_request()
90  
91 Type : Request handler
92 Title : handle_request
93 Usage : $service->handle_request($cgi);
94 Function: Handles a service request
95 Returns : prints out response and exits
96 Args : Required: a CGI.pm object
97  
98 =cut
99  
100 sub _process_request_params {
101 my ( $self, $cgi ) = @_;
102 $self->set_format($cgi->param('format'));
103 $self->set_query($cgi->param('query'));
104 my $path = $cgi->path_info;
105 my $section;
106 if ( $path =~ m|/phylows/([a-z]+)/| ) {
107 $section = $1;
108 $self->set_section($section);
109 }
110 if ( $path !~ /find/ && $path =~ m|/phylows/$section/(.+?):(.+)$|) {
111 my ( $authority, $guid ) = ( $1, $2 );
112 if ( $authority ne $self->get_authority ) {
113 throw 'BadArgs' => ref($self) . " can't process identifiers "
114 ."with the $authority prefix";
115 }
116 $self->set_guid($guid);
117 }
118 if ( $path !~ /phylows/ ) {
119 $logger->warn("'$path' is not a PhyloWS URL");
120 }
121 }
122
123 sub handle_request {
124 my ( $self, $cgi ) = @_; # CGI.pm
125 $self->_process_request_params($cgi);
126
127 # there is a different address under the given conditions.
128 # typically this is the case if there are web pages we can
129 # point to.
130 if ( my $redirect = $self->get_redirect($cgi) ) {
131 $logger->info("Redirecting to $redirect");
132 print $cgi->redirect(
133 '-uri' => $redirect,
134 '-status' => _HTTP_SC_SEE_ALSO_,
135 );
136 }
137
138 # a serialization format has been specified
139 if ( my $f = $self->get_format ) {
140 $logger->info("Returning $f serialization");
141 my %args = (
142 '-format' => $f,
143 '-phylo' => $self->get_result,
144 );
145 if ( my $recordSchema = $cgi->param('recordSchema') ) {
146 $args{'-recordSchema'} = $recordSchema;
147 }
148 print $cgi->header( $Bio::Phylo::PhyloWS::MIMETYPE{$f} );
149 binmode STDOUT, ":utf8";
150 print unparse(%args);
151 }
152
153 # no serialization format has been specified, returning a
154 # resource description instead
155 else {
156 $logger->info("Returning RDF description");
157 print $cgi->header( $Bio::Phylo::PhyloWS::MIMETYPE{'rdf'} );
158 binmode STDOUT, ":utf8";
159 print $self->get_description->to_xml;
160 }
161
162 exit(0);
163 }
164  
165 =back
166  
167 =head2 ACCESSORS
168  
169 =over
170  
171 =item get_result()
172  
173 Gets a phylows result, either a record lookup or a query result,
174 depending on the internal state of the service object
175  
176 Type : Accessor
177 Title : get_result
178 Usage : my $proj = $obj->get_result;
179 Function: Gets a phylows result
180 Returns : Bio::Phylo::Project
181 Args : None
182 Comments:
183  
184 =cut
185  
186 sub get_result {
187 my $self = shift;
188 my $name = ref($self);
189 $name =~ s/.+://;
190 my $proj;
191 if ( my $id = $self->get_guid ) {
192 $proj = $self->get_record( '-guid' => $id );
193 $proj->set_name("$name PhyloWS record lookup service");
194 $proj->set_desc("Results for ID: $id");
195 }
196 elsif ( my $query = $self->get_query ) {
197 $proj = $self->get_query_result($query);
198 $proj->set_name("$name PhyloWS query service");
199 $proj->set_desc("Results for query: $query");
200 }
201 else {
202 throw 'BadArgs' => "Neither GUID nor query provided!";
203 }
204 $proj->set_link($self->get_url);
205 return $proj;
206 }
207  
208 =item get_record()
209  
210 Gets a phylows record by its id
211  
212 Type : Abstract Accessor
213 Title : get_record
214 Usage : my $record = $obj->get_record( -guid => $guid );
215 Function: Gets a phylows record by its id
216 Returns : Bio::Phylo::Project
217 Args : Required: -guid => $guid,
218 Optional: -format => $format
219 Comments: This is an ABSTRACT method that needs to be implemented
220 by a child class
221  
222 =cut
223  
224 sub get_record {
225 my $self = shift;
226 throw 'NotImplemented' => 'Method get_record should be in '
227 . ref($self)
228 . ", but isn't";
229 }
230  
231 =item get_query_result()
232  
233 Gets a phylows cql query result
234  
235 Type : Abstract Accessor
236 Title : get_query_result
237 Usage : my $result = $obj->get_query_result( $query );
238 Function: Gets a query result
239 Returns : Bio::Phylo::Project
240 Args : Required: $query
241 Comments: This is an ABSTRACT method that needs to be implemented
242 by a child class
243  
244 =cut
245  
246 sub get_query_result {
247 my $self = shift;
248 throw 'NotImplemented' => 'Method get_query_result should be in '
249 . ref($self)
250 . ", but isn't";
251 }
252  
253 =item get_supported_formats()
254  
255 Gets an array ref of supported formats
256  
257 Type : Abstract Accessor
258 Title : get_supported_formats
259 Usage : my @formats = @{ $obj->get_supported_formats };
260 Function: Gets an array ref of supported formats
261 Returns : ARRAY
262 Args : NONE
263 Comments: This is an ABSTRACT method that needs to be implemented
264 by a child class
265  
266 =cut
267  
268 sub get_supported_formats {
269 my $self = shift;
270 throw 'NotImplemented' => 'Method get_supported_formats should be in '
271 . ref($self)
272 . ", but isn't";
273 }
274  
275 =item get_redirect()
276  
277 Gets a redirect URL if relevant
278  
279 Type : Accessor
280 Title : get_redirect
281 Usage : my $url = $obj->get_redirect;
282 Function: Gets a redirect URL if relevant
283 Returns : String
284 Args : $cgi
285 Comments: This method is called by handle_request so that
286 services can 303 redirect a record lookup to
287 another URL. By default, this method returns
288 undef (i.e. no redirect)
289  
290 =cut
291  
292 sub get_redirect {
293 my ( $self, $cgi ) = @_;
294 return;
295 }
296  
297 =item get_description()
298  
299 Gets an RSS1.0/XML representation of a phylows record
300  
301 Type : Accessor
302 Title : get_description
303 Usage : my $desc = $obj->get_description;
304 Function: Gets an RSS1.0/XML representation of a phylows record
305 Returns : String
306 Args : None
307 Comments: This method creates a representation of a single record
308 (i.e. the service's base url + the record's guid)
309 that can be serialized in whichever formats are
310 supported
311  
312 =cut
313  
314 sub get_description {
315 my $self = shift;
316
317 # create constructor args
318 my %args = (
319 '-section' => $self->get_section,
320 '-base_uri' => $self->get_base_uri,
321 );
322 if ( $self->get_query ) {
323 $args{'-query'} = $self->get_query;
324 }
325 else {
326 $args{'-authority'} = $self->get_authority;
327 $args{'-guid'} = $self->get_guid;
328 }
329
330 # create root description
331 my $desc = $fac->create_description(
332 '-name' => 'About ' . $self->get_url,
333 '-desc' => 'Available serializations for this resource',
334 %args,
335 );
336
337 # create available resources
338 for my $format ( @{ $self->get_supported_formats } ) {
339 $desc->insert(
340 $fac->create_resource(
341 '-format' => $format,
342 '-name' => $format,
343 '-desc' => "A $format serialization of the resource",
344 %args
345 )
346 );
347 }
348 return $desc;
349 }
350  
351 =back
352  
353 =cut
354  
355 # podinherit_insert_token
356  
357 =head1 SEE ALSO
358  
359 There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo>
360 for any user or developer questions and discussions.
361  
362 Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com>
363  
364 =head1 CITATION
365  
366 If you use Bio::Phylo in published research, please cite it:
367  
368 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
369 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
370 I<BMC Bioinformatics> B<12>:63.
371 L<http://dx.doi.org/10.1186/1471-2105-12-63>
372  
373 =cut
374  
375 }
376 1;