Table of Contents
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.
![]() |
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.
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.
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.
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.
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.
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
.
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(); }
This list should work as guide when creating new web service in BASE.
Place the new service in same package as the abstract class,
net.sf.basedb.ws.server
Write the routines/methods the service should deploy.
![]() |
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; } |
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.
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>
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"/>
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.