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

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

Fixes #809: Read Web services documentation

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