Java Web Services in a Nutshell

Examples Online

The examples in this book are available online and can be downloaded from the book’s home page at http://www.oreilly.com/catalog/javawsian/. You may also want to visit this site to see if any important notes or errata about the book have been published there. Once you download the example source code, you need to install it, together with either the Java Web Services Developer’s Pack (JWSDP) or the J2EE Version 1.4 reference implementation.

The JWSDP is a standalone package that contains everything that you need to get started with web service development, including the reference implementations of the web services APIs, a version of the Tomcat web server that has been preconfigured with web services, and the Ant build tool for compiling and running web service applications. The JWSDP requires J2SE Version 1.3.1 or later. The example source code for this book has been tested with JWSDP Version 1.1 and J2SE versions 1.4.0 and 1.4.1.

Most of the web services technologies from the JWSDP have been incorporated into the J2EE 1.4 platform. The examples have been tested with the beta release of the J2EE 1.4 reference implementation and should work unchanged with the final release, unless unexpected changes are made. Following the FCS release of J2EE 1.4, refer to the book’s web site where any necessary updates to the example source code will be posted.

You can obtain the JWSDP from http://java.sun.com/webservices/webservicespack.html. After completing the download, follow the instructions that are supplied with the distribution to install it. Alternatively, download and install the reference implementation of J2EE 1.4, which is available at http://java.sun.com/j2ee/download.html. If you choose to use the examples in this book with J2EE 1.4, you will not need to download the JWSDP.

Installing the Example Source Code

The example source code is supplied as a ZIP file that can be unpacked into a directory of your choice, which we’ll refer to throughout this section as c:\JWSNutshell\examples. Beneath this directory, you’ll find the examples for each chapter organized into separate directories. The example source code contains buildfiles for the Ant utility, which is supplied with both the JWSDP and the J2EE 1.4 reference implementation and, throughout this book, you’ll find specific instructions for building and running each example along with the text that describes it.

Once you unpack the examples, copy the files jwsnutExamples.properties and jwsnutJaxrExamples.properties to your home directory. These files need to be tailored to suit your environment before you can run any of the examples, as described in the following sections.

Tailoring the jwnutExamples.properties file

Before you start editing the jwsnutExamples.properties file, you need to decide whether you will be using the example source code with the JWSDP or with J2EE 1.4. To use the JWSDP with the Tomcat web server, uncomment and set the following properties that appear near the top of the file:

USING_JWSDP=true
WSROOT=c:/jwsdp-1.1

The WSROOT property should be set to point to the directory in which you installed the JWSDP. Since this file is read by the Ant build utility, it is acceptable to use forward slashes in pathnames on all operating system platforms, although Windows users may use backslashes if preferred. To use the example source code with J2EE 1.4, uncomment and set the following properties instead:

USING_J2EE14=true
J2EEROOT=c:/j2sdkee1.4
WSROOT=${J2EEROOT}

You should ensure that the property definitions in only one of these two blocks are uncommented.

The settings for the remainder of the properties in this file do not depend on your choice of web container and should be set as described in Table P-1. In most cases, the values that you’ll find in the file will work for your system; therefore, only a small number of these properties will need to be changed.

Table 1. Properties defined in the jwsnutExamples.properties file

Property	Description
EXAMPLES_ROOT	The directory in which you have installed the example source code — for example, c:/JWSNutshell/examples.
USERNAME PASSWORD	Some of the examples in this book make use of HTTP basic authentication to demonstrate how you can apply basic security to your web service. These examples require you to supply a username and password, which are referred to within the text as JWSUser and JWSPassword respectively, but which may have any values you choose. The username and password must also be registered with the web container, as described later in this section.
AMAZON_TAG	Chapter 1 contains an example that makes use of a web service provided by Amazon.com. If you want to run this example for yourself, you will need to register at Amazon.com’s web site and obtain a developer tag, the value of which you should supply here. To register, visit the URL https://associates.amazon.com/exec/panama/associates/join/developer/application.html.
AMAZON_TAG	Chapter 1 contains an example that makes use of a web service provided by Amazon.com. If you want to run this example for yourself, you will need to register at Amazon.com’s web site and obtain a developer tag, the value of which you should supply here. To register, visit the URL https://associates.amazon.com/exec/panama/associates/join/developer/application.html.
CONNECTED	Some of the examples in Chapter 7 are fully functional only when used on a machine that has an Internet connection. If your machine has such a connection, set this property to true.
TARGET_HOST	The name of the host on which the Tomcat or J2EE 1.4 web container is running. In most cases, the value localhost, which is the default, is appropriate.
TOMCAT_WEBPORT J2EE14_WEBPORT	The port number used by the web container. The values that you’ll find in the file as installed are correct for the default installations of the JWSDP and J2EE 1.4
TOMCAT_WEBSVCPORT J2EE14_WEBSVCPORT	The JWSDP installs a small number of services in the Tomcat web container. These services are accessed at a different port, which must be supplied using the TOMCAT_WEBSVCPORT property. The value supplied in the file as installed is correct for the default configuration of the JWSDP and for J2EE 1.4.
TOMCAT_WEBSVCPORT J2EE14_WEBSVCPORT	The JWSDP installs a small number of services in the Tomcat web container. These services are accessed at a different port, which must be supplied using the TOMCAT_WEBSVCPORT property. The value supplied in the file as installed is correct for the default configuration of the JWSDP and for J2EE 1.4.
TOMCAT_WEBSVCPORT J2EE14_WEBSVCPORT	The JWSDP installs a small number of services in the Tomcat web container. These services are accessed at a different port, which must be supplied using the TOMCAT_WEBSVCPORT property. The value supplied in the file as installed is correct for the default configuration of the JWSDP and for J2EE 1.4.
TOMCAT_WEBHTTPSPORT J2EE14_WEBHTTPSPORT	The port number that the web container uses for secure HTTP (HTTPS). The initial settings are correct for the default installations of JWSDP and J2EE 1.4.
TOMCAT_WEBHTTPSPORT J2EE14_WEBHTTPSPORT	The port number that the web container uses for secure HTTP (HTTPS). The initial settings are correct for the default installations of JWSDP and J2EE 1.4.
TOMCAT_WEBHTTPSPORT J2EE14_WEBHTTPSPORT	The port number that the web container uses for secure HTTP (HTTPS). The initial settings are correct for the default installations of JWSDP and J2EE 1.4.
HTTP_PROXY_SERVER HTTP_PROXY_PORT HTTPS_PROXY_SERVER HTTPS_PROXY_PORT	If you need to run the client parts of the example source code in this book through a proxy server, you may do so by setting these properties to point to the server and port number of the proxy that you are using. The HTTPS properties need to be set only if the example uses a secure connection. These properties must not be set if you do not need to use a proxy.
HTTP_PROXY_SERVER HTTP_PROXY_PORT HTTPS_PROXY_SERVER HTTPS_PROXY_PORT	If you need to run the client parts of the example source code in this book through a proxy server, you may do so by setting these properties to point to the server and port number of the proxy that you are using. The HTTPS properties need to be set only if the example uses a secure connection. These properties must not be set if you do not need to use a proxy.
HTTP_PROXY_SERVER HTTP_PROXY_PORT HTTPS_PROXY_SERVER HTTPS_PROXY_PORT	If you need to run the client parts of the example source code in this book through a proxy server, you may do so by setting these properties to point to the server and port number of the proxy that you are using. The HTTPS properties need to be set only if the example uses a secure connection. These properties must not be set if you do not need to use a proxy.

Tailoring the jwsnutJaxrExamples.properties file

The jwsnutJaxrExamples.properties file contains settings that are used with the examples for JAXR (covered in Chapter 7). The appropriate values are described in Chapter 7 alongside the text for the examples that use them.

Environment variables

Some of the utilities in the JWSDP and the J2EE reference implementation rely on environment variables to locate libraries, configuration files, and other utilities. Table P-2 lists the variables that you need to set, along with typical values.

Table 2. Environment variable settings

Variable	Description
JAVA_HOME	The installation directory of the J2SE SDK. A typical value is c:\j2sdk1.4.1.
J2EE_HOME	The installation directory of the J2EE reference implementation. This is required only if you are using J2EE 1.4. A typical value is c:\j2sdkee1.4.
JWSDP_HOME	The installation directory of the JWSDP. A typical value is c:\jwsdp-1.1. Does not need to be set if you are using J2EE 1.4.
JAXRPC_HOME	The home directory for JAX-RPC. This is required only if you are using the JWSDP and should be set to point to the JAX-RPC directory directly below JWSDP_HOME. For JWSDP 1.1, this would be %JWSDP_HOME%\jaxrpc-1.0.3
JAXR_HOME	The home directory for JAXR. This is required only if you are using the JWSDP and should be set to point to the JAXR directory directly below JWSDP_HOME. For JWSDP 1.1, this is %JWSDP_HOME%\jaxr-1.0_03
ANT_HOME	The home directory for the Ant build tool. If you are using the JWSDP, set this to %JWSDP_HOME%\jakarta-ant-1.5.1. For J2EE 1.4, set it to the value of J2EE_HOME. You can also set this variable to point to a separately installed version of Ant if you prefer.
PATH	This variable must include the following: The bin directory of the J2SE SDK (e.g. c:\j2sdk1.4.1\bin) The bin directory of the J2EE installation, if you are using J2EE 1.4 (e.g., c:\j2sdkee1.4\bin) If you are using the JWSDP, the bin directories for the JWSDP itself, then Ant, JAX-RPC, and JAXR must also be added: %JWSDP_HOME%\bin %JWSDP_HOME%\shared\bin %ANT_HOME%\bin %JAXRPC_HOME%\bin %JAXR_HOME%\bin

Using the Example Source Code with the JWSDP

To use the example source code with the Tomcat web container that is supplied with the JWSDP, you need to add a role name and two usernames and passwords to the web container’s authentication information, which you’ll find in the file %JWSDP_HOME%\conf\tomcat-users.xml. The lines that should be added to this file are highlighted in Example P-1.

Example 1. Adding authentication information to the tomcat-users.xml file

<?xml version='1.0'?>
<tomcat-users>
    <role rolename="admin"/>
    <role rolename="manager"/>
    <role rolename="provider"/>
    <role rolename="JWSGroup"/>
                  <user      username="JWSUserName" password="JWSPassword"
                      roles="admin,manager,provider,JWSGroup"/>
                  <user username="AnotherUser" password="Pwd"
          roles="admin,manager,provider,JWSGroup"/>  
</tomcat-users>

Note that the values JWSUserName and JWSPassword shown here must match the USERNAME and PASSWORD properties set in the jwsnutExamples.properties file. If you have substituted your own username and password, then you must use the same values in the tomcat-users.xml file.

Using the Source Code with J2EE Version 1.4

If you intend to use J2EE 1.4, you need to add two usernames and a group to the application server’s authentication information. The commands required to do this are shown next, where it is assumed that the bin directory of the J2EE installation has been added to your PATH environment variable:

realmtool -addGroup JWSGroup
realmtool -add JWSUserName JWSPassword JWSGroup
realmtool -add AnotherUser Pwd JWSGroup

Note that the values JWSUserName and JWSPassword shown here match those of the USERNAME and PASSWORD properties set in the jwsnutExamples.properties file. If you have substituted your own username and password, then you must use the same values here.

Using the Examples with a TCP Monitor Utility

It is sometimes useful to be able to see the SOAP messages that a web service client sends and receives. There are various monitoring utilities available that can be interposed between the client and the server to catch and print these messages as they are exchanged. One such utility is tcpmon, which is part of the Apache Axis distribution and can be downloaded from http://ws.apache.org/axis. A file in this distribution, axis.jar, contains the class files for tcpmon. To monitor the examples in this book using this utility, you need to select a free port on which tcpmon will listen and from which it will forward all messages to the server. Assuming you select port 5050 for tcpmon, you can start it using the following command:

java -classpath axis.jar org.apache.axis.utils.tcpmon 5050 localhost 8000

This command will display any messages sent to port 5050 and pass them on to port 8000 on localhost, which is the port on which the J2EE 1.4 reference implementation listens by default. If you are using the JWSDP, then you should forward the messages to port 8080 instead. Next, you need to ensure that the examples connect to port 5050 instead of the port assigned to the web container. To do this, edit the jwsnutExamples.properties file in your home directory and set either TOMCAT_WEBPORT (for the JWSDP) or J2EE_WEBPORT (for J2EE 1.4) to 5050. With these changes, you’ll see all of the SOAP messages sent and received by most of the examples in this book displayed in the tcpmon window. To revert to normal operation, just reset the value of TOMCAT_WEBPORT or J2EE_WEBPORT and stop tcpmon.