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

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

References #809 Documentation updated

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