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

NAME

Webservice::InterMine - modules for interacting with InterMine datawarehouse webservices

SYNOPSIS

  use Webservice::InterMine;

  my $service  = Webservice::InterMine->new_service($url, $user, $pass);
  my $template = $service->template($name);
  my $results  = $template->results_with(valueA => 'x', valueB => 'y');

OR

  use Webservice::InterMine 'flymine', 'SOMETOKEN';

  my $query    = Webservice::InterMine->new_query(class => 'Gene');
  my $results  = $query->select('symbol', 'primaryIdentifier', 'pathways.*')
                       ->where(symbol => [qw/H bib eve zen/])
                       ->all();

DESCRIPTION

This distribution is the client interface to any implementation of the InterMine Datawarehousing WebService (www.intermine.org). Primarily used for biological genomic databases, the webservice allows the user to easily write and execute structured queries.

This module allows you to interact with one or more webservices by providing a url to an InterMine implementation.

INSTALLATION AND DEPENDENCIES

This package can be installed using the following commands (Module::Build >= 0.36 is required):

perl Build.PL
./Build test
sudo ./Build install

If any runtime dependencies are missing, you can use the following command to install them:

sudo ./Build installdeps

IMPORT STATEMENTS

You must import the module with "use" to utilise its functionality. Additional parameters can be supplied at import to specify a default service.

Simply import the module:

use Webservice::InterMine;

Import the module, and specify the default service as FlyMine (the url will be looked up at the central mine registry http://www.intermine.org/registry.

use Webservice::InterMine 'flymine';

The same, only with the full url, eliminating the need for an extra lookup:

use Webservice::InterMine 'www.flymine.org/query';

The same, but with authentication supplied by an API access token:

use Webservice::InterMine 'flymine', 'SOMETOKEN';

The same, but with authentication supplied username and password credentials: (deprecated)

use Webservice::InterMine 'flymine', 'username', 'password';

The same, with explicit, named parameters:

  use Webservice::InterMine root => 'flymine', user => 'username', pass => 'password';

Calling use Webservice::InterMine without any parameters simply means you need to either specify the webservice url on every call, or call the methods on a service directly.

If you pass parameters to import, a default service will be set meaning method calls will not require the webservice url. Unless you are intending to access multiple services, this form is recommended.

METHODS

new_query( [from => \@service_args], [%query_args] )

returns a new query object for you to fill in with constraints before being run to get its results.

Parameters:

  • from => [url, user, pass]

    An array ref of arguments to pass to get_service. This information can be used to specify a different service than the one named on import, or to specify one when none was named on import.

  • %query_args

    Key value pairs of arguments to pass to the query constructor in Webservice::InterMine::Service. This methid serves as sugar for the factory method in that class.

Please see Webservice::InterMine::Query, Webservice::InterMine::Service.

new_list( %list_args, [from => \@service_args] )

Creates a new list with the content specified by the list arguments. The content key-word parameter will always be required. For a full specification of creating lists, see: Webservice::InterMine::Service.

Parameters:

  • from => [url, user, pass]

    An array ref of arguments to pass to get_service. This information can be used to specify a different service than the one named on import, or to specify one when none was named on import.

  • %list_args

    Key value pairs of arguments to pass to the list constructor in Webservice::InterMine::Service. This methid serves as sugar for the factory method in that class.

get_list( $list_name, [from => \@service_args] )

Get the list of the given name from the default service, or the given service if details are supplied.

load_query([\@service_args], source_file|source_string => $source, %opts )

Returns a query object based on xml you have previously saved, either as a string or as a file. For a file pass:

load_query(source_file => $file);

For a string:

load_query(source_string => $string);

If you want a specific service, call it thus:

load_query(from => [$name, $user, $pass], source_string => $string);

OR:

load_query(from => [$name, $user, $pass], source_string => $string);

Please see Webservice::InterMine::Query::Saved

template( $name, [from => \@service_args], [%opts] )

returns the named template (if it exists - if not it returns undef). If you pass a url, it returns the named template from the specified webservice.

Please see Webservice::InterMine::Query::Template

saved_query( $name, [from => \@service_args], %options ) NOT IMPLEMENTED YET

returns the named saved_query (if it exists - if not it returns undef). If you pass a url, it returns the named query from the specified webservice.

This method requires you to have provided a username and password to the webservice for authentication.

Please see Webservice::InterMine::Query::Saved

get_service( $root, ($token | $user, $pass) )

returns a webservice object, which is used to construct queries and fetch templates and saved queries. If a url is passed, the webservice for that url is returned, otherwise the service for the url given to use is returned.

Get the default service defined at import:

use Webservice::InterMine qw(http://www.intermine.org/intermine-demo SOMETOKEN);

my $service =  InterMine::Webservice->get_service;

OR get a specific service, authenticated using an API access token:

my $service = InterMine::Webservice->get_service($url, $token);

Fetch that same authenticated service later:

my $service = InterMine::Webservice->get_service($url);

OR make the same call using a hash reference and named parameters:

my $service = InterMine::Webservice->get_service({ 
  root => $url, token => $token
});

Parameters:

  • $root - The base url for the service.

  • $token - An API access key

  • $username, $password - A user's login credentials

InterMine webservices support two authentication mechanisms to provide access to private data. The recommended method is to use API access keys, which have the advantage of eliminating the need to transmit your login details. If compromised, an access key can be easily changed or disabled without needing to change either the associated username or password. However this facility is new, so for backwards compatibility, the older mechanism for passing along username and password credentials has been retained.

If three arguments are supplied, they will be interpreted as ($root, $user, $pass), but if two are supplied, they will be intepreted as ($root, $token).

These arguments may also be passed in a keyword/hash style, either as a list or a hash reference, in which case the full list will be passed to the Webservice::InterMine::Service::new constructor.

If a service for a url has been created previously, that one is returned, even if different login details are provided.

Please see: Webservice::InterMine::Service

clean_temp_lists()

Deletes all automatically created anonymous lists. Any renamed lists will be spared the clean-up. This method is called on system exit, unless the variable $Webservice::InterMine::CLEAN_UP is set to a false value.

get_{minename}(user, pass)

An unknown method preceded with 'get_' will be interpreted as a mine name, and an attempt will be made to return a service with that name.

SEE ALSO

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

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.