Changeset 3907


Ignore:
Timestamp:
Nov 5, 2007, 2:58:33 PM (14 years ago)
Author:
Martin Svensson
Message:

References #809. Smaller adjustments.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/developerdoc/webservices.xml

    r3897 r3907  
    3131  <title>Web services</title>
    3232  <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.
     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.
    3738  </para>
    3839
    3940  <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.
     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>
    4760  </para>
    4861
     
    5063    <title>Available services</title>
    5164    <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.
     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.
    5769    </para>
    5870
    5971    <sect2 id="webservices.available_services.services">
    6072      <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>
    6673      <variablelist>
    67 
    6874        <varlistentry>
    6975          <term>SessionService</term>
    7076          <listitem>
    71             <para>Different kinds of methods to manage a session in Base.</para>
     77            <para>Provides methods to manage a session in Base.</para>
    7278            <variablelist>
    7379              <varlistentry>
     
    95101                <listitem>
    96102                  <para>
    97                     Login and activate a session, using a registered user's
    98                     login name and password.
     103                    Login and activate a session. A registered user's login and
     104                    password has to be used.
    99105                  </para>
    100106                </listitem>
     
    106112                <listitem>
    107113                  <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.
     114                    Logout and stop an active session in Base.
    111115                  </para>
    112116                </listitem>
     
    151155          <term>ProjectService</term>         
    152156          <listitem>
    153             <para>Service to handle projects</para>
     157            <para>Service related to project</para>
    154158            <variablelist>
    155159              <varlistentry>
     
    160164                  <para>
    161165                    Sets a project to be active. This will be the same as when a
    162                     project is active in the web client, see
     166                    project is set to be active in the web client, see
    163167                    <xref linkend="project_permission.projects.active" />
    164168                    .
     
    174178                    Gets information about each project the active session has
    175179                    permission to read.
    176                     <classname>net.sf.basedb.ws.info.ProjectInfo</classname>
    177                     objects are used to hold the information.
    178180                  </para>
    179181                </listitem>
     
    196198                <listitem>
    197199                  <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.
     200                    Information about each experiment an active session has
     201                    permission to read.
    202202                  </para>
    203203                </listitem>
     
    209209                <listitem>
    210210                  <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.
     211                    Returns information about bioassay sets in an experiment.
    216212                  </para>
    217213                </listitem>
     
    224220                  <para>
    225221                    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.
     222                    experiment.
    229223                  </para>
    230224                </listitem>
     
    246240                    Returns the name of the file formats a bioassay set can be
    247241                    exported in. Available formats are the ones provided by the
    248                     core plugin called BioAssaySetExporter.
     242                    BioAssaySetExporter-plugin.
    249243                  </para>
    250244                </listitem>
     
    261255                    <classname>org.apache.axiom.om.OMElement</classname>
    262256                    object with a file attached. The file contains a bioassayset
    263                     exported in specific format by the BioAssaySetExporter. The
     257                    exported by the BioAssaySetExporter in a specific format . The
    264258                    format parameter must be identical to one of the strings
    265259                    returned by
     
    289283                <listitem>
    290284                  <para>
    291                     This returns information about the array design that is used
     285                    Returns information about the array design used
    292286                    by a raw bioassay.
    293287                  </para>
     
    302296                    Returns a
    303297                    <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.
     298                    . Raw data file will be attached to this element if the raw
     299                    bioassay using file storage in Base.
    307300                  </para>
    308301                </listitem>
     
    330323                  <para>
    331324                    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.
     325                    bioassay, that can be downloaded.
    338326                  </para>
    339327                </listitem>
     
    354342                  <para>
    355343                    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.
     344                    array design in files.
    362345                  </para>
    363346                </listitem>
     
    370353                  <para>
    371354                    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.
     355                    Useful before calling any of the other method.
    374356                  </para>
    375357                </listitem>
     
    383365                    Gets an array design file of a certain type. Only array
    384366                    designs using file storage in Base can be used with this
    385                     method.
     367                    method. For other array designs this method will return an
     368                    empty element.
    386369                  </para>
    387370                </listitem>
     
    398381    <para>
    399382      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
     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
    403386    </para>
    404387   
     
    410393        /misc/wsdl/
    411394      </filename>
    412       and are generated automatically when Base is compiled. Each WSDL-file has the same name
    413       as the service it corresponds to.
     395      . Each WSDL-file has the same name as the service it corresponds to.
    414396    </para>
    415397
     
    420402        file is send as a binary attachment to an element in the XML. It is in the interest
    421403        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
     404        therefore both a list showing which level a file is located and
    423405        programlisting that shows how it is implemented in the java-clients that come with
    424406        Base.
     
    432414                  <listitem>
    433415                    <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.
    436416                  </listitem>
    437417                </itemizedlist>
     
    440420          </listitem>
    441421        </itemizedlist>
    442         Here is a programlisting, that shows how it is done in the web service clients in
    443         Base.
     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.
    444425<programlisting language="java">
    445426protected File invokeFileBlocking(String operation, String fileName, Object... args)
     
    520501              <replaceable>BASE_ROOT</replaceable>
    521502              /src/webservices/server/META-INF/services.xml
    522             </filename>
     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>
    523525          </para>
    524526        </listitem>
Note: See TracChangeset for help on using the changeset viewer.