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

Last change on this file since 4932 was 4932, checked in by Nicklas Nordborg, 13 years ago

References #742: Refactor BioAssaySetExporter?

Removed references in the documentation to BioAssaySetExporter?.

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