Deploying OpenXRI Store Functions as SOAP Services

Copyright 2006 OpenXRI Fondation
Author :
Distributed under Apache 2.0 License

Document Conventions

In this document following conventions are used,

Important :

This document is intended for developers of openxri code who change one of these core classes

or change the CORBA interface IDL file.

This document explains how to generate code and other steps required to deploy SOAP services on both server side and client side.

Note : As a OpenXRI end user , you do not have to perform any of these steps. All these steps have already been completed and the generated code is already embedded as part of download at correct locations.

Note : All the steps mentioned here can be done on regular development box with reliable configuration. These are not required to be done on Production (Live) box. In these steps, we are only generating Java Code which needs to be embedded on Server Side and Client Side code.

Dependencies :

Before proceeding to any of these steps, it is assumed you have completed the basic XRI Server Setup (With/Without SOAP Services Deployed) and you have the application deployed in a Servlet Engine. Which means you can at least invoke the URL, (http://hostname:portnum/openxri/resolve) even if it does not resolve to anything.

To keep it simple, this guide assumes that you are currently using Tomcat as the Servlet Engine. Except for folder locations, most of the steps will be same on other Servers also. The install location for Tomcat is referred to as %TOMCAT_HOME%

Also in this document. the place where OpenXRI is downloaded and extracted on local machine is referred to %OPENXRI_HOME%

Step 1 : Generating the WSDL file

In this step we will generate the WSDL file.

While the Tomcat Server is running copy the file,

%OPENXRI_HOME%\org.openxri.soapadmin\schemas\soap\StoreServices.jws

To following location,

%TOMCAT_HOME%webapps/openxri/StoreServices.jws

and then from Browser request for following URL,

http://hostname:portnum/openxri/StoreServices.jws?wsdl

(replace hostname and portnum with required parameters)

This will generate the WSDL file.

Save this file to following location,

%OPENXRI_HOME%\org.openxri.soapadmin\schemas\soap\openxri.wsdl

NOTES : StoreServices.jws Lists all the Services (functions) that can be invoked from Client End. So if any functions need to be added or modified, this file needs to be modified

VERY IMPORTANT : Remove the file "%TOMCAT_HOME%webapps/openxri/StoreServices.jws" once the WSDL has been generated. You won't need it at RunTime. This file only used to generate the WSDL file. This is really a one time operation.

Step 2 : Update the WSDL file

We want to make sure the WSDL File generated from different machines look the same and also we want to make sure the SOAP services work on same server along with CORBA Services.

This is the give choice to users to use either Corba Services or SOAP Services. Please do note that administration of DBStore has been tested only with SOAP Services, since the Hibernate Configuration relies on JNDI based Database Configuration.

So next open following file, %OPENXRI_HOME%\org.openxri.soapadmin\schemas\soap\openxri.wsdl

and make following changes in WSDL file,

  1. Replace the string

    http://hostname:portnum/openxri/StoreServices.jws

    with following string.

    http://openxri.org/soap/StoreServices.jws

    (replace hostname and portnum with required parameters)

  2. Replace the String "iiop." with "soap."

    This will change the package name for generated file and will have SOAP services code work along with CORBA code.

Step 3 : Generating the SOAP Client/Server code

From the command prompt, go to following location,

%OPENXRI_HOME%\org.openxri.soapadmin

and execute command

prompt> ant server

This will generate code required on both Server Side and Client Side.

CAUTION : This Command also updates newly generated Java Files to this folder, %OPENXRI_HOME%\org.openxri.server\src\org\openxri\soap\admin removing any previously generated Server (AXIS) code.

Step 4 : Deploying SOAP Service on Server

In this step we will deploy the SOAP Service on the tomcat server.

Before proceeding with this step, couple of pre-requisite steps needs to be completed.

Dependencies :

Check 1 :

If any new functions have been added in

%OPENXRI_HOME%\org.openxri.soapadmin\schemas\soap\StoreServices.jws

Then the following file needs to be changed,

%OPENXRI_HOME%\org.openxri.server\src\org\openxri\store\webservice\StoreServicesHelper.java

and implement any new functions here.

This is the class that implements all the SOAP functions and the class that is invoked on server side for each SOAP request.

Check 2 :

Since we have copied new code to OpenXRI Server Side code (in Step 4 above), this new code needs to be compiled and deployed on the tomcat server before actually deploying the service.

So first go to %OPENXRI_HOME%\C:\project\org.openxri.server

and from command prompt run following commands,

prompt> ant clean
prompt> ant
prompt> ant war

This will create %OPENXRI_HOME%\org.openxri.server\dist\openxri.war

ReDeploy this WAR file on Tomcat Server again.

Check 3 :

Make sure in web.xml all the Declaration for SOAP Servlet are defined.

Note : It's already done in the web.xml provided as part of OpenXRI distribution. Unless it has been commented out on purpose, this change already exists.

FINAL STEP (Deploying the Services) :

Now lets deploy the service on Server.

  1. On the command set the value for environment variable XRI_SOAP_SERVER

    For example something like this,

    set XRI_SOAP_SERVER_URL=http://localhost:8080/openxri/services/AdminService

    (replace hostname and portnum with required parameters)

    From the build.xml, this variable is referred internally.

  2. Next check if this file already exists,

    %TOMCAT_HOME%\webapps\openxri\WEB-INF\server-config.wsdd

    Remove this file if it exists. This file will be recreated once we deploy the service.

  3. Make sure Tomcat is running at the time this command is executed

    From command prompt, go to following location,

    %OPENXRI_HOME%\org.openxri.soapadmin

    and execute command

    prompt> ant deployservice

    Verify that it will create a new file here %TOMCAT_HOME%\webapps\openxri\WEB-INF\server-config.wsdd

    That completed SOAP Service deployment on Server Side.

Step 5 : Securing the SOAP Service

After above step, once the deployment of the SOAP services is done and the file "server-config.wsdd" is created, this step will secure the deployed methods with UserName/Password combination.

There are several different ways of securing the SOAP Services. For notes, please refer to following document, http://wiki.apache.org/beehive/WsmSecurityModel

Coming back to our setup, the following file,

%OPENXRI_HOME%\org.openxri.server\schemas\soap\users.lst

Which as part of WAR file Deployment is copied to following location,

%TOMCAT_HOME%\webapps\openxri\WEB-INF\users.lst

This has the list of users names and their passwords of the users who can invoke the SOAP request.

In the newly generated file,

%TOMCAT_HOME%\webapps\openxri\WEB-INF\server-config.wsdd

Just after the following line,

<arrayMapping innerType="ns8:Service" languageSpecificType="java:org.openxri.soap.admin.Service[]" qname="ns7:ArrayOf_tns1_Service" xmlns:ns7="http://openxri.org/soap/StoreServices.jws" xmlns:ns8="http://admin.soap.openxri.org"/>

Add the following lines,

<!-- Start : New Lines Added Later to Authenticate User -->
<parameter name="allowedRoles" value="xriuser1,xriuser2"/>
<requestFlow name="checks"> 

        <handler type="java:org.apache.axis.handlers.SimpleAuthenticationHandler"/>
        <handler type="java:org.apache.axis.handlers.SimpleAuthorizationHandler"/>

</requestFlow>
<!-- End : New Lines Added Later to Authenticate User -->

For example of this, you can check the existing file that provided as part of Souce Code. It's available here,

%OPENXRI_HOME%\org.openxri.server\schemas\soap\server-config.wsdd

Here the "allowedRoles" attribute has list of users who can access the service. The idea of this type of deployment is, you have single "users.lst" file and different services can have different set of users.

The file name "users.lst" is not given anywhere in "server-config.wsdd". The "SimpleAuthenticationHandler" at runtime relys on this file for the list of users.

IMPORTANT : After the deployment, to make it more secure, on the Unix Box, remove all permissions on these 2 files,

%TOMCAT_HOME%\webapps\openxri\WEB-INF\server-config.wsdd
%TOMCAT_HOME%\webapps\openxri\WEB-INF\users.lst

and give Read Privileges only to "tomcat" user.

Step 6 : SOAP Client Side usage

Note : For the usage of the client side code, please refer to following file,

%OPENXRI_HOME%\org.openxri.soapadmin\Install.txt