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

Last change on this file since 3907 was 3907, checked in by Martin Svensson, 14 years ago

References #809. Smaller adjustments.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 17.3 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 3907 2007-11-05 13:58:33Z martin $
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 procced 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          complexed for this to be possible. Instead is each item type represented by an info class
48          that can hold it's less complex properties. More
49          complex properties need to be exported to a file before they can be send by the
50          web services as an attachment.
51        </para>
52      </listitem>
53      <listitem>
54        <para>
55          Base offers a way for services to allow the client applications to put their own
56          includes and restrictions on a query before it is executed.
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, like information about raw bioassays or exported bioassay set. This
67      section lists all the available services in Base and gives a short description of what each
68      one can be used to.
69    </para>
70
71    <sect2 id="webservices.available_services.services">
72      <title>Services</title>
73      <variablelist>
74        <varlistentry>
75          <term>SessionService</term>
76          <listitem>
77            <para>Provides methods to manage a session in Base.</para>
78            <variablelist>
79              <varlistentry>
80                <term>
81                  <function>newSession</function>
82                </term>
83                <listitem>
84                  <para>
85                    Creates a new session and returns it's id. Before a session can
86                    be used you have to login with it, see below.
87                  </para>
88                  <important>
89                    <para>
90                      The id should be send along each time a client invokes a
91                      service otherwise it is not possible for the service to get
92                      access to Base.
93                    </para>
94                  </important>
95                </listitem>
96              </varlistentry>
97              <varlistentry>
98                <term>
99                  <function>login</function>
100                </term>
101                <listitem>
102                  <para>
103                    Login and activate a session. A registered user's login and
104                    password has to be used.
105                  </para>
106                </listitem>
107              </varlistentry>
108              <varlistentry>
109                <term>
110                  <function>logout</function>
111                </term>
112                <listitem>
113                  <para>
114                    Logout and stop an active session in Base.
115                  </para>
116                </listitem>
117              </varlistentry>
118              <varlistentry>
119                <term>
120                  <function>getChallenge</function>
121                </term>
122                <listitem>
123                  <para>
124                    Returns a random string to be used for password encryption.
125                  </para>
126                </listitem>
127              </varlistentry>
128              <varlistentry>
129                <term>
130                  <function>getSessionTimeOut</function>
131                </term>
132                <listitem>
133                  <para>
134                    Gives how many minutes of inactivity before a
135                    session do a timeout and automatically logout.
136                  </para>
137                </listitem>
138              </varlistentry>
139              <varlistentry>
140                <term>
141                  <function>refreshSession</function>
142                </term>
143                <listitem>
144                  <para>
145                    Reset the time of inactivity. Can be used to keep a session
146                    alive.
147                  </para>
148                </listitem>
149              </varlistentry>
150            </variablelist>
151          </listitem>
152        </varlistentry>
153
154        <varlistentry>
155          <term>ProjectService</term>         
156          <listitem>
157            <para>Service related to project</para>
158            <variablelist>
159              <varlistentry>
160                <term>
161                  <function>setActiveProject</function>
162                </term>
163                <listitem>
164                  <para>
165                    Sets a project to be active. This will be the same as when a
166                    project is set to be active in the web client, see
167                    <xref linkend="project_permission.projects.active" />
168                    .
169                  </para>
170                </listitem>
171              </varlistentry>
172              <varlistentry>
173                <term>
174                  <function>getProjects</function>
175                </term>
176                <listitem>
177                  <para>
178                    Gets information about each project the active session has
179                    permission to read.
180                  </para>
181                </listitem>
182              </varlistentry>
183            </variablelist>
184          </listitem>
185        </varlistentry>
186        <varlistentry>
187          <term>ExperimentService</term>
188          <listitem>
189            <para>
190              Different kinds of methods regarding experiments and items in an
191              experiment.
192            </para>
193            <variablelist>
194              <varlistentry>
195                <term>
196                  <function>getExperiments</function>
197                </term>
198                <listitem>
199                  <para>
200                    Information about each experiment an active session has
201                    permission to read.
202                  </para>
203                </listitem>
204              </varlistentry>
205              <varlistentry>
206                <term>
207                  <function>getBioAssaySets</function>
208                </term>
209                <listitem>
210                  <para>
211                    Returns information about bioassay sets in an experiment.
212                  </para>
213                </listitem>
214              </varlistentry>
215              <varlistentry>
216                <term>
217                  <function>getRawBioAssays</function>
218                </term>
219                <listitem>
220                  <para>
221                    Returns information about the raw bioassays used in an
222                    experiment.
223                  </para>
224                </listitem>
225              </varlistentry>
226            </variablelist>
227          </listitem>
228        </varlistentry>
229        <varlistentry>
230          <term>BioAssaySetService</term>
231          <listitem>
232            <para>Services related to bioassay sets.</para>
233            <variablelist>
234              <varlistentry>
235                <term>
236                  <function>getExportFormats</function>
237                </term>
238                <listitem>
239                  <para>
240                    Returns the name of the file formats a bioassay set can be
241                    exported in. Available formats are the ones provided by the
242                    BioAssaySetExporter-plugin.
243                  </para>
244                </listitem>
245              </varlistentry>
246            </variablelist>
247            <variablelist>
248              <varlistentry>
249                <term>
250                  <function>downloadBioAssaySet</function>
251                </term>
252                <listitem>
253                  <para>
254                    Returns an
255                    <classname>org.apache.axiom.om.OMElement</classname>
256                    object with a file attached. The file contains a bioassayset
257                    exported by the BioAssaySetExporter in a specific format . The
258                    format parameter must be identical to one of the strings
259                    returned by
260                    <function>getExportFormats</function>
261                    . How to get access to the received file is described in
262                    section,
263                    <xref linkend="webservices.client_development" />
264                  </para>
265                </listitem>
266              </varlistentry>
267            </variablelist>
268          </listitem>
269        </varlistentry>
270        <varlistentry>
271          <term>RawBioAssayService</term>
272          <listitem>
273            <para>
274              Methods related to raw bioassays and exporting data from a raw bioassay.
275              In most cases you need to know the id of a raw bioassay to be able to
276              use one of these methods.
277            </para>
278            <variablelist>
279              <varlistentry>
280                <term>
281                  <function>getArrayDesign</function>
282                </term>
283                <listitem>
284                  <para>
285                    Returns information about the array design used
286                    by a raw bioassay.
287                  </para>
288                </listitem>
289              </varlistentry>
290              <varlistentry>
291                <term>
292                  <function>downloadRawDataByType</function>
293                </term>
294                <listitem>
295                  <para>
296                    Returns a
297                    <classname>org.apache.axiom.om.OMElement</classname>
298                    . Raw data file will be attached to this element if the raw
299                    bioassay using file storage in Base.
300                  </para>
301                </listitem>
302              </varlistentry>
303              <varlistentry>
304                <term>
305                  <function>hasDownloadableData</function>
306                </term>
307                <listitem>
308                  <para>
309                    This method should be used before calling any of
310                    <function>downloadRawDataByType</function>
311                    or
312                    <function>getDataFileTypes</function>
313                    above. It shows if there are any data file in a raw bioassay
314                    to download or not.
315                  </para>
316                </listitem>
317              </varlistentry>
318              <varlistentry>
319                <term>
320                  <function>getDataFileTypes</function>
321                </term>
322                <listitem>
323                  <para>
324                    Shows information about the data file types, for a raw
325                    bioassay, that can be downloaded.
326                  </para>
327                </listitem>
328              </varlistentry>
329            </variablelist>
330          </listitem>
331        </varlistentry>
332        <varlistentry>
333          <term>ArrayDesignService</term>
334          <listitem>
335            <para>Service for array designs and data in array designs.</para>
336            <variablelist>
337              <varlistentry>
338                <term>
339                  <function>getDataFileTypes</function>
340                </term>
341                <listitem>
342                  <para>
343                    Gets information about the data file types used to store an
344                    array design in files.
345                  </para>
346                </listitem>
347              </varlistentry>
348              <varlistentry>
349                <term>
350                  <function>hasDownloadableData</function>
351                </term>
352                <listitem>
353                  <para>
354                    Indicates if an array design is saved as a file or not.
355                    Useful before calling any of the other method.
356                  </para>
357                </listitem>
358              </varlistentry>
359              <varlistentry>
360                <term>
361                  <function>downloadArrayDesignByType</function>
362                </term>
363                <listitem>
364                  <para>
365                    Gets an array design file of a certain type. Only array
366                    designs using file storage in Base can be used with this
367                    method. For other array designs this method will return an
368                    empty element.
369                  </para>
370                </listitem>
371              </varlistentry>
372            </variablelist>
373          </listitem>
374        </varlistentry>
375      </variablelist>
376    </sect2>
377  </sect1>
378
379  <sect1 id="webservices.client_development">
380    <title>Client development</title>
381    <para>
382      How to develop client applications for the web services in Base is, of course, depending
383      alot on which program language you are using. Base comes with clients written in java for the
384      existing services and these clients can either be used as examples of how clients should
385      implement the services or used as real client applications. 
386    </para>
387   
388    <para>
389      There are WSDL-files available in the Base distribution for each service class, as a
390      help for the developer of web service clients. The files are located in
391      <filename class="directory">
392        <replaceable>BASE_HOME</replaceable>
393        /misc/wsdl/
394      </filename>
395      . Each WSDL-file has the same name as the service it corresponds to.
396    </para>
397
398    <sect2 id="webservices.client_development.receivingfiles">
399      <title>Receiving files</title>
400      <para>
401        Files are not send by the web services like ie. strings and integers are. Instead a
402        file is send as a binary attachment to an element in the XML. It is in the interest
403        of the client developer to know how to get access to a received file. Below are
404        therefore both a list showing which level a file is located and
405        programlisting that shows how it is implemented in the java-clients that come with
406        Base.
407        <itemizedlist mark="none">
408          <listitem>
409            <sgmltag class="starttag">MessageElement</sgmltag>
410            <itemizedlist mark="none">
411              <listitem>
412                <sgmltag class="starttag">FileElement</sgmltag>
413                <itemizedlist mark="none">
414                  <listitem>
415                    <sgmltag class="starttag">BinaryNode</sgmltag>
416                  </listitem>
417                </itemizedlist>
418              </listitem>
419            </itemizedlist>
420          </listitem>
421        </itemizedlist>
422        The file is attached to the last node and can be accessed by picking up the
423        inputstream, see example below. Here is a programlisting, that shows how it is done
424        in the web service clients that comes with Base.
425<programlisting language="java">
426protected File invokeFileBlocking(String operation, String fileName, Object... args)
427    throws AxisFault, IOException
428  {
429    //Creates a file to write the inputstream to.
430    File receivedFile = new File(fileName);
431   
432    //Get the whole response element send from the server-side
433    OMElement response = getService().invokeBlocking(getOperation(operation), args);
434   
435    //The element returned from the service is the first element of the response
436    OMElement fileElement = response.getFirstElement();
437   
438    //File node allways in the first element.
439    OMElement dataElement = fileElement.getFirstElement(); 
440    if (dataElement == null) return null;
441   
442    //Get the binary node and pick up the inputstream.
443    OMText node = (OMText) dataElement.getFirstOMChild();
444    node.setBinary(true);
445    DataHandler dataHandler = (DataHandler) node.getDataHandler();   
446    InputStream in = dataHandler.getInputStream();
447   
448    //Write the inputstream to the files outputstream
449    FileOutputStream out = new FileOutputStream(receivedFile);
450    byte[] buffer = new byte[512];
451    int bytes = 0;
452    long totalBytes = 0;
453    while (bytes != -1)
454    {
455      bytes = in.read(buffer, 0, buffer.length);
456      if (bytes > 0)
457      {
458        totalBytes += bytes;
459        out.write(buffer, 0, bytes);
460      }
461    }
462    //The file is now received
463    return receivedFile;
464  }
465</programlisting>
466      </para>
467    </sect2>
468  </sect1>
469
470  <sect1 id="webservices.services_development">
471    <title>Services development</title>   
472    <para>
473      This list should work as guide when creating new web service in base.
474      <orderedlist>
475        <listitem>
476          <para>
477            Create a new class that extends
478            <classname>net.sf.basedb.ws.server.AbstractRPCService</classname>
479          </para>
480        </listitem>
481        <listitem>
482          <para>
483            Place the new service in same package as the abstract class,
484            <classname>net.sf.basedb.ws.server.*</classname>
485          </para>
486        </listitem>
487        <listitem>
488          <para>Write the routines/methods the service should deploy.</para>
489        </listitem>
490        <listitem>
491          <para>
492            Make the build-file create a WSDL-file when the services are
493            compiled(Optional), see
494            <xref linkend="webservices.services_development.generate_wsdl" />
495          </para>
496        </listitem>
497        <listitem>
498          <para>
499            Register the service in
500            <filename>
501              <replaceable>BASE_ROOT</replaceable>
502              /src/webservices/server/META-INF/services.xml
503            </filename>. <xref linkend="webservices.examples.register_service"/>
504             shows how the Session-service is registered.
505             <example id="webservices.examples.register_service">
506              <title>
507                Register a service in
508                <filename>services.xml</filename>
509              </title>
510              <programlisting language="xml">
511&lt;service name="Session" scope="application"&gt;
512    &lt;description&gt;
513      This service handles BASE sessions (including login/logout)
514    &lt;/description&gt;
515    &lt;messageReceivers&gt;
516      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
517        class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" /&gt;
518      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
519        class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" /&gt;
520    &lt;/messageReceivers&gt;
521    &lt;parameter name="ServiceClass" locked="false"&gt;net.sf.basedb.ws.server.SessionService&lt;/parameter&gt;
522  &lt;/service&gt;
523</programlisting>
524            </example>
525          </para>
526        </listitem>
527      </orderedlist>
528    </para>
529    <sect2 id="webservices.services_development.generate_wsdl">
530      <title>Generate WSDL-files</title>
531      <para>
532        When a new service is created it can be a good idea to also get a WSDL-file
533        generated when the web services are compiled. The WSDL-file will be a help for those
534        developers who intend to create client applications to the new service. It is an
535        one-liner in the ant build file to do this and not very complicated. Following line
536        shows how this is made for ProjectService, only thing you have to do is to replace
537        <replaceable>ProjectService</replaceable>
538        with the name of your service class.
539<programlisting language="xml">
540&lt;webservices.wsdl serviceClassName="ProjectService"/&gt;
541</programlisting>
542      </para>
543    </sect2>
544  </sect1>
545</chapter>
Note: See TracBrowser for help on using the repository browser.