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

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

References #809 Described available services and describe how to create server/client applications

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