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