/ 
Webservice-InterMine-0.9704
River stage one • 1 direct dependent • 1 total dependent
/ Webservice::InterMine::Service

NAME

Webservice::InterMine::Service - an object representation of an Webservice::InterMine Web-Service

SYNOPSIS

 use Webservice::InterMine;

 my $service = Webservice::InterMine->get_service('www.flymine.org/query/service');

 # Construct queries...
 my $query    = $service->new_query(class => 'Gene');

 # Access templates...
 my $template = $service->template('Probe_Genes')
     or die "Cannot find template"

 # Manage lists
 my $new_list = $service->new_list(content => $filename, type => 'Gene');
 my $existing_list = $service->list($name);

 # Get metadata
 my $model = $service->model

 # Get path info
 my $path = $service->new_path("Gene.homologues.homologue.symbol");

 # ... do stuff with your objects

DESCRIPTION

The service object is the portal to the webservice: it provides the model and templates for the objects you want to construct, and is used by the queries to return results. Generally you won't need to interact with it directly, or if you do, the methods you will be most interested in are those that return objects you can use for running queries.

new( $url, [$user, $pass] )

A service can be constructed directly by passing a webservice url to the new method. To have access to private data (personal templates, saved queries and lists) you also need to provide login information in the form of a username and password.

CONSTRUCTION

Webservice::InterMine->get_service($root, $user, $pass)

Typically as service is most conveniently obtained through the Webservice::InterMine interface.

new($root, $user, $pass)

It can of course be instantiated directly, with a standard call to new.

don't!

You do not have to obtain a service object: simply call the methods on the Webservice::InterMine factory class to obtain new queries, fetch templates and load saved queries.

ATTRIBUTES

root | user | pass

The values passed into the constructor can be accessed via these methods. Note that the url passed in will have a scheme added if none was provided.

model

The data model for the webservice. This model is required by many modules for checking validity with the webservice database schema. See InterMine::Model

version

The version of the webservice - used for determining compatibility with different query formats. The version is always an integer. An attempt to get the version is made on instantiation, which serves to validate the webservice.

release

The release string of the webservice. The release is the version of the data-warehouse, and should change for any data added to it.

agent

An LWP::UserAgent suitable for getting and posting with. This agent will authenticate to the given user and password credentials if given.

METHODS

new_query([%args])

This returns a new query object for you to define by adding constraints and a view to.

The most useful arguments are the root class, eg:

my $query = $service->new_query(class => 'Gene');

With this, you can use the shortcuts for adding views:

# Adds all attributes
$query->add_views('*');

And avoid having to repeat the root class on other calls:

# 'Gene.' is now optional
$query->add_constraint('symbol', '=', 'eve');

See Webservice::InterMine::Query

new_from_xml(source_file => $file_name)

Returns a new query by unmarshalling a serialised xml query.

See Webservice::InterMine::Query

Template Methods:

For handling template objects, see Webservice::InterMine::Query::Template

  • template( $name )

    This checks to see if there is a template of this name in the webservice, and returns it to you if it exists. If the user has provided user credentials, then that user's private templates will also be accessible. If the template exists but cannot be parsed (and so will not run) an exception will be throws (which it up to you to catch).

  • get_templates()

    Returns all the templates available from the service as a list. If the user has provided user credentials, then that user's private templates will also be accessible. The number of templates returned in this list may NOT be the same as the figure returned by get_template_count - any templates that cannot be parsed (and so will not run) are excluded from the list.

  • get_template_count()

    Gets the count of all templates reported as available at the webservice. This may include broken templates.

  • get_template_names()

    Returns a list of names of the templates available at the service. No guarantee is made to the order these names are returned in - you may have to do some sorting if you require them to be alphabetical. This list includes all templates, working or broken.

List Methods

For handling list objects, see Webservice::InterMine::List.

list( $name )

Get the list with the given name, if it exists. Returns undef if the given list is not accessible (either because it does not exist or because the service is not authenticated to the correct user account).

lists()

Get all the lists that this service has access to.

list_names()

Get all the names of the lists this service has access to.

new_list(content => $content, [type => $class], [name => $name], [description => $description])

Make a new list on the server with the given content and return a Webservice::InterMine::List object referring to it.

Args:

  • content

    can be a filename, an array ref of identifiers, a string containing identifiers (separated by whitespace and quoted, if necessary by double-quotes), or a Webservice::InterMine::Query (specifically, a Webservice::InterMine::Query::Roles::Listable query.

  • type (required, unless the content is a query)

    The type of the items in this list. The type must be one of the of the classes in the model.

  • name [optional]

    The name of the list to create. If not name is supplied, one will be generated for you, and the resulting list will be cleaned up (deleted) when the program exits. (Renaming the list later will prevent this clean up, as will setting the $CLEAN_UP variable in Webservice::InterMine.)

  • description [optional]

    A long form description of the nature of this list. Optional. One will be generated if none is provided.

  • path [required if the content is a Template]

    The path to determine the list type for Templates.

join_lists(\@lists, [$name, $description)

Join the given lists to create a new one (with the optional name and description) from their union. The lists can be given as Webservice::InterMine::List objects, Webservice::InterMine::Query::Roles::Listable queries, or the names of the lists to join.

subtract_lists(\@from, \@to_be_subtracted, [$name, $description])

Subtract the lists to be subtracted from the union of the list of lists to subtract from, creating a new one (with the optional name and description). The lists can be given as Webservice::InterMine::List objects, Webservice::InterMine::Query::Roles::Listable queries, or the names of lists the service has access to.

intersect_lists(\@lists, [$name, $description)

Intersect the given lists to create a new one (with the optional name and description) from their intersection. The lists can be given as Webservice::InterMine::List objects, Webservice::InterMine::Query::Roles::Listable queries, or the names of lists the service has access to.

diff_lists(\@lists, [$name, $description)

Calculate the symmetric difference of the given lists to create a new one (with the optional name and description). The lists can be given as Webservice::InterMine::List objects, Webservice::InterMine::Query::Roles::Listable queries, or the names of lists the service has access to.

delete_lists(@lists)

Delete the given lists from the service. If the lists don't exist, an error will be thrown. Consider also calling the delete method directly on Webservice::InterMine::List objects.

delete_temp_lists()

Delete all anonymous list created by the programme. This method is automatically called on programme exist unless the variable $Webservice::InterMine::CLEAN_UP is set to a false value.

get_list_data()

Get the string containing list data from the service.

new_path(Str path, [path => class, ...])

Construct new path objects for use with path based webservices. The path will be immediately validated, so it is important that any subclass constraints that affect this path's validity are included. Subclass constraints can be listed as key-value pairs, or as a hash-ref.

EG:

my $path = $service->new_path("Department.employees.name");
my $path = $service->new_path("Department.employees.name", 
  "Department.employees" => "Manager");
my $path = $service->new_path("Department.employees.name", 
  {"Department.employees" => "Manager"});

Any irrelevant subclass constraint values are ignored.

For handling path objects to retrieve lists of potential values, see Webservice::InterMine::Path

INTERNAL METHODS

  • get_results_iterator($url, $view_list, $row_format, $json_format, $roles)

    Returns a results iterator that iterates over result rows in the requested format.

    Parameters:

    • $url: The path to the requested resource

    • $query_form: A hashref of query parameters

    • $view_list: an array-ref of view-paths

    • $row_format: the format for each parsed row

    • $json_format: how to handle json results

    • $roles: an optional array-ref of roles to apply

    Returns a Webservice::InterMine::ResultIterator

  • fetch($url)

    A simple data fetch method, for getting data as represented by a url and doing basic error checks on the response before returning the content. Used internally for obtaining several items of data from the service.

  • send_off($xml, $url)

    Send xml data to the webservice, checking the response for errors. This is used internally to save templates and queries.

AUTHOR

Alex Kalderimis dev@intermine.org

BUGS

Please report any bugs or feature requests to dev@intermine.org.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Webservice::InterMine::Service

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright 2006 - 2011 FlyMine, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.