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 will be 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 Accessing the Samples Directory for information on how to do so now.

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 will get 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 (e.g., 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:

Setting Up the Sample Application

Running the Sample Application

Setting Up the Sample Application

This section discusses setting up the message security application that uses XML digital signatures to implement message security. 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 will be referred to as simply app_dir/xms/.

Accessing the Samples Directory

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. To install the samples server, follow these steps:

Start the installation for the Application Server (2004Q4 Beta).

Click Next on the Welcome page.

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

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

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/.

Reenter the Admin User Name and Password. Click Next.

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

Deselect everything except Create Samples Server. Click Next.

Click Install Now to install the samples.

Click Finish to complete the installation.

Modifying Build Targets to Specify Domain

The targets used to compile, package, and deploy the example must be modified to specify under which domain you want the application to run. This is due to a bug in this release. To modify the build target to specify the domain, follow these steps:

Open the file containing the common properties in a text editor. This file is install_dir\samples\common.properties.

Locate the domain.name property in this file. Enter the value of the domain you wish to use for this example. For example, if you are running this example on domain1, verify or modify the property/value as shown (which is the default):

domain.name=domain1

Verify that the properties in the 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.

Save and exit the file.

Open the file containing the asant targets in a text editor. This file is install_dir\samples\webservices\security\ejb\apps\xms\build.xml.

Locate and modify the following arguments and add an argument to specify the name of the domain on which to stop and start the Application Server. The property to be added is specified in bold below.

<echo message="Stopping the server" />
<exec executable="${com.sun.aas.installRoot}/bin/asadmin">
<arg line="stop-domain ${domain.name}"/>
</exec>

<echo message="Restarting the server" />
<exec executable="${com.sun.aas.installRoot}/bin/asadmin">
<arg line="start-domain"/>
<arg line="--user ${admin.user} --password ${admin.password}
${domain.name} "/>
</exec>

Save and exit the file.

Modifying the Path in the sun-acc.xml Template

In order for the path specified in the message security template that renames and replaces the sun-acc.xml file to correctly process message security commands, modify the following property in the file xms/setup/sun-acc.xml.template to make it a relative, instead of absolute, path. This change needs to be made in order to correct an error in the example application.

Open the file install_dir\samples\webservices\security\ejb\apps\xms\setup\
sun-acc.xml.template in a text editor.

Search for the text string /sun/.

When you find a section that looks like the following line, move on to the next step.

Replace the value for that property with the following string that shows the correct relative path to the WSS client configuration file: ${com.sun.aas.instanceRoot}/lib/appclient/wss-client-config.xml.

The resulting line will look like this:

Save and exit the file.

Running the Sample Application

Make sure you’ve completed the steps in Setting Up For Web Services Security.

Make sure that the Application Server is running.

The steps for setting up the message security providers are run when the asant targets are run, so you don’t need to configure these when running this example.

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 will be found in the following section:

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.

Change to the install_dir\samples\webservices\security\ejb\apps\xms\ directory.

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

To compile samples:

asant

To deploy samples:

asant deploy

To run samples:

asant run

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

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

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 will receive an Already in Use error and deployment failures when you try to deploy another Web services example application.

To undeploy the sample, run the following asant target:

asant undeploy

Previous Contents Next

Previous Contents Next
Sun Java System Application Server Enterprise Edition 8 2004Q4 XML and Web Services Security Guide