source: trunk/doc/src/docbook/developerdoc/webservices.xml @ 3977

Last change on this file since 3977 was 3977, checked in by Nicklas Nordborg, 15 years ago

References #827: Add more web services methods

Added AnnotationTypeService? that can be used to find available annotation types.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 15.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: webservices.xml 3977 2007-11-16 10:59:48Z nicklas $
7 
8  Copyright (C) 2007 Martin Svensson
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="webservices">
30  <?dbhtml dir="webservices"?>
31  <title>Web services</title>
32  <para>
33    This chapter is an introduction of web services in BASE. It is recommended to begin your
34    reading with the first section in this chapter and then you can move on to either the second
35    section for more information how to develop client applications, or to the third section if
36    you think there are some services missing and you want to know how to proceed to develop a
37    new one.
38  </para>
39
40  <para>
41    Before moving on to develop client applications or new services there are few things that
42    need to be explained first.
43    <orderedlist>
44      <listitem>
45        <para>
46          Items in Base are not send directly by the web services, most of them are to
47          complex for this should be possible. Instead is each item type represented by
48          an info class that can hold the type's less complex properties.
49        </para>
50      </listitem>
51      <listitem>
52        <para>
53          BASE offers a way for services to allow the client applications to put their own
54          includes and restrictions on a query before it is executed. For those who intend
55          to develop services it is recommended to have a look in javadoc for the
56          <classname docapi="net.sf.basedb.info">QueryOptions</classname> class.
57          This is on the first hand for the service developers but it can be useful for
58          client developers to also know that this may be available in some services.
59        </para>
60      </listitem>
61    </orderedlist>
62  </para>
63
64  <sect1 id="webservices.available_services">
65    <title>Available services</title>
66    <para>
67      Web services can, at the moment, be used to provide some information and data related to
68      experiments in BASE, for exampl, information about raw bioassays or bioassay set data.
69      The subsection below gives an overview of the services that are currently present in
70      BASE short description for each. More detailed information
71      can be found in the javadoc and WSDL-files. Each service has it's own class and WSDL-file.
72    </para>
73
74    <sect2 id="webservices.available_services.services">
75      <title>Services</title>
76      <variablelist>
77        <varlistentry>
78          <term><classname docapi="net.sf.basedb.ws.server">SessionService</classname></term>
79          <term><classname docapi="net.sf.basedb.ws.client">SessionClient</classname></term>
80          <listitem>
81            <para>
82              Provides methods to manage a sessions. This is the main entry point
83              to the BASE web services. This contains methods for logging in and out
84              and keeping the session alive to avoid automatic logout due
85              to inactivity.
86            </para>
87          </listitem>
88        </varlistentry>
89
90        <varlistentry>
91          <term><classname docapi="net.sf.basedb.ws.server">ProjectService</classname></term>         
92          <term><classname docapi="net.sf.basedb.ws.client">ProjectClient</classname></term>
93          <listitem>
94            <para>
95              Service related to projects. You can list available projects
96              and select one to use as the active project.
97            </para>
98          </listitem>
99        </varlistentry>
100       
101        <varlistentry>
102          <term><classname docapi="net.sf.basedb.ws.server">ExperimentService</classname></term>
103          <term><classname docapi="net.sf.basedb.ws.client">ExperimentClient</classname></term>
104          <listitem>
105            <para>
106              Service related to experiments. List your experiments and
107              find out which raw bioassays that are part of it and
108              which bioassay sets have been created as part of the analysis.
109            </para>
110          </listitem>
111        </varlistentry>
112       
113        <varlistentry>
114          <term><classname docapi="net.sf.basedb.ws.server">BioAssaySetService</classname></term>
115          <term><classname docapi="net.sf.basedb.ws.client">BioAssaySetClient</classname></term>
116          <listitem>
117            <para>
118              Services related to bioassay sets. Get access to the data in a bioassay
119              set by exporting it to a file. Supported foramts are those provided
120              by the <classname docapi="net.sf.basedb.plugins">BioAssaySetExporter</classname>
121              plug-in.
122            </para>
123          </listitem>
124        </varlistentry>
125
126        <varlistentry>
127          <term><classname docapi="net.sf.basedb.ws.server">RawBioAssayService</classname></term>
128          <term><classname docapi="net.sf.basedb.ws.client">RawBioAssayClient</classname></term>
129          <listitem>
130            <para>
131              Services related to raw bioassays. Find out which raw data files that
132              are present and download them.
133            </para>
134          </listitem>
135        </varlistentry>
136       
137        <varlistentry>
138          <term><classname docapi="net.sf.basedb.ws.server">ArrayDesignService</classname></term>
139          <term><classname docapi="net.sf.basedb.ws.client">ArrayDesignClient</classname></term>
140          <listitem>
141            <para>
142              Services related to array design. Find out which data files that
143              are present and download them.
144            </para>
145          </listitem>
146        </varlistentry>
147       
148        <varlistentry>
149          <term><classname docapi="net.sf.basedb.ws.server">AnnotationTypeService</classname></term>
150          <term><classname docapi="net.sf.basedb.ws.client">AnnotationTypeClient</classname></term>
151          <listitem>
152            <para>
153              Services related to annotation types. Find out which annotation types that
154              can be used for different types of items.
155            </para>
156          </listitem>
157        </varlistentry>
158       
159      </variablelist>
160    </sect2>
161  </sect1>
162
163  <sect1 id="webservices.client_development">
164    <title>Client development</title>
165    <para>
166      How to develop client applications for the web services in Base is, of course, depends
167      on which program language you are using. Base comes with a simple client API for java
168      for the existing services. If you use this API, you don't have to worry about WSDL
169      files, stubs and skeletons and other web services related stuff. Just use it
170      the client API as any other java API.
171    </para>
172   
173    <para>
174      The client API can be downloaded with example code from the
175      <ulink url="http://base.thep.lu.se/wiki/DeveloperInformation">BASE developer
176      website</ulink>. The package contains all external JAR files you need, the
177      WSDL files (in case you still want them) and some example code that
178      logs in to a BASE server, lists projects and experiments and then logs out
179      again. Here is a short example of how to login to a BASE server, list
180      the experiments and then logout.
181    </para>
182   
183    <programlisting language="java">
184String serviceUrl = "http://your.base.server/base2/services";
185String login = "mylogin";
186String password = "mypassword";
187
188// Create new session
189SessionClient session = new SessionClient(serviceUrl, null, null);
190
191// Login
192session.login(login, password, null, false);
193
194// Get all projects and print out name and ID
195ExperimentClient ex = new ExperimentClient(session);
196ExperimentInfo[] experiments = ec.getExperiments(new QueryOptions());
197
198if (experiments != null &amp;&amp; experiments.length > 0)
199{
200   for (ExperimentInfo info : experiments)
201   {
202      System.out.println("name=" + info.getName() + "; id=" +info.getId());
203   }
204}
205
206// Logout
207session.logout();
208</programlisting>
209   
210    <para>
211      If you want to use another language than Java or you don't want to
212      use our client API, you probably need the WSDL files. These can be found
213      in the client API package discussed above and also in the BASE core
214      distribution in the <filename>&lt;base-dir&gt;/misc/wsdl</filename>
215      directory. The WSDL files can also be generated on the fly by the BASE server
216      by appending <constant>?wsdl</constant> to the url for a specific service.
217      For example, <constant>http://your.base.server/base2/services/Session?wsdl</constant>.
218    </para>
219
220    <sect2 id="webservices.client_development.receivingfiles">
221      <title>Receiving files</title>
222      <para>
223        Some methods can be used to download files or exported data. Since this
224        kind of data can be binary data the usual return methods can't be used.
225        Base uses a method commonly known as <emphasis>web services with attachments</emphasis>
226        using MTOM (SOAP Message Transmission Optimization Mechanism) to send file data.
227        Read the <ulink url="http://ws.apache.org/axis2/1_0/mtom-guide.html">MTOM Guide</ulink>
228        from Apache if you want to know more about this.
229      </para>
230     
231      <para>
232        With the client API it is relatively easy to download a file. Here is a short
233        program example that downloads the CEL files for all raw bioassays in an
234        experiment.
235      </para>
236     
237      <programlisting language="java">
238int experimentId = ...
239SessionClient session = ...
240String fileType = "affymetrix.cel";
241
242// Create clients for experiment and raw bioassay
243ExperimentClient ec = new ExperimentClient(session);
244RawBioAssayClient rc = new RawBioAssayClient(session);
245
246// Get all raw bioassays in the experiment
247RawBioAssayInfo[] rawInfo = ec.getRawBioAssays(experimentId, new QueryOptions());
248if (rawInfo == null &amp;&amp; rawInfo.length == 0) return;
249
250for (RawBioAssayInfo info : rawInfo)
251{
252   // We receive the file contents as an InputStream
253   InputStream download = rc.downloadRawDataByType(info.getId(), fileType);
254   
255   // Save to file with the same name as the raw bioassay + .cel
256   // assume that there are no duplicates
257   File saveTo = new File(info.getName() + ".cel");
258   FileUtil.copy(download, new FileOutputStream(saveTo));
259}
260</programlisting>
261
262        <para>
263          If you are using another programming language than Java or doesn't
264          want to use the client API you must know how to get access to the
265          received file. The data is sent as a binary attachment to an element in the
266          XML. It is in the interest of the client developer to know how to get access
267          to a received file and to make sure that the programming language/web services
268          framework that is used supports MTOM. Below is a listing which shows an
269          example of a returned message from the
270          <methodname>RawBioAssayService.downloadRawDataByType()</methodname>
271          service.
272        </para>
273       
274        <programlisting>
275<![CDATA[
276--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
277Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
278Content-Transfer-Encoding: binary
279Content-ID: <0.urn:uuid:1526E5ADD9FC4431651195044149665@apache.org>
280
281<ns:downloadRawDataByTypeResponse xmlns:ns="http://server.ws.basedb.sf.net">
282  <ns:return>
283    <Test.cel:Test.cel xmlns:Test.cel="127.0.0.1">
284       <xop:Include href="cid:1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org"
285          xmlns:xop="http://www.w3.org/2004/08/xop/include" />
286    </Test.cel:Test.cel>
287  </ns:return>
288</ns:downloadRawDataByTypeResponse>
289--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
290Content-Type: text/plain
291Content-Transfer-Encoding: binary
292Content-ID: <1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org>
293
294... binary file data is here ...
295]]>
296</programlisting>
297       
298        <para>
299          Here is a programlisting, that shows how to pick up the file.
300          This is the actual implementation that is used in the
301          web service client that comes with BASE. The <classname>InputStream</classname>
302          returned from this method is the same <classname>InputStream</classname>
303          that is returned from, for example, the <methodname>RawBioAssayClient.downloadRawDataByType()</methodname>
304          method.
305        </para>
306       
307        <programlisting language="java">
308// From AbstractRPCClient.java
309protected InputStream invokeFileBlocking(String operation, Object... args)
310   throws AxisFault, IOException
311{
312   //Get the original response element as sent from the server-side
313   OMElement response = getService().invokeBlocking(getOperation(operation), args);
314
315   //The file element returned from the service is the first element of the response
316   OMElement fileElement = response.getFirstElement();
317   
318   //The data node always in the first element.
319   OMElement dataElement = fileElement.getFirstElement();
320   if (dataElement == null) return null;
321   
322   //Get the binary node and pick up the inputstream.
323   OMText node = (OMText)dataElement.getFirstOMChild();
324   node.setBinary(true);
325   DataHandler dataHandler = (DataHandler)node.getDataHandler();   
326   return dataHandler.getInputStream();
327}
328</programlisting>
329
330    </sect2>
331  </sect1>
332
333  <sect1 id="webservices.services_development">
334    <title>Services development</title>   
335    <para>
336      This list should work as guide when creating new web service in base.
337      <orderedlist>
338        <listitem>
339          <para>
340            Create a new class that extends
341            <classname api="net.sf.basedb.ws.server">AbstractRPCService</classname>
342          </para>
343        </listitem>
344        <listitem>
345          <para>
346            Place the new service in same package as the abstract class,
347            <classname>net.sf.basedb.ws.server</classname>
348          </para>
349        </listitem>
350        <listitem>
351          <para>Write the routines/methods the service should deploy.</para>
352        </listitem>
353        <listitem>
354          <para>
355            Make the Ant build-file creates a WSDL-file when the services are
356            compiled (see below). This step is not needed for BASE to work
357            but may be appreciated by client application developers.
358          </para>
359        </listitem>
360        <listitem>
361          <para>
362            Register the service in the
363            <filename>&lt;base-dir&gt;/src/webservices/server/META-INF/services.xml</filename> 
364            file. This is an XML file listing all services and is needed
365            for BASE (Axis) to pick up the new service and expose it to the
366            outside world. Below is an example of hoe the <classname>Session</classname>
367            service is registered.
368           
369             <example id="webservices.examples.register_service">
370              <title>
371                How to register a service in
372                <filename>services.xml</filename>
373              </title>
374              <programlisting language="xml">
375<![CDATA[
376<service name="Session" scope="application"> 
377   <description> 
378      This service handles BASE sessions (including login/logout) 
379   </description> 
380   <messageReceivers> 
381      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"   
382         class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" /> 
383      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"   
384         class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" /> 
385   </messageReceivers> 
386   <parameter name="ServiceClass"
387      locked="false">net.sf.basedb.ws.server.SessionService</parameter> 
388</service> 
389]]>
390</programlisting>
391            </example>
392          </para>
393        </listitem>
394      </orderedlist>
395    </para>
396    <sect2 id="webservices.services_development.generate_wsdl">
397      <title>Generate WSDL-files</title>
398      <para>
399        When a new service is created it can be a good idea to also get a WSDL-file
400        generated when the web services are compiled. The WSDL-file will be a help for those
401        developers who intend to create client applications to the new service. It is a
402        one-liner in the Ant build file to do this and not very complicated.
403        To create a WSDL file for the new web service add a line like the one
404        below to the <constant>webservices.wsdl</constant> target. Replace
405        <replaceable>SessionService</replaceable> with the name of the new service class.
406      </para>
407
408<programlisting language="xml">
409&lt;webservices.wsdl serviceClassName="SessionService"/&gt;
410</programlisting>
411
412    </sect2>
413  </sect1>
414</chapter>
Note: See TracBrowser for help on using the repository browser.