Bio::Phylo::PhyloWS::Service(3)

NAME
Bio::Phylo::PhyloWS::Service - Base class for phylogenetic web services

SYNOPSIS
 # inside a CGI script:
 use CGI;
 use Bio::Phylo::PhyloWS::Service::${child};

 my $service = Bio::Phylo::PhyloWS::Service::${child}->new( '-url' => $url );
 $service->handle_request(CGI->new);

DESCRIPTION
This is the base class for services that implement the PhyloWS (<http://evoinfo.nescent.org/PhyloWS>) recommendations. Such services should subclass this class and implement any relevant abstract methods. Examples of this are Bio::Phylo::PhyloWS::Service::Tolweb and Bio::Phylo::PhyloWS::Service::Ubio.

PhyloWS services are web services for phylogenetics that provide two types of functionality:

Record lookup
    Services that implement record lookups are services that know how to process URL requests of the form "/phylows/$object_type/$authority:$identifier?format=$format", where $object_type is a string representing the type of object that is returned, e.g. 'tree', 'matrix', 'taxon', etc., $authority is a naming authority such as TB2 for TreeBASE2, $identifier is a local identifier for the object, for example an accession number, and $format is a serialization format such as 'nexml'.

    In order to provide this functionality, subclasses of this class must implement a method called "get_record" which is passed at least a named "-guid" argument that provides the local identifier. The "get_record" method must return a Bio::Phylo::Project object, which is subsequently serialized in the requested format by the "handle_request" method provided here.

Record search
    Services that implement record searches are services that know how to process URL requests of the form "/phylows/$object_type/find?query=$query&format=$format", where $object_type is a string representing the type of object to search for, $query is a CQL query (<http://www.loc.gov/standards/sru/specs/cql.html>), and $format is the serialization format in which the returned results are represented.

    In order to provide this functionality, subclasses of this class must implement a method called "get_query_result", which is passed the $query parameter and which must return a Bio::Phylo::Project object that combines the search results (e.g. in a single taxa block for taxon searches).

    CQL has different levels of support, services may only implement certain levels of support. The example services Bio::Phylo::PhyloWS::Service::Tolweb and Bio::Phylo::PhyloWS::Service::Ubio only proved Level 0, term-only support, meaning that $query is simply a term such as "Homo+sapiens".

Child classes that implement some or all of the functionality described above can subsequently be made operational on a web server by calling them from a simple CGI script as shown in the SYNOPSIS section, where $child must be substituted by the actual class name of the child class (e.g. "Tolweb"). The $url parameter that is passed to the constructor is usually simply the URI of the CGI script, i.e. the environment variable $ENV{'SCRIPT_URI'} under most standard HTTP servers.

  REQUEST HANDLER

handle_request()
     Type    : Request handler
     Title   : handle_request
     Usage   : $service->handle_request($cgi);
     Function: Handles a service request
     Returns : prints out response and exits
     Args    : Required: a CGI.pm object

  ACCESSORS

get_result()
    Gets a phylows result, either a record lookup or a query result, depending on the internal state of the service object

     Type    : Accessor
     Title   : get_result
     Usage   : my $proj = $obj->get_result;
     Function: Gets a phylows result
     Returns : Bio::Phylo::Project
     Args    : None
     Comments:

get_record()
    Gets a phylows record by its id

     Type    : Abstract Accessor
     Title   : get_record
     Usage   : my $record = $obj->get_record( -guid => $guid );
     Function: Gets a phylows record by its id
     Returns : Bio::Phylo::Project
     Args    : Required: -guid => $guid,
               Optional: -format => $format
     Comments: This is an ABSTRACT method that needs to be implemented
               by a child class

get_query_result()
    Gets a phylows cql query result

     Type    : Abstract Accessor
     Title   : get_query_result
     Usage   : my $result = $obj->get_query_result( $query );
     Function: Gets a query result
     Returns : Bio::Phylo::Project
     Args    : Required: $query
     Comments: This is an ABSTRACT method that needs to be implemented
               by a child class

get_supported_formats()
    Gets an array ref of supported formats

     Type    : Abstract Accessor
     Title   : get_supported_formats
     Usage   : my @formats = @{ $obj->get_supported_formats };
     Function: Gets an array ref of supported formats
     Returns : ARRAY
     Args    : NONE
     Comments: This is an ABSTRACT method that needs to be implemented
               by a child class

get_redirect()
    Gets a redirect URL if relevant

     Type    : Accessor
     Title   : get_redirect
     Usage   : my $url = $obj->get_redirect;
     Function: Gets a redirect URL if relevant
     Returns : String
     Args    : $cgi
     Comments: This method is called by handle_request so that
               services can 303 redirect a record lookup to
               another URL. By default, this method returns
               undef (i.e. no redirect)

get_description()
    Gets an RSS1.0/XML representation of a phylows record

     Type    : Accessor
     Title   : get_description
     Usage   : my $desc = $obj->get_description;
     Function: Gets an RSS1.0/XML representation of a phylows record
     Returns : String
     Args    : None
     Comments: This method creates a representation of a single record
               (i.e. the service's base url + the record's guid)
               that can be serialized in whichever formats are
               supported

SEE ALSO
There is a mailing list at <https://groups.google.com/forum/#!forum/bio-phylo> for any user or developer questions and discussions.

Also see the manual: Bio::Phylo::Manual and <http://rutgervos.blogspot.com>

CITATION
If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. <http://dx.doi.org/10.1186/1471-2105-12-63>