| 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; |