The InterMine SOAP web service

This document describes how to install and use the InterMine web service, which allow queries to a remote database. This may be a central data store, in which case it is not necessary to install a local server. At present both server and client usage require the InterMine source distribution.

The web service has a client/server architecture. Network access is transparent to the user, and queries are performed in the same way as in any other ObjectStore?. It consists of two components: the server and the client, which are configured and run independently. Communication is performed using SOAP over HTTP which should allow connection even if the client is behind a firewall. A server must be installed or located before the client can be used.

Client usage

Usage if the client requires:

• a Java runtime
• the InterMine webservice-client.jar, and a jar for model against which you wish to query
• knowledge of the URL of a server

The client is just an ObjectStore? implementation, and is configured using properties in similar way to any other ObjectStore?. The relevant implementation class is specified in addition to the server URL (which is analogous to the database alias specified for an ObjectStore? backed by a relational store.)

Suitable intermine.properties could be:

            os.default = os.ws-client
            
            os.ws-client.class=org.intermine.objectstore.webservice.ObjectStoreClient
            os.ws-client.model=testmodel
            os.ws-client.url=http://localhost:8080/webservice/services/ObjectStore
            
            os.query.max-time=1000000000
            os.query.max-limit=10000
            os.query.max-offset=10000
            os.queue-len=100

Assuming these properties are accessible, and that the required jars are on the CLASSPATH, a suitable test is to run java org.intermine.objectstore.query.iql.IqlShell?, which should allow you to interactively run queries against the remote database.

Server installation

The server provides a remote interface to an underlying ObjectStore? specified using the os.default property in intermine.properties. This ObjectStore?, which may use a database, should be configured and tested separately.

The server is implemented using the Apache Axis engine, and runs as a web application in a suitable servlet container. The InterMine ant build script will package the web service as a web archive (.war) file suitable for deployment in containers that implement at least version 2.2 of the Servlet specification. This archive, built using the build-webservice target, includes all dependencies and does not require Axis to be installed separately.

If you are using the Apache Tomcat container the build script can additionally deploy the web application using the release-webservice target. This requires configuration information such as the target host and port, along a username and password for a user with "manager" privileges and a deployment path. The URL that is subsequently used to access the service is derived from this path. Deployment is dynamic: it requires Tomcat to be running and does not require it to be immediately restarted.

The following build.properties.intermine should be sufficient:

            webservice.baseurl=http://localhost:8080
            webservice.path=/webservice
            webservice.manager=manager
            webservice.password=manager