Chapter 27. Web services

Table of Contents

27.1. Available services
27.1.1. Services
27.2. Client development
27.2.1. Receiving files
27.3. Services development
27.3.1. Generate WSDL-files
27.4. Example web service client (with download)

This chapter is an introduction of web services in BASE. It is recommended to begin your reading with the first section in this chapter and then you can move on to either the second section for more information how to develop client applications, or to the third section if you think there are some services missing and you want to know how to proceed to develop a new one.

[Important] Web services support has been deprecated in BASE 3.3

The current implementation is most likely not very useful and has limited support for accessing information in BASE. Therefore it has been decided to remove the web services support in BASE 3.4. If anyone require web services support or similar we recommend using the BASE extensions mechanism to implement exactly what is needed for that project and we also beleive that a simplier API such as JSON is preferable.

Before moving on to develop client applications or new services there are few things that need to be explained first.

  1. Items in BASE are not send directly by the web services, most of them are to complex for this should be possible. Instead is each item type represented by an info class that can hold the type's less complex properties.

  2. BASE offers a way for services to allow the client applications to put their own includes and restrictions on a query before it is executed. For those who intend to develop services it is recommended to have a look in javadoc for the QueryOptions class. This is on the first hand for the service developers but it can be useful for client developers to also know that this may be available in some services.

27.1. Available services

Web services can, at the moment, be used to provide some information and data related to experiments in BASE, for example, information about raw bioassays or bioassay set data. The subsection below gives an overview of the services that are currently present in BASE short description for each. More detailed information can be found in the javadoc and WSDL-files. Each service has it's own class and WSDL-file.

27.1.1. Services

SessionService, SessionClient

Provides methods to manage a sessions. This is the main entry point to the BASE web services. This contains methods for logging in and out and keeping the session alive to avoid automatic logout due to inactivity.

ProjectService, ProjectClient

Service related to projects. You can list available projects and select one to use as the active project.

ExperimentService, ExperimentClient

Service related to experiments. List your experiments and find out which raw bioassays that are part of it and which bioassay sets have been created as part of the analysis. Find reporter lists that are part of the experiment and get information about the experimental factors.

BioAssaySetService, BioAssaySetClient

Services related to bioassay sets. Get access data files that are attached to bioassay sets. Data from the database must first be exported and saved as a file. Find annotation values on bioassay sets.

RawBioAssayService, RawBioAssayClient

Services related to raw bioassays. Find out which raw data files that are present and download them. Find annotation values on raw bioassays.

ArrayDesignService, ArrayDesignClient

Services related to array design. Find out which data files that are present and download them. Find annotation values on array designs.

AnnotationTypeService, AnnotationTypeClient

Services related to annotation types. Find out which annotation types that can be used for different types of items.

ReporterService, ReporterClient

Services related to reporters and reporter lists. Get information about all admin-defined extended properties. Download reporter information for reporters.

FileService, FileClient

Services related to files. Download files.

27.2. Client development

How to develop client applications for the web services in BASE depends on which program language you are using. BASE comes with a simple client API for java for the existing services. If you use this API, you don't have to worry about WSDL files, stubs and skeletons and other web services related stuff. Just use it the client API as any other java API.

The client API can be downloaded with example code from the BASE plug-ins website. The package contains all external JAR files you need, the WSDL files (in case you still want them) and some example code that logs in to a BASE server, lists projects and experiments and then logs out again. Here is a short example of how to login to a BASE server, list the experiments and then logout.

String serviceUrl = "http://your.base.server/base2/services";
String login = "mylogin";
String password = "mypassword";

// Create new session
SessionClient session = new SessionClient(serviceUrl, null, null);

// Login
session.login(login, password, null);

// Get all projects and print out name and ID
ExperimentClient ex = new ExperimentClient(session);
ExperimentInfo[] experiments = ec.getExperiments(new QueryOptions());

if (experiments != null && experiments.length > 0)
{
   for (ExperimentInfo info : experiments)
   {
      System.out.println("name=" + info.getName() + "; id=" +info.getId());
   }
}

// Logout
session.logout();

If you want to use another language than Java or you don't want to use our client API, you probably need the WSDL files. These can be found in the client API package discussed above and also in the BASE core distribution in the <base-dir>/misc/wsdl directory. The WSDL files can also be generated on the fly by the BASE server by appending ?wsdl to the url for a specific service. For example, http://your.base.server/base2/services/Session?wsdl.

27.2.1. Receiving files

Some methods can be used to download files or exported data. Since this kind of data can be binary data the usual return methods can't be used. BASE uses a method commonly known as web services with attachments using MTOM (SOAP Message Transmission Optimization Mechanism) to send file data. Read the MTOM Guide from Apache if you want to know more about this.

With the client API it is relatively easy to download a file. Here is a short program example that downloads the CEL files for all raw bioassays in an experiment.

int experimentId = ...
SessionClient session = ...
String fileType = "affymetrix.cel";

// Create clients for experiment and raw bioassay
ExperimentClient ec = new ExperimentClient(session);
RawBioAssayClient rc = new RawBioAssayClient(session);

// Get all raw bioassays in the experiment
RawBioAssayInfo[] rawInfo = ec.getRawBioAssays(experimentId, new QueryOptions());
if (rawInfo == null && rawInfo.length == 0) return;

for (RawBioAssayInfo info : rawInfo)
{
   // We receive the file contents as an InputStream
   InputStream download = rc.downloadRawDataByType(info.getId(), fileType);
   
   // Save to file with the same name as the raw bioassay + .cel
   // assume that there are no duplicates
   File saveTo = new File(info.getName() + ".cel");
   FileUtil.copy(download, new FileOutputStream(saveTo));
}

If you are using another programming language than Java or doesn't want to use the client API you must know how to get access to the received file. The data is sent as a binary attachment to an element in the XML. It is in the interest of the client developer to know how to get access to a received file and to make sure that the programming language/web services framework that is used supports MTOM. Below is a listing which shows an example of a returned message from the RawBioAssayService.downloadRawDataByType() service.


--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:1526E5ADD9FC4431651195044149665@apache.org>

<ns:downloadRawDataByTypeResponse xmlns:ns="http://server.ws.basedb.sf.net">
  <ns:return>
    <Test.cel:Test.cel xmlns:Test.cel="127.0.0.1">
       <xop:Include href="cid:1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org" 
          xmlns:xop="http://www.w3.org/2004/08/xop/include" />
    </Test.cel:Test.cel>
  </ns:return>
</ns:downloadRawDataByTypeResponse>
--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
Content-Type: text/plain
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org>

... binary file data is here ...

Here is a programlisting, that shows how to pick up the file. This is the actual implementation that is used in the web service client that comes with BASE. The InputStream returned from this method is the same InputStream that is returned from, for example, the RawBioAssayClient.downloadRawDataByType() method.

// From AbstractRPCClient.java
protected InputStream invokeFileBlocking(String operation, Object... args)
   throws AxisFault, IOException
{
   //Get the original response element as sent from the server-side
   OMElement response = getService().invokeBlocking(getOperation(operation), args);

   //The file element returned from the service is the first element of the response
   OMElement fileElement = response.getFirstElement();
   
   //The data node always in the first element.
   OMElement dataElement = fileElement.getFirstElement();	
   if (dataElement == null) return null;
   
   //Get the binary node and pick up the inputstream.
   OMText node = (OMText)dataElement.getFirstOMChild();
   node.setBinary(true);
   DataHandler dataHandler = (DataHandler)node.getDataHandler();		
   return dataHandler.getInputStream();
}

27.3. Services development

This list should work as guide when creating new web service in BASE.

  1. Create a new class that extends AbstractRPCService

  2. Place the new service in same package as the abstract class, net.sf.basedb.ws.server

  3. Write the routines/methods the service should deploy.

    [Warning] Never return void from methods

    For server-side exceptions to be propagated to the client the web services method mustn't be declared as void. We suggest that in cases where there is no natural return value, the session ID is returned, for example:

    public String myMethod(String ID, ...more parameters...)
    {
      // ... your code here
      return ID;
    }
    
  4. Make the Ant build-file creates a WSDL-file when the services are compiled (see below). This step is not needed for BASE to work but may be appreciated by client application developers.

  5. Register the service in the <base-dir>/src/webservices/server/META-INF/services.xml file. This is an XML file listing all services and is needed for BASE (Axis) to pick up the new service and expose it to the outside world. Below is an example of hoe the Session service is registered.

    Example 27.1.  How to register a service in services.xml

    
    <service name="Session" scope="application">  
       <description>  
          This service handles BASE sessions (including login/logout)  
       </description>  
       <messageReceivers>  
          <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"   
             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />  
          <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"   
             class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />  
       </messageReceivers>  
       <parameter name="ServiceClass" 
          locked="false">net.sf.basedb.ws.server.SessionService</parameter>  
    </service>  
    
    


27.3.1. Generate WSDL-files

When a new service is created it can be a good idea to also get a WSDL-file generated when the web services are compiled. The WSDL-file will be a help for those developers who intend to create client applications to the new service. It is a one-liner in the Ant build file to do this and not very complicated. To create a WSDL file for the new web service add a line like the one below to the webservices.wsdl target. Replace SessionService with the name of the new service class.

<webservices.wsdl serviceClassName="SessionService"/>

27.4. Example web service client (with download)

We have created a simple Java client that uses web services to get information about projects and experiments from a BASE server. The example code can also download raw data files attached to an experiment. The example code can be used as a starting point for developers wanting to do their own client. You can download a tar file with the source and compiled code from the BASE plug-ins website.