Understanding and Running the Example Application

This section discusses the WSS sample application, xms, which is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. This directory and this sample application is installed on your system only if you have selected to install the samples server when you installed the Application Server. If you have not installed the samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the xms example is a simple web service implemented using a J2EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, sayHello, which takes a string then sends a response with Hello prefixed to the given string. You can view the WSDL file for the service endpoint interface at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl.

In this application, the client lookups the service using the JNDI name java:comp/env/service/HelloWorld and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response Hello Duke!

This example shows how to use message security for web services at the Application Server level and at the application level. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

This section includes the following topics:

• To Set Up the Sample Application

• To Run the Sample Application

To Set Up the Sample Application

Before You Begin

The example application is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. For ease of reference throughout the rest of this section, this directory is referred to as simply app-dir/xms/.

In order to have access to this sample application, you must have installed the samples server during installation of the Application Server. To check to see if the samples are installed, browse to the directory install-dir/samples/webservices/security/ejb/apps/xms/. If this directory exists, you do not need to follow the steps in the following section. If this directory does not exist, the samples server is not installed, and must be installed for access to the sample application discussed here.

1. Start the installation for the Application Server.

2. Click Next on the Welcome page.

3. Click Yes on the Software License Agreement page. Click Next.

4. Click Next to accept the installation directory, or change it to match the location where the Application Server is currently installed.

5. Select Continue to install to the same directory.

   You want to do this because you want the samples/ directory to be a subdirectory of the Application Server directory, install-dir/samples/.

6. Reenter the Admin User Name and Password. Click Next.

   You are on the page where you select to install just the samples.

7. Deselect everything except Create Samples Server. Click Next.

8. Click Install Now to install the samples.

9. Click Finish to complete the installation.

To Run the Sample Application

1. Make sure that the Application Server is running.

   Message security providers are set up when the asant targets are run, so you don’t need to configure these on the Application Server prior to running this example.

2. If you are not running HTTP on the default port of 8080, change the WSDL file for the example to reflect the change, and change the common.properties file to reflect the change as well.

   The WSDL file for this example is located at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl. The port number is in the following section:

   <service name="HelloWorld">
     <port name="HelloIFPort" binding="tns:HelloIFBinding">
       <soap:address location="http://localhost:8080/service/HelloWorld"/>
     </port>
   </service>

   Verify that the properties in the install-dir/samples/common.properties file are set properly for your installation and environment. If you need more description of this file, refer to the Configuration section for the web services security applications at install-dir/samples/webservices/security/docs/common.html#Logging.

3. Change to the install-dir/samples/webservices/security/ejb/apps/xms/ directory.

4. Run the following asant targets to compile, deploy, and run the example application:

   1. To compile samples:

      asant

   2. To deploy samples:

      asant deploy

   3. To run samples:

      asant run

   If the sample has compiled and deployed properly, you see the following response on your screen after the application has run:

   run:[echo] Running the xms program:[exec] Established message level security : Hello Duke!

5. To undeploy the sample, run the following asant target:

   asant undeploy

   All of the web services security examples use the same web service name (HelloWorld) and web service ports in order to show only the differences necessary for protecting web services using various mechanisms. Make sure to undeploy an application when you have completed running it, or you receive an Already in Use error and deployment failures when you try to deploy another web services example application.