Changeset 3969


Ignore:
Timestamp:
Nov 14, 2007, 2:17:17 PM (14 years ago)
Author:
Nicklas Nordborg
Message:

Fixes #809: Read Web services documentation

File:
1 edited

Legend:

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

    r3944 r3969  
    3434    reading with the first section in this chapter and then you can move on to either the second
    3535    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
     36    you think there are some services missing and you want to know how to proceed to develop a
    3737    new one.
    3838  </para>
     
    4545        <para>
    4646          Items in Base are not send directly by the web services, most of them are to
    47           complexed for this should be possible. Instead is each item type represented by
    48           an info class that can hold the type's less complex properties. The complex
    49           properties need to be exported to a file before they can be send by the web
    50           services as an attachment.
     47          complex for this should be possible. Instead is each item type represented by
     48          an info class that can hold the type's less complex properties.
    5149        </para>
    5250      </listitem>
    5351      <listitem>
    5452        <para>
    55           Base offers a way for services to allow the client applications to put their own
     53          BASE offers a way for services to allow the client applications to put their own
    5654          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 docapi="net.sf.basedb.ws.info">QueryOptions</classname>
    59           . This is on the first hand for the service developers but it can be useful for
     55          to develop services it is recommended to have a look in javadoc for the
     56          <classname docapi="net.sf.basedb.info">QueryOptions</classname> class.
     57          This is on the first hand for the service developers but it can be useful for
    6058          client developers to also know that this may be available in some services.
    6159        </para>
     
    6866    <para>
    6967      Web services can, at the moment, be used to provide some information and data related to
    70       experiments in BASE, like information about raw bioassays or exported bioassay set, to
    71       mention some. The subsection below lists all the available services in Base and gives a
    72       short description, including available methods. More detailed information can be found
    73       in the javadoc and WSDL-files. Each service has it's own class and WSDL-file.
     68      experiments in BASE, for exampl, information about raw bioassays or bioassay set data.
     69      The subsection below gives an overview of the services that are currently present in
     70      BASE short description for each. More detailed information
     71      can be found in the javadoc and WSDL-files. Each service has it's own class and WSDL-file.
    7472    </para>
    7573
     
    7876      <variablelist>
    7977        <varlistentry>
    80           <term>SessionService</term>
    81           <listitem>
    82             <para>Provides methods to manage a session in Base.</para>
    83             <variablelist>
    84               <varlistentry>
    85                 <term>
    86                   <function>newSession</function>
    87                 </term>
    88                 <listitem>
    89                   <para>
    90                     Creates a new session and returns it's id. Before a session can
    91                     be used you have to login with it.
    92                   </para>
    93                   <important>
    94                     <para>
    95                       The id should be send along each time a client invokes a
    96                       service otherwise it is not possible for the service to get
    97                       access to Base.
    98                     </para>
    99                   </important>
    100                 </listitem>
    101               </varlistentry>
    102               <varlistentry>
    103                 <term>
    104                   <function>login</function>
    105                 </term>
    106                 <listitem>
    107                   <para>
    108                     Login and activate a session. A registered user's login and
    109                     password has to be used.
    110                   </para>
    111                 </listitem>
    112               </varlistentry>
    113               <varlistentry>
    114                 <term>
    115                   <function>logout</function>
    116                 </term>
    117                 <listitem>
    118                   <para>
    119                     Logout and stops an active session in Base.
    120                   </para>
    121                 </listitem>
    122               </varlistentry>
    123               <varlistentry>
    124                 <term>
    125                   <function>getChallenge</function>
    126                 </term>
    127                 <listitem>
    128                   <para>
    129                     Returns a random string to be used for password encryption.
    130                   </para>
    131                 </listitem>
    132               </varlistentry>
    133               <varlistentry>
    134                 <term>
    135                   <function>getSessionTimeOut</function>
    136                 </term>
    137                 <listitem>
    138                   <para>
    139                     Gives how many minutes of inactivity before a
    140                     session do a timeout and automatically logout.
    141                   </para>
    142                 </listitem>
    143               </varlistentry>
    144               <varlistentry>
    145                 <term>
    146                   <function>refreshSession</function>
    147                 </term>
    148                 <listitem>
    149                   <para>
    150                     Reset the time of inactivity. Can be used to keep a session
    151                     alive.
    152                   </para>
    153                 </listitem>
    154               </varlistentry>
    155             </variablelist>
    156           </listitem>
    157         </varlistentry>
    158 
    159         <varlistentry>
    160           <term>ProjectService</term>         
    161           <listitem>
    162             <para>Service related to project</para>
    163             <variablelist>
    164               <varlistentry>
    165                 <term>
    166                   <function>setActiveProject</function>
    167                 </term>
    168                 <listitem>
    169                   <para>
    170                     Sets a project to be active. This is the same as when a
    171                     project is set to be active in the web client, see
    172                     <xref linkend="project_permission.projects.active" />
    173                     .
    174                   </para>
    175                 </listitem>
    176               </varlistentry>
    177               <varlistentry>
    178                 <term>
    179                   <function>getProjects</function>
    180                 </term>
    181                 <listitem>
    182                   <para>
    183                     Gets information about each project an active session has
    184                     permission to read.
    185                   </para>
    186                 </listitem>
    187               </varlistentry>
    188             </variablelist>
    189           </listitem>
    190         </varlistentry>
    191         <varlistentry>
    192           <term>ExperimentService</term>
    193           <listitem>
    194             <para>
    195               Different kinds of methods regarding experiments and items in an
    196               experiment.
    197             </para>
    198             <variablelist>
    199               <varlistentry>
    200                 <term>
    201                   <function>getExperiments</function>
    202                 </term>
    203                 <listitem>
    204                   <para>
    205                     Information about each experiment an active session has
    206                     permission to read.
    207                   </para>
    208                 </listitem>
    209               </varlistentry>
    210               <varlistentry>
    211                 <term>
    212                   <function>getBioAssaySets</function>
    213                 </term>
    214                 <listitem>
    215                   <para>
    216                     Returns information about bioassay sets in an experiment.
    217                   </para>
    218                 </listitem>
    219               </varlistentry>
    220               <varlistentry>
    221                 <term>
    222                   <function>getRawBioAssays</function>
    223                 </term>
    224                 <listitem>
    225                   <para>
    226                     Returns information about the raw bioassays used in an
    227                     experiment.
    228                   </para>
    229                 </listitem>
    230               </varlistentry>
    231             </variablelist>
    232           </listitem>
    233         </varlistentry>
    234         <varlistentry>
    235           <term>BioAssaySetService</term>
    236           <listitem>
    237             <para>Services related to bioassay sets.</para>
    238             <variablelist>
    239               <varlistentry>
    240                 <term>
    241                   <function>getExportFormats</function>
    242                 </term>
    243                 <listitem>
    244                   <para>
    245                     Returns the name of the file formats a bioassay set can be
    246                     exported in. Available formats are the ones provided by the
    247                     BioAssaySetExporter-plugin.
    248                   </para>
    249                 </listitem>
    250               </varlistentry>
    251             </variablelist>
    252             <variablelist>
    253               <varlistentry>
    254                 <term>
    255                   <function>downloadBioAssaySet</function>
    256                 </term>
    257                 <listitem>
    258                   <para>
    259                     Returns an
    260                     <classname>org.apache.axiom.om.OMElement</classname>
    261                     object with a file attached. The file contains a bioassayset
    262                     exported by the BioAssaySetExporter in a specific format . The
    263                     format parameter must be identical to one of the strings
    264                     returned by
    265                     <function>getExportFormats</function>
    266                     . How to get access to the received file is described in
    267                     section,
    268                     <xref linkend="webservices.client_development" />
    269                   </para>
    270                 </listitem>
    271               </varlistentry>
    272             </variablelist>
    273           </listitem>
    274         </varlistentry>
    275         <varlistentry>
    276           <term>RawBioAssayService</term>
    277           <listitem>
    278             <para>
    279               Methods related to raw bioassays and exporting data from a raw bioassay.
    280               In most cases you need to know the id of a raw bioassay to be able to
    281               use one of these methods.
    282             </para>
    283             <variablelist>
    284               <varlistentry>
    285                 <term>
    286                   <function>getArrayDesign</function>
    287                 </term>
    288                 <listitem>
    289                   <para>
    290                     Returns information about the array design used
    291                     by a raw bioassay.
    292                   </para>
    293                 </listitem>
    294               </varlistentry>
    295               <varlistentry>
    296                 <term>
    297                   <function>downloadRawDataByType</function>
    298                 </term>
    299                 <listitem>
    300                   <para>
    301                     Returns a
    302                     <classname>org.apache.axiom.om.OMElement</classname>
    303                     . Raw data file will be attached to this element if the raw
    304                     bioassay using file storage in Base.
    305                   </para>
    306                 </listitem>
    307               </varlistentry>
    308               <varlistentry>
    309                 <term>
    310                   <function>hasDownloadableData</function>
    311                 </term>
    312                 <listitem>
    313                   <para>
    314                     This method should be used before calling any of
    315                     <function>downloadRawDataByType</function>
    316                     or
    317                     <function>getDataFileTypes</function>
    318                     above. It shows if there are any data file in a raw bioassay
    319                     to download or not.
    320                   </para>
    321                 </listitem>
    322               </varlistentry>
    323               <varlistentry>
    324                 <term>
    325                   <function>getDataFileTypes</function>
    326                 </term>
    327                 <listitem>
    328                   <para>
    329                     Shows information about the data file types, for a raw
    330                     bioassay, that can be downloaded.
    331                   </para>
    332                 </listitem>
    333               </varlistentry>
    334             </variablelist>
    335           </listitem>
    336         </varlistentry>
    337         <varlistentry>
    338           <term>ArrayDesignService</term>
    339           <listitem>
    340             <para>Service for array designs and data in array designs.</para>
    341             <variablelist>
    342               <varlistentry>
    343                 <term>
    344                   <function>getDataFileTypes</function>
    345                 </term>
    346                 <listitem>
    347                   <para>
    348                     Gets information about the data file types used to store an
    349                     array design in files.
    350                   </para>
    351                 </listitem>
    352               </varlistentry>
    353               <varlistentry>
    354                 <term>
    355                   <function>hasDownloadableData</function>
    356                 </term>
    357                 <listitem>
    358                   <para>
    359                     Indicates if an array design is saved as a file or not.
    360                     Useful before calling any of the other method.
    361                   </para>
    362                 </listitem>
    363               </varlistentry>
    364               <varlistentry>
    365                 <term>
    366                   <function>downloadArrayDesignByType</function>
    367                 </term>
    368                 <listitem>
    369                   <para>
    370                     Gets an array design file of a certain type. Only array
    371                     designs using file storage in Base can be used with this
    372                     method. For other array designs this method will return an
    373                     empty element.
    374                   </para>
    375                 </listitem>
    376               </varlistentry>
    377             </variablelist>
    378           </listitem>
    379         </varlistentry>
     78          <term><classname docapi="net.sf.basedb.ws.server">SessionService</classname></term>
     79          <term><classname docapi="net.sf.basedb.ws.client">SessionClient</classname></term>
     80          <listitem>
     81            <para>
     82              Provides methods to manage a sessions. This is the main entry point
     83              to the BASE web services. This contains methods for logging in and out
     84              and keeping the session alive to avoid automatic logout due
     85              to inactivity.
     86            </para>
     87          </listitem>
     88        </varlistentry>
     89
     90        <varlistentry>
     91          <term><classname docapi="net.sf.basedb.ws.server">ProjectService</classname></term>         
     92          <term><classname docapi="net.sf.basedb.ws.client">ProjectClient</classname></term>
     93          <listitem>
     94            <para>
     95              Service related to projects. You can list available projects
     96              and select one to use as the active project.
     97            </para>
     98          </listitem>
     99        </varlistentry>
     100       
     101        <varlistentry>
     102          <term><classname docapi="net.sf.basedb.ws.server">ExperimentService</classname></term>
     103          <term><classname docapi="net.sf.basedb.ws.client">ExperimentClient</classname></term>
     104          <listitem>
     105            <para>
     106              Service related to experiments. List your experiments and
     107              find out which raw bioassays that are part of it and
     108              which bioassay sets have been created as part of the analysis.
     109            </para>
     110          </listitem>
     111        </varlistentry>
     112       
     113        <varlistentry>
     114          <term><classname docapi="net.sf.basedb.ws.server">BioAssaySetService</classname></term>
     115          <term><classname docapi="net.sf.basedb.ws.client">BioAssaySetClient</classname></term>
     116          <listitem>
     117            <para>
     118              Services related to bioassay sets. Get access to the data in a bioassay
     119              set by exporting it to a file. Supported foramts are those provided
     120              by the <classname docapi="net.sf.basedb.plugins">BioAssaySetExporter</classname>
     121              plug-in.
     122            </para>
     123          </listitem>
     124        </varlistentry>
     125
     126        <varlistentry>
     127          <term><classname docapi="net.sf.basedb.ws.server">RawBioAssayService</classname></term>
     128          <term><classname docapi="net.sf.basedb.ws.client">RawBioAssayClient</classname></term>
     129          <listitem>
     130            <para>
     131              Services related to raw bioassays. Find out which raw data files that
     132              are present and download them.
     133            </para>
     134          </listitem>
     135        </varlistentry>
     136       
     137        <varlistentry>
     138          <term><classname docapi="net.sf.basedb.ws.server">ArrayDesignService</classname></term>
     139          <term><classname docapi="net.sf.basedb.ws.client">ArrayDesignClient</classname></term>
     140          <listitem>
     141            <para>
     142              Services related to array design. Find out which data files that
     143              are present and download them.
     144            </para>
     145          </listitem>
     146        </varlistentry>
     147       
    380148      </variablelist>
    381149    </sect2>
     
    385153    <title>Client development</title>
    386154    <para>
    387       How to develop client applications for the web services in Base is, of course, depending
    388       alot on which program language you are using. Base comes with clients written in java
    389       for the existing services and these clients can either be used as examples of how
    390       clients should implement the services or used as real client applications. The root URL
    391       that clients should use to access the services in Base is
    392       <uri>
    393         http://
    394         <replaceable>BASE_URL</replaceable>
    395         /services/
    396       </uri>
     155      How to develop client applications for the web services in Base is, of course, depends
     156      on which program language you are using. Base comes with a simple client API for java
     157      for the existing services. If you use this API, you don't have to worry about WSDL
     158      files, stubs and skeletons and other web services related stuff. Just use it
     159      the client API as any other java API.
    397160    </para>
    398161   
    399162    <para>
    400       There are WSDL-files available in the Base distribution for each service class, as a
    401       help for the developer of web service clients. The files are located in
    402       <filename class="directory">
    403         <replaceable>BASE_HOME</replaceable>
    404         /misc/wsdl/
    405       </filename>
    406       . Each WSDL-file has the same name as the service it corresponds to.
     163      The client API can be downloaded with example code from the
     164      <ulink url="http://base.thep.lu.se/wiki/DeveloperInformation">BASE developer
     165      website</ulink>. The package contains all external JAR files you need, the
     166      WSDL files (in case you still want them) and some example code that
     167      logs in to a BASE server, lists projects and experiments and then logs out
     168      again. Here is a short example of how to login to a BASE server, list
     169      the experiments and then logout.
     170    </para>
     171   
     172    <programlisting language="java">
     173String serviceUrl = "http://your.base.server/base2/services";
     174String login = "mylogin";
     175String password = "mypassword";
     176
     177// Create new session
     178SessionClient session = new SessionClient(serviceUrl, null, null);
     179
     180// Login
     181session.login(login, password, null, false);
     182
     183// Get all projects and print out name and ID
     184ExperimentClient ex = new ExperimentClient(session);
     185ExperimentInfo[] experiments = ec.getExperiments(new QueryOptions());
     186
     187if (experiments != null &amp;&amp; experiments.length > 0)
     188{
     189   for (ExperimentInfo info : experiments)
     190   {
     191      System.out.println("name=" + info.getName() + "; id=" +info.getId());
     192   }
     193}
     194
     195// Logout
     196session.logout();
     197</programlisting>
     198   
     199    <para>
     200      If you want to use another language than Java or you don't want to
     201      use our client API, you probably need the WSDL files. These can be found
     202      in the client API package discussed above and also in the BASE core
     203      distribution in the <filename>&lt;base-dir&gt;/misc/wsdl</filename>
     204      directory. The WSDL files can also be generated on the fly by the BASE server
     205      by appending <constant>?wsdl</constant> to the url for a specific service.
     206      For example, <constant>http://your.base.server/base2/services/Session?wsdl</constant>.
    407207    </para>
    408208
     
    410210      <title>Receiving files</title>
    411211      <para>
    412         Files are not send by the web services like ie. strings and integers are. Instead a
    413         file is send as a binary attachment to an element in the XML. It is in the interest
    414         of the client developer to know how to get access to a received file. Below are
    415         therefore both a list showing which level a file is located and
    416         programlisting that shows how it is implemented in the java-clients that come with
    417         Base.
    418         <itemizedlist mark="none">
    419           <listitem>
    420             <sgmltag class="starttag">MessageElement</sgmltag>
    421             <itemizedlist mark="none">
    422               <listitem>
    423                 <sgmltag class="starttag">FileElement</sgmltag>
    424                 <itemizedlist mark="none">
    425                   <listitem>
    426                     <sgmltag class="starttag">BinaryNode</sgmltag>
    427                   </listitem>
    428                 </itemizedlist>
    429               </listitem>
    430             </itemizedlist>
    431           </listitem>
    432         </itemizedlist>
    433         The file is attached to the last node and can be accessed by picking up the
    434         inputstream, see example below. Here is a programlisting, that shows how it is done
    435         in the web service clients that comes with Base.
    436 <programlisting language="java">
    437 protected File invokeFileBlocking(String operation, String fileName, Object... args)
    438     throws AxisFault, IOException
    439   {
    440     //Creates a file to write the inputstream to.
    441     File receivedFile = new File(fileName);
    442    
    443     //Get the whole response element send from the server-side
    444     OMElement response = getService().invokeBlocking(getOperation(operation), args);
    445    
    446     //The element returned from the service is the first element of the response
    447     OMElement fileElement = response.getFirstElement();
    448    
    449     //File node allways in the first element.
    450     OMElement dataElement = fileElement.getFirstElement(); 
    451     if (dataElement == null) return null;
    452    
    453     //Get the binary node and pick up the inputstream.
    454     OMText node = (OMText) dataElement.getFirstOMChild();
    455     node.setBinary(true);
    456     DataHandler dataHandler = (DataHandler) node.getDataHandler();   
    457     InputStream in = dataHandler.getInputStream();
    458    
    459     //Write the inputstream to the files outputstream
    460     FileOutputStream out = new FileOutputStream(receivedFile);
    461     byte[] buffer = new byte[512];
    462     int bytes = 0;
    463     long totalBytes = 0;
    464     while (bytes != -1)
    465     {
    466       bytes = in.read(buffer, 0, buffer.length);
    467       if (bytes > 0)
    468       {
    469         totalBytes += bytes;
    470         out.write(buffer, 0, bytes);
    471       }
    472     }
    473     //The file is now received
    474     return receivedFile;
    475   }
    476 </programlisting>
     212        Some methods can be used to download files or exported data. Since this
     213        kind of data can be binary data the usual return methods can't be used.
     214        Base uses a method commonly known as <emphasis>web services with attachments</emphasis>
     215        using MTOM (SOAP Message Transmission Optimization Mechanism) to send file data.
     216        Read the <ulink url="http://ws.apache.org/axis2/1_0/mtom-guide.html">MTOM Guide</ulink>
     217        from Apache if you want to know more about this.
    477218      </para>
     219     
     220      <para>
     221        With the client API it is relatively easy to download a file. Here is a short
     222        program example that downloads the CEL files for all raw bioassays in an
     223        experiment.
     224      </para>
     225     
     226      <programlisting language="java">
     227int experimentId = ...
     228SessionClient session = ...
     229String fileType = "affymetrix.cel";
     230
     231// Create clients for experiment and raw bioassay
     232ExperimentClient ec = new ExperimentClient(session);
     233RawBioAssayClient rc = new RawBioAssayClient(session);
     234
     235// Get all raw bioassays in the experiment
     236RawBioAssayInfo[] rawInfo = ec.getRawBioAssays(experimentId, new QueryOptions());
     237if (rawInfo == null &amp;&amp; rawInfo.length == 0) return;
     238
     239for (RawBioAssayInfo info : rawInfo)
     240{
     241   // We receive the file contents as an InputStream
     242   InputStream download = rc.downloadRawDataByType(info.getId(), fileType);
     243   
     244   // Save to file with the same name as the raw bioassay + .cel
     245   // assume that there are no duplicates
     246   File saveTo = new File(info.getName() + ".cel");
     247   FileUtil.copy(download, new FileOutputStream(saveTo));
     248}
     249</programlisting>
     250
     251        <para>
     252          If you are using another programming language than Java or doesn't
     253          want to use the client API you must know how to get access to the
     254          received file. The data is sent as a binary attachment to an element in the
     255          XML. It is in the interest of the client developer to know how to get access
     256          to a received file and to make sure that the programming language/web services
     257          framework that is used supports MTOM. Below is a listing which shows an
     258          example of a returned message from the
     259          <methodname>RawBioAssayService.downloadRawDataByType()</methodname>
     260          service.
     261        </para>
     262       
     263        <programlisting>
     264<![CDATA[
     265--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
     266Content-Type: application/xop+xml; charset=UTF-8; type="application/soap+xml"
     267Content-Transfer-Encoding: binary
     268Content-ID: <0.urn:uuid:1526E5ADD9FC4431651195044149665@apache.org>
     269
     270<ns:downloadRawDataByTypeResponse xmlns:ns="http://server.ws.basedb.sf.net">
     271  <ns:return>
     272    <Test.cel:Test.cel xmlns:Test.cel="127.0.0.1">
     273       <xop:Include href="cid:1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org"
     274          xmlns:xop="http://www.w3.org/2004/08/xop/include" />
     275    </Test.cel:Test.cel>
     276  </ns:return>
     277</ns:downloadRawDataByTypeResponse>
     278--MIMEBoundaryurn_uuid_1526E5ADD9FC4431651195044149664
     279Content-Type: text/plain
     280Content-Transfer-Encoding: binary
     281Content-ID: <1.urn:uuid:1526E5ADD9FC4431651195044149663@apache.org>
     282
     283... binary file data is here ...
     284]]>
     285</programlisting>
     286       
     287        <para>
     288          Here is a programlisting, that shows how to pick up the file.
     289          This is the actual implementation that is used in the
     290          web service client that comes with BASE. The <classname>InputStream</classname>
     291          returned from this method is the same <classname>InputStream</classname>
     292          that is returned from, for example, the <methodname>RawBioAssayClient.downloadRawDataByType()</methodname>
     293          method.
     294        </para>
     295       
     296        <programlisting language="java">
     297// From AbstractRPCClient.java
     298protected InputStream invokeFileBlocking(String operation, Object... args)
     299   throws AxisFault, IOException
     300{
     301   //Get the original response element as sent from the server-side
     302   OMElement response = getService().invokeBlocking(getOperation(operation), args);
     303
     304   //The file element returned from the service is the first element of the response
     305   OMElement fileElement = response.getFirstElement();
     306   
     307   //The data node always in the first element.
     308   OMElement dataElement = fileElement.getFirstElement();
     309   if (dataElement == null) return null;
     310   
     311   //Get the binary node and pick up the inputstream.
     312   OMText node = (OMText)dataElement.getFirstOMChild();
     313   node.setBinary(true);
     314   DataHandler dataHandler = (DataHandler)node.getDataHandler();   
     315   return dataHandler.getInputStream();
     316}
     317</programlisting>
     318
    478319    </sect2>
    479320  </sect1>
     
    493334          <para>
    494335            Place the new service in same package as the abstract class,
    495             <classname>net.sf.basedb.ws.server.*</classname>
     336            <classname>net.sf.basedb.ws.server</classname>
    496337          </para>
    497338        </listitem>
     
    501342        <listitem>
    502343          <para>
    503             Make the build-file create a WSDL-file when the services are
    504             compiled(Optional), see
    505             <xref linkend="webservices.services_development.generate_wsdl" />
     344            Make the Ant build-file creates a WSDL-file when the services are
     345            compiled (see below). This step is not needed for BASE to work
     346            but may be appreciated by client application developers.
    506347          </para>
    507348        </listitem>
    508349        <listitem>
    509350          <para>
    510             Register the service in
    511             <filename>
    512               <replaceable>BASE_ROOT</replaceable>
    513               /src/webservices/server/META-INF/services.xml
    514             </filename>. <xref linkend="webservices.examples.register_service"/>
    515              shows how the Session-service is registered.
     351            Register the service in the
     352            <filename>&lt;base-dir&gt;/src/webservices/server/META-INF/services.xml</filename>
     353            file. This is an XML file listing all services and is needed
     354            for BASE (Axis) to pick up the new service and expose it to the
     355            outside world. Below is an example of hoe the <classname>Session</classname>
     356            service is registered.
     357           
    516358             <example id="webservices.examples.register_service">
    517359              <title>
    518                 Register a service in
     360                How to register a service in
    519361                <filename>services.xml</filename>
    520362              </title>
    521363              <programlisting language="xml">
    522 &lt;service name="Session" scope="application"&gt;
    523     &lt;description&gt;
    524       This service handles BASE sessions (including login/logout)
    525     &lt;/description&gt;
    526     &lt;messageReceivers&gt;
    527       &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
    528         class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" /&gt;
    529       &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
    530         class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" /&gt;
    531     &lt;/messageReceivers&gt;
    532     &lt;parameter name="ServiceClass" locked="false"&gt;net.sf.basedb.ws.server.SessionService&lt;/parameter&gt;
    533   &lt;/service&gt;
     364<![CDATA[
     365<service name="Session" scope="application"> 
     366   <description> 
     367      This service handles BASE sessions (including login/logout) 
     368   </description> 
     369   <messageReceivers> 
     370      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"   
     371         class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" /> 
     372      <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"   
     373         class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" /> 
     374   </messageReceivers> 
     375   <parameter name="ServiceClass"
     376      locked="false">net.sf.basedb.ws.server.SessionService</parameter> 
     377</service> 
     378]]>
    534379</programlisting>
    535380            </example>
     
    543388        When a new service is created it can be a good idea to also get a WSDL-file
    544389        generated when the web services are compiled. The WSDL-file will be a help for those
    545         developers who intend to create client applications to the new service. It is an
    546         one-liner in the ant build file to do this and not very complicated. Following line
    547         shows how this is made for ProjectService, only thing you have to do is to replace
    548         <replaceable>ProjectService</replaceable>
    549         with the name of your service class.
     390        developers who intend to create client applications to the new service. It is a
     391        one-liner in the Ant build file to do this and not very complicated.
     392        To create a WSDL file for the new web service add a line like the one
     393        below to the <constant>webservices.wsdl</constant> target. Replace
     394        <replaceable>SessionService</replaceable> with the name of the new service class.
     395      </para>
     396
    550397<programlisting language="xml">
    551 &lt;webservices.wsdl serviceClassName="ProjectService"/&gt;
    552 </programlisting>
    553       </para>
     398&lt;webservices.wsdl serviceClassName="SessionService"/&gt;
     399</programlisting>
     400
    554401    </sect2>
    555402  </sect1>
Note: See TracChangeset for help on using the changeset viewer.