[Bio] / FigKernelPackages / SAPserver.pm Repository:
ViewVC logotype

View of /FigKernelPackages/SAPserver.pm

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.8 - (download) (as text) (annotate)
Tue Sep 8 21:31:32 2009 UTC (10 years, 3 months ago) by parrello
Branch: MAIN
CVS Tags: rast_rel_2009_0925
Changes since 1.7: +48 -29 lines
Changed to allow specification of 'localhost" for the server URL. When this is done, the SAP module is called directly instead of remotely through the server.

#!/usr/bin/perl -w
#	This is a SAS Component.
# Copyright (c) 2003-2006 University of Chicago and Fellowship
# for Interpretations of Genomes. All Rights Reserved.
# This file is part of the SEED Toolkit.
# The SEED Toolkit is free software. You can redistribute
# it and/or modify it under the terms of the SEED Toolkit
# Public License.
# You should have received a copy of the SEED Toolkit Public License
# along with this program; if not write to the University of Chicago
# at info@ci.uchicago.edu or the Fellowship for Interpretation of
# Genomes at veronika@thefig.info or download a copy from
# http://www.theseed.org/LICENSE.TXT.

package SAPserver;

    use strict;
    use YAML;

=head1 Sapling Server Helper Object

=head2 Description

This module is used to call the sapling server, which is a general-purpose
server for extracting data from the Sapling database. Each Sapling server
function correspond to a method of this object.

This package deliberately uses no internal SEED packages or scripts, only common
PERL modules.

The fields in this object are as follows.

=over 4

=item server_url

The URL used to request data from the sapling server. If C<localhost> is
specified, then the L<SAP> module will be called directly.

=item ua

The user agent for communication with the server.

=item singleton

Indicates whether or not results are to be returned in singleton mode. In
singleton mode, if the return document is a hash reference with only one
entry, the entry value is returned rather than the hash.



=head3 new

    my $ss = SAPserver->new(%options);

Construct a new SAPserver object. The following options are supported.

=over 4

=item url

URL for the sapling server. This option may be used to redirect requests to a
test version of the server, or to an older server script.

=item singleton

If TRUE, results from methods will be returned in singleton mode. In singleton
mode, if a single result comes back, it will come back as a scalar rather than
as a hash value accessible via an incoming ID.



sub new {
    # Get the parameters.
    my ($class, %options) = @_;
    # Get the options.
    my $url = $options{url} || "http://servers.nmpdr.org/sapling/server.cgi";
    my $singleton = $options{singleton} || 0;
    # Create the fields of the object. Note that if we're in localhost mode,
    # the user agent is actually a SAP object.
    my $server_url = $url;
    my $ua;
    if ($server_url ne 'localhost') {
        require LWP::UserAgent;
        $ua = LWP::UserAgent->new();
    } else {
        require SAP;
        $ua = SAP->new();
    # Create the SAPserver object.
    my $retVal = { 
                    server_url => $server_url,
                    ua => $ua,
                    singleton => $singleton,
    # Bless and return it.
    bless $retVal, $class;
    return $retVal;

=head2 Public Methods

All L<SAP/Primary Methods> are also methods of this object.


    my $result = $ss->method(%args);

Call a function on the server. Any method call on this object (other than
the constructor) is translated into a request against the server. This
enables us to add new server functions without requiring an update to this
module. The parameters are specified as a hash, and the result is a scalar
or object reference. If an error occurred, we will throw an exception.


# This variable will contain the method name.

    # Get the parameters. We do some fancy dancing to allow the user to pass
    # in a hash or a hash reference.
    my $self = shift @_;
    my $args = $_[0];
    if (defined $args && ref $args ne 'HASH') {
        my %args = @_;
        $args = \%args;
    # Declare the return variable.
    my $retVal;
    # Get the method name.
    my $function = $AUTOLOAD;
    # Strip off the stuff before the method name.
    $function =~ s/.+:://;
    # Get our user agent.
    my $ua = $self->{ua};
    # Determine the type.
    if (ref $ua eq 'LWP::UserAgent') {
        # Here we're going to a server. Compute the argument document.
        my $argString = YAML::Dump($args);
        # Request the function from the server.
        my $response = $ua->post($self->{server_url},
                                 [function => $function, args => $argString,
                                  source => __PACKAGE__ ]);
        # Get the response content.
        my $content = $response->content;
        if (! $response->is_success) {
            die "Server error " . $response->status_line . "\n$content";
        } else {
            $retVal = YAML::Load($content);
            # Figure out what we got back.
            my $returnType = ref $retVal;
            if ($returnType) {
                if ($returnType eq 'ErrorDocument') {
                    # Here an error occurred, so we throw an exception using the
                    # error message.
                    die $retVal->{message};
    } else {
        # Here we're calling a local method.
        $retVal = eval("\$ua->$function(\$args)");
        # Check for an error.
        if ($@) {
            die "Package error: $@";
    # We have our result. Adjust for singleton mode.
    if ($self->{singleton} && ref $retVal eq 'HASH' && scalar(keys %$retVal) <= 1) {
        # Here we're in singleton mode and we got a single result,
        # so we dereference a bit to make it easier for the user
        # to access it.
        ($retVal) = values %$retVal;
    # Return the result.
    return $retVal;

=head3 DESTROY


This method has no function. It's purpose is to keep the destructor from
being caught by the autoload processing.


sub DESTROY { }


MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3