Phylo/PhyloWS/Service.pm untested

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