Ignore:
Timestamp:
Oct 31, 2007, 3:59:45 PM (16 years ago)
Author:
Martin Svensson
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/developerdoc/webservices.xml

    • Property svn:eol-style set to native
    • Property svn:keywords set to Id
    r3885 r3897  
    44    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    55<!--
    6   $Id: base_overview.xml 3675 2007-08-16 14:16:43Z jari $
     6  $Id$
    77 
    88  Copyright (C) 2007 Martin Svensson
    … …  
    3131  <title>Web services</title>
    3232  <para>
    33     This chapter is an introduction of the web services in BASE. It's recommended to begin with
    34     reading the first section in this chapter. Then you can either move on to the second section
    35     for guideness how to develop client applications, or go directly to third section if you
    36     think there are some services missing and you want to develop a new service.
     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.
    3747  </para>
    3848
    … …  
    4050    <title>Available services</title>
    4151    <para>
    42       Below is a list of available services in BASE, each one with information about what it
    43       can do and example of use case.
     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.
    4457    </para>
    4558
    46 
    47     <variablelist>
    48       <varlistentry>
    49         <term>SessionService</term>
    50         <listitem>
    51           <para></para>
    52         </listitem>
    53       </varlistentry>
    54       <varlistentry>
    55         <term>ProjectService</term>
    56         <listitem>
    57           <para></para>
    58         </listitem>
    59       </varlistentry>
    60       <varlistentry>
    61         <term>ExperimentService</term>
    62         <listitem>
    63           <para></para>
    64         </listitem>
    65       </varlistentry>
    66       <varlistentry>
    67         <term>BioAssaySetService</term>
    68         <listitem>
    69           <para></para>
    70         </listitem>
    71       </varlistentry>
    72       <varlistentry>
    73         <term>RawBioAssayService</term>
    74         <listitem>
    75           <para></para>
    76         </listitem>
    77       </varlistentry>
    78       <varlistentry>
    79         <term>ArrayDesignService</term>
    80         <listitem>
    81           <para></para>
    82         </listitem>
    83       </varlistentry>
    84     </variablelist>
     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>
    85394  </sect1>
    86395
    87396  <sect1 id="webservices.client_development">
    88397    <title>Client development</title>
    89     <para></para>
     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>
    90487  </sect1>
    91488
    92489  <sect1 id="webservices.services_development">
    93     <title>Services development</title>
    94     <para></para>
     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>
    95542  </sect1>
    96543</chapter>
Note: See TracChangeset for help on using the changeset viewer.