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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: webservices.xml 3969 2007-11-14 13:17:17Z nicklas $
  
  Copyright (C) 2007 Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<chapter id="webservices">
  <?dbhtml dir="webservices"?>
  <title>Web services</title>
  <para>
    This chapter is an introduction of web services in BASE. It is recommended to begin your
    reading with the first section in this chapter and then you can move on to either the second
    section for more information how to develop client applications, or to the third section if
    you think there are some services missing and you want to know how to proceed to develop a
    new one.
  </para>

  <para>
    Before moving on to develop client applications or new services there are few things that
    need to be explained first.
    <orderedlist>
      <listitem>
        <para>
          Items in Base are not send directly by the web services, most of them are to
          complex for this should be possible. Instead is each item type represented by
          an info class that can hold the type's less complex properties.
        </para>
      </listitem>
      <listitem>
        <para>
          BASE offers a way for services to allow the client applications to put their own
          includes and restrictions on a query before it is executed. For those who intend
          to develop services it is recommended to have a look in javadoc for the
          <classname docapi="net.sf.basedb.info">QueryOptions</classname> class.
          This is on the first hand for the service developers but it can be useful for
          client developers to also know that this may be available in some services.
        </para>
      </listitem>
    </orderedlist>
  </para>

  <sect1 id="webservices.available_services">
    <title>Available services</title>
    <para>
      Web services can, at the moment, be used to provide some information and data related to
      experiments in BASE, for exampl, information about raw bioassays or bioassay set data.
      The subsection below gives an overview of the services that are currently present in 
      BASE short description for each. More detailed information 
      can be found in the javadoc and WSDL-files. Each service has it's own class and WSDL-file.
    </para>

    <sect2 id="webservices.available_services.services">
      <title>Services</title>
      <variablelist>
        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">SessionService</classname></term>
          <term><classname docapi="net.sf.basedb.ws.client">SessionClient</classname></term>
          <listitem>
            <para>
              Provides methods to manage a sessions. This is the main entry point
              to the BASE web services. This contains methods for logging in and out
              and keeping the session alive to avoid automatic logout due
              to inactivity.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">ProjectService</classname></term>         
          <term><classname docapi="net.sf.basedb.ws.client">ProjectClient</classname></term>
          <listitem>
            <para>
              Service related to projects. You can list available projects
              and select one to use as the active project.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">ExperimentService</classname></term>
          <term><classname docapi="net.sf.basedb.ws.client">ExperimentClient</classname></term>
          <listitem>
            <para>
              Service related to experiments. List your experiments and
              find out which raw bioassays that are part of it and
              which bioassay sets have been created as part of the analysis.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">BioAssaySetService</classname></term>
          <term><classname docapi="net.sf.basedb.ws.client">BioAssaySetClient</classname></term>
          <listitem>
            <para>
              Services related to bioassay sets. Get access to the data in a bioassay
              set by exporting it to a file. Supported foramts are those provided
              by the <classname docapi="net.sf.basedb.plugins">BioAssaySetExporter</classname>
              plug-in.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">RawBioAssayService</classname></term>
          <term><classname docapi="net.sf.basedb.ws.client">RawBioAssayClient</classname></term>
          <listitem>
            <para>
              Services related to raw bioassays. Find out which raw data files that
              are present and download them. 
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><classname docapi="net.sf.basedb.ws.server">ArrayDesignService</classname></term>
          <term><classname docapi="net.sf.basedb.ws.client">ArrayDesignClient</classname></term>
          <listitem>
            <para>
              Services related to array design. Find out which data files that
              are present and download them. 
            </para>
          </listitem>
        </varlistentry>
        
      </variablelist>
    </sect2>
  </sect1>

  <sect1 id="webservices.client_development">
    <title>Client development</title>
    <para>
      How to develop client applications for the web services in Base is, of course, depends
      on which program language you are using. Base comes with a simple client API for java
      for the existing services. If you use this API, you don't have to worry about WSDL
      files, stubs and skeletons and other web services related stuff. Just use it
      the client API as any other java API.
    </para>
    
    <para>
      The client API can be downloaded with example code from the 
      <ulink url="http://base.thep.lu.se/wiki/DeveloperInformation">BASE developer 
      website</ulink>. The package contains all external JAR files you need, the
      WSDL files (in case you still want them) and some example code that
      logs in to a BASE server, lists projects and experiments and then logs out
      again. Here is a short example of how to login to a BASE server, list
      the experiments and then logout.
    </para>
    
    <programlisting language="java">
String serviceUrl = "http://your.base.server/base2/services";
String login = "mylogin";
String password = "mypassword";

// Create new session
SessionClient session = new SessionClient(serviceUrl, null, null);

// Login
session.login(login, password, null, false);

// Get all projects and print out name and ID
ExperimentClient ex = new ExperimentClient(session);
ExperimentInfo[] experiments = ec.getExperiments(new QueryOptions());

if (experiments != null &amp;&amp; experiments.length > 0)
{
   for (ExperimentInfo info : experiments)
   {
      System.out.println("name=" + info.getName() + "; id=" +info.getId());
   }
}

// Logout
session.logout();
</programlisting>
    
    <para>
      If you want to use another language than Java or you don't want to
      use our client API, you probably need the WSDL files. These can be found
      in the client API package discussed above and also in the BASE core
      distribution in the <filename>&lt;base-dir&gt;/misc/wsdl</filename>
      directory. The WSDL files can also be generated on the fly by the BASE server
      by appending <constant>?wsdl</constant> to the url for a specific service.
      For example, <constant>http://your.base.server/base2/services/Session?wsdl</constant>.
    </para>

    <sect2 id="webservices.client_development.receivingfiles">
      <title>Receiving files</title>
      <para>
        Some methods can be used to download files or exported data. Since this
        kind of data can be binary data the usual return methods can't be used.
        Base uses a method commonly known as <emphasis>web services with attachments</emphasis>
        using MTOM (SOAP Message Transmission Optimization Mechanism) to send file data.
        Read the <ulink url="http://ws.apache.org/axis2/1_0/mtom-guide.html">MTOM Guide</ulink>
        from Apache if you want to know more about this.
      </para>
      
      <para>
        With the client API it is relatively easy to download a file. Here is a short
        program example that downloads the CEL files for all raw bioassays in an
        experiment.
      </para>
      
      <programlisting language="java">
int experimentId = ...
SessionClient session = ...
String fileType = "affymetrix.cel";

// Create clients for experiment and raw bioassay
ExperimentClient ec = new ExperimentClient(session);
RawBioAssayClient rc = new RawBioAssayClient(session);

// Get all raw bioassays in the experiment
RawBioAssayInfo[] rawInfo = ec.getRawBioAssays(experimentId, new QueryOptions());
if (rawInfo == null &amp;&amp; rawInfo.length == 0) return;

for (RawBioAssayInfo info : rawInfo)
{
   // We receive the file contents as an InputStream
   InputStream download = rc.downloadRawDataByType(info.getId(), fileType);
   
   // Save to file with the same name as the raw bioassay + .cel
   // assume that there are no duplicates
   File saveTo = new File(info.getName() + ".cel");
   FileUtil.copy(download, new FileOutputStream(saveTo));
}
</programlisting>

        <para>
          If you are using another programming language than Java or doesn't
          want to use the client API you must know how to get access to the
          received file. The data is sent as a binary attachment to an element in the 
          XML. It is in the interest of the client developer to know how to get access 
          to a received file and to make sure that the programming language/web services
          framework that is used supports MTOM. Below is a listing which shows an
          example of a returned message from the 
          <methodname>RawBioAssayService.downloadRawDataByType()</methodname>
          service.
        </para>
        
        <programlisting>
<![CDATA[
--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:1526E5ADD9FC4431651195044149665@apache.org>

<ns:downloadRawDataByTypeResponse xmlns:ns="http://server.ws.basedb.sf.net">
  <ns:return>
    <Test.cel:Test.cel xmlns:Test.cel="127.0.0.1">
       <xop:Include href="cid:1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org" 
          xmlns:xop="http://www.w3.org/2004/08/xop/include" />
    </Test.cel:Test.cel>
  </ns:return>
</ns:downloadRawDataByTypeResponse>
--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
Content-Type: text/plain
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org>

... binary file data is here ...
]]>
</programlisting>
        
        <para>
          Here is a programlisting, that shows how to pick up the file.
          This is the actual implementation that is used in the 
          web service client that comes with BASE. The <classname>InputStream</classname>
          returned from this method is the same <classname>InputStream</classname>
          that is returned from, for example, the <methodname>RawBioAssayClient.downloadRawDataByType()</methodname>
          method.
        </para>
        
        <programlisting language="java">
// From AbstractRPCClient.java
protected InputStream invokeFileBlocking(String operation, Object... args)
   throws AxisFault, IOException
{
   //Get the original response element as sent from the server-side
   OMElement response = getService().invokeBlocking(getOperation(operation), args);

   //The file element returned from the service is the first element of the response
   OMElement fileElement = response.getFirstElement();
   
   //The data node always in the first element.
   OMElement dataElement = fileElement.getFirstElement(); 
   if (dataElement == null) return null;
   
   //Get the binary node and pick up the inputstream.
   OMText node = (OMText)dataElement.getFirstOMChild();
   node.setBinary(true);
   DataHandler dataHandler = (DataHandler)node.getDataHandler();    
   return dataHandler.getInputStream();
}
</programlisting>

    </sect2>
  </sect1>

  <sect1 id="webservices.services_development">
    <title>Services development</title>   
    <para>
      This list should work as guide when creating new web service in base.
      <orderedlist>
        <listitem>
          <para>
            Create a new class that extends
            <classname api="net.sf.basedb.ws.server">AbstractRPCService</classname>
          </para>
        </listitem>
        <listitem>
          <para>
            Place the new service in same package as the abstract class,
            <classname>net.sf.basedb.ws.server</classname>
          </para>
        </listitem>
        <listitem>
          <para>Write the routines/methods the service should deploy.</para>
        </listitem>
        <listitem>
          <para>
            Make the Ant build-file creates a WSDL-file when the services are
            compiled (see below). This step is not needed for BASE to work
            but may be appreciated by client application developers.
          </para>
        </listitem>
        <listitem>
          <para>
            Register the service in the
            <filename>&lt;base-dir&gt;/src/webservices/server/META-INF/services.xml</filename> 
            file. This is an XML file listing all services and is needed
            for BASE (Axis) to pick up the new service and expose it to the
            outside world. Below is an example of hoe the <classname>Session</classname>
            service is registered.
            
             <example id="webservices.examples.register_service">
              <title>
                How to register a service in
                <filename>services.xml</filename>
              </title>
              <programlisting language="xml">
<![CDATA[
<service name="Session" scope="application">  
   <description>  
      This service handles BASE sessions (including login/logout)  
   </description>  
   <messageReceivers>  
      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"   
         class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />  
      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"   
         class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />  
   </messageReceivers>  
   <parameter name="ServiceClass" 
      locked="false">net.sf.basedb.ws.server.SessionService</parameter>  
</service>  
]]>
</programlisting>
            </example>
          </para>
        </listitem>
      </orderedlist>
    </para>
    <sect2 id="webservices.services_development.generate_wsdl">
      <title>Generate WSDL-files</title>
      <para>
        When a new service is created it can be a good idea to also get a WSDL-file
        generated when the web services are compiled. The WSDL-file will be a help for those
        developers who intend to create client applications to the new service. It is a
        one-liner in the Ant build file to do this and not very complicated. 
        To create a WSDL file for the new web service add a line like the one
        below to the <constant>webservices.wsdl</constant> target. Replace 
        <replaceable>SessionService</replaceable> with the name of the new service class.
      </para>

<programlisting language="xml">
&lt;webservices.wsdl serviceClassName="SessionService"/&gt;
</programlisting>

    </sect2>
  </sect1>
</chapter>