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

Last change on this file since 4509 was 4509, checked in by Jari Häkkinen, 13 years ago

Addresses #1106. Missed to change reference wherefrom retrive GPLv3 license text. And some other changes.

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