Deploying Web Services on Java 2, Enterprise Edition (J2EE)

Print-friendly Version

Since the first awkward attempts to define them when they were introduced in September 2000, Web services have gathered a great deal of momentum amongst developers -- so much, in fact, that JavaOne in March 2002 devoted an entire track of 63 sessions to the subject (see pointers to the session slides in For More Information). Accordingly, to coincide with a recent update to a key software package for developing Web services on Java 2, Sun has decided to update the basic instructions for deploying Web services on the Java 2 Platform, Enterprise Edition (J2EE).

The flexibility and scalability of the J2EE has made it the platform of choice for building multitiered enterprise applications; deploying Web services on the J2EE platform is a natural extension. The Java Web Services Developer Pack (Java WSDP) is an all-in-one download containing key technologies that simplify Web services development using the Java 2 Platform. Java WSDP is a collection of tools and APIs developed by Sun (and other members of the Java community) that allow you to build Web services quickly and easily.

You can either run the Java WSDP components on J2EE, or integrate the components with the J2EE. This article briefly introduces Web services and then shows how to:

• Set up the J2EE 1.3.1 environment for Web services (Java WSDP 1.0 FCS)
• Integrate Web services with J2EE, following guidelines of the Web Services Software Quality Engineering (SQE) team
• Deploy sample Web services on J2EE, following guidelines of the SQE team
• Run Web services on J2EE

The instructions provided here apply to both UNIX^R and Microsoft Windows. General instructions are for developers working on Microsoft Windows platforms, while UNIX exceptions to these instructions are preceded by the prefix UNIX. We made the screenshots on Windows, but since the Java WSDP uses Swing, UNIX developers should see the same screens.

Note: The instructions here are written for the Java WSDP 1.0 FCS. If you have been using an earlier version (such as Java WSDP EA1 or EA2), download the FCS version, as it has several improvements.

Introducing Web Services

Web services are computing services offered through the web that are accessible from any web-service-enabled machine with Internet access. Web services enable interoperability through a set of XML-based open standards. Businesses use the XML-based Web Services Description Language (WSDL) to describe their Web services on the Internet and list them in an XML-based registry such as the Universal Description, Discovery, and Integration (UDDI). UDDI allows you to find publicly available Web services as shown in Figure 1. A client sends a service request to the registry, which informs the client about the registered services that meet the criteria of the request. The Simple Object Access Protocol (SOAP) is then used to communicate (using HTTP and XML as the exchange mechanism) between the applications running on different platforms.

Figure 1: Web services protocols

If you need more background on Web services, look into some of the introductory resources under For More Information.

Downloading and Installing J2EE SDK 1.3.1 and the Java WSDP 1.0 FCS

If you haven't done so already, download and install the versions of J2EE and Java WSDP covered in these instructions: J2EE SDK 1.3.1, and the Java WSDP 1.0 FCS. Installation is self-explanatory (both packages have installation and configuration manuals). The most important configuration step is to ensure that the environment variables J2EE_HOME and JWSDP_HOME point to the correct installation directories, because many other environment variables depend on them.

Integrating Java WSDP with J2EE

The integration process consists of three major tasks: adding Java WSDP-related JAR files to J2EE, performing some minor port configurations, and setting some security permissions.

Note: If you like, you can run the script %JWSDP_HOME%\bin\jwsdponj2ee.bat (UNIX: $JWSDP_HOME/bin/jwsdponj2ee.sh). These scripts use an Ant build file (jwsdponj2ee.xml) located in the bin directory of your JWSDP installation. If you let Ant perform the configuration for you, skip down to the next section of the article to see how to package and deploy Web services on top of the J2EE platform. If you prefer to see what is happening behind the scenes, follow the instructions here to do the configurations manually. For more information on the Ant script and instructions on how to use it, please see %JWSDP_HOME\docs\jwsdponj2ee.html (UNIX: $JWSDP_HOME/docs/jwsdponj2ee.html).

To add the necessary Java WSDP-related JAR files, you start by creating two major JAR files (jwsdp-common.jar and jwsdp-endorsed.jar) out of several Java WSDP JAR files. Then you extract the contents of the two new JAR files to the right location and perform some configuration.

To create the jwsdp-common.jar file:

1. Create a temporary directory (for example: %JWSDP_HOME%\work\jwsdp_jars). (UNIX: $JWSDP_HOME/work/jwsdp_jars).

2. Extract the following JAR files from %JWSDP_HOME%\common\lib to %JWSDP_HOME%\work\jwsdp_jars. The %JWSDP_HOME% environment variable defines the absolute path to the JWSDP installation. For example, on our Windows machine it is c:\jwsdp. (UNIX: Extract $JWSDP_HOME/common/lib to $JWSDP_HOME/work/jwsdp_jars. The $JWSDP_HOME environment variable defines the home directory for the JWSDP installation.)

   • mail.jar
     This JAR file contains the JavaMail API and all service providers.

   • activation.jar
     This JAR file contains the classes that make up the JavaBeans Activation Framework (JAF).

   • dom4j.jar
     dom4j is an open-source XML framework for Java. It allows you to read, write, navigate, create, and modify XML documents. It integrates with DOM and SAX and is seamlessly integrated with full XPath support. The dom4j.jar file contains all the dom4j code and the XPath engine without the SAX and DOM interfaces. This is the JAR file to use if you are using JAXP and crimson.jar or xerces.jar.

   • saaj-api.jar and saaj-ri.jar
     These two JAR files contain the APIs and Reference Implementation of SOAP with Attachments API for Java (SAAJ), which provide API and implementation to generate SOAP messages.

   • jaxrpc-api.jar and jaxrpc-ri.jar
     These two JAR files contain the JAX-RPC APIs and Reference Implementation of Java API for XML-based Remote Procedure Call (RPC), which enable Java developers to build web applications and Web services that incorporate XML-based RPC functionality according to the SOAP specification.

   • jaxm-api.jar and jaxm-runtime.jar
     These two JAR files contain the APIs and Reference Implementation of the Java API for XML Messaging (JAXM), which is an XML-based messaging system for sending and receiving SOAP messages.

   • jaxr-api.jar and jaxr-ri.jar
     These two files contain the APIs and Reference Implementation for JAXR or the Java API for XML Registries, which provides a uniform standard API for accessing different kinds of XML registries. It includes detailed bindings between the JAXR information model and both the ebXML Registry and the UDDI registry specifications.

   • jaxp-api.jar
     JAXP is the Java API for XML Processing. It supports processing of XML documents using DOM, SAX, and XSLT.

   • castor-0.9.3.9-xml.jar
     Castor is an XML data-binding framework. Unlike DOM and SAX, which deal with the structure of an XML document, Castor enables you to deal with the data defined in an XML document through an object model that represents that data. Castor can marshal almost any beanlike Java object to and from XML.

   • commons-logging.jar
     This JAR file contains a logging library package.

   • fscontext.jar and providerutil.jar
     These two files contain the file-system service provider.

3. Extract the following JAR files from %JWSDP_HOME%\tools\jstl  to %JWSDP_HOME%\work\jwsdp_jars. (UNIX: Extract the following JAR files from $JWSDP_HOME/tools/jstl to $JWSDP_HOME/work/jwsdp_jars.)

   • jstl.jar

   • standard.jar
     These two JAR files provide implementation for the Standard Tag Library for JavaServer Pages.

   • jaxen-full.jar
     This JAR file contains the classes that make up Jaxen -- a Java XPath Engine that is capable of evaluating XPath expressions across multiple modes (dom4j, JDOM, and so on).

   • saxpath.jar
     This JAR file contains the classes that make up SAXPath -- a Simple API for XPath. SAXPath is an event-based model for parsing XPath expressions.

   • jdbc2_0-stdext.jar
     This JAR file contains the classes that make up the JDBC standard extensions.

4. Extract the following JAR files needed for the Registry Server from %JWSDP_HOME%\common\lib  to %JWSDP_HOME%\work\jwsdp_jars. (UNIX: Extract the following JAR files needed for the Registry Server from $JWSDP_HOME/common/lib to $JWSDP_HOME/work/jwsdp_jars.)

   • openorb.jar
     This JAR file contains the implementation of OpenORB -- a CORBA Object Request Broker developed in Java. It complies with the CORBA 2.4.2 specification and provides many features, services, and extensions.

   • xindice.jar
     This JAR file contains the classes that make up xindice -- a database server designed from the ground up to store XML data.

   • xmldb.jar
     This JAR file contains the classes that make up the XML:DB initiative for XML databases. It provides APIs for managing data in an XML database.

   • xmldb-xupdate.jar
     This JAR file contains the classes that make up XUpdate. XUpdate is an XML Update Language for XML documents.

5. Extract the JAR file provider.jar from %JWSDP_HOME%\services\jaxm-provider\WEB-INF\lib to %JWSDP_HOME%\work\jwsdp_jars (UNIX: Extract $JWSDP_HOME/services/jaxm-provider/WEB-INF/lib/provider.jar to $JWSDP_HOME/work/jwsdp_jars.)

   The provider.jar file is a JAXM provider, which is a messaging service that routes and transmits messages, completely transparent to the client. You need a JAXM provider only when your application requires asynchronous (or one-way) messaging.

6. Change directory to %JWSDP_HOME%\work\jwsdp_jars (UNIX: $JWSDP_HOME/work/jwsdp_jars).

7. Create jwsdp-common.jar from the contents of the directory %JWSDP_HOME%\work\jwsdp_jars (UNIX: $JWSDP_HOME/work/jwsdp_jars) as follows:
   jar -cvf %JWSDP_HOME%\work\jwsdp-common.jar . Note the dot at the end of the command.

   (UNIX: jar -cvf $JWSDP_HOME/work/jwsdp-common.jar . Note the dot at the end of the command.)

   Now, you have jwsdp-common.jar in %JWSDP_HOME%\work  (UNIX: $JWSDP_HOME/work).

To create the jwsdp-endorsed.jar file:

1. Create a temporary directory (for example, %JWSDP_HOME%\work\endorsed_jars or, in UNIX, $JWSDP_HOME/work/endorsed_jars).

2. Extract the following JAR files from %JWSDP_HOME%\common\endorsed  to %JWSDP_HOME%\work\endorsed_jars (UNIX: Extract the following JAR files from $JWSDP_HOME/common/endorsed to $JWSDP_HOME/work/endorsed_jars).

   • sax.jar
     SAX is the Simple API for XML. This JAR file contains implementation of SAX.

   • dom.jar
     DOM is the Document Object Model. This file contains the implementation of DOM.

   • xercesImpl.jar
     This JAR file contains all the parser class files that implement one of the standard APIs supported by the parser.

   • xalan.jar
     This JAR file contains XSLT stylesheet processors. It implements XSLT and XPath.

   • xsltc.jar
     This JAR file provides a compiler and a runtime processor for XSL stylesheets.

3. Change directory to %JWSDP_HOME%\work\endorsed_jars (UNIX: $JWSDP_HOME/work/endorsed_jars).

4. Create jwsdp-endorsed.jar from the contents of the directory %JWSDP_HOME%\work\endorsed_jars (UNIX: $JWSDP_HOME/work/endorsed_jars) as follows:

   jar -cvf %JWSDP_HOME%\work\jwsdp-endorsed.jar .

   Note the dot at the end of the command.

   (UNIX: jar -cvf $JWSDP_HOME\work\jwsdp-endorsed.jar .)

   Now, you have jwsdp-endorsed.jar in %JWSDP_HOME%\work (UNIX: $JWSDP_HOME/work).

To extract the JAR files to the right location and set the class path:

1. Extract jwsdp-common.jar from

   %JWSDP_HOME%\work (UNIX: $JWSDP_HOME/work)
   to
   %J2EE_HOME%\lib\system (UNIX: $J2EE_HOME/lib/system)

2. Extract the following JAR files from

   %JWSDP_HOME%\common\lib (UNIX: $JWSDP_HOME/common/lib)
   to
   %J2EE_HOME%\lib\system (UNIX: $J2EE_HOME/lib/system)

   Note: The following JAR files are included as part of J2SE 1.4, so you only need to extract them if you are using J2SE 1.3.

   • jaas.jar
     This JAR file contains the classes that make up the Java Authentication and Authorization Service (JAAS), which is a package that enables services to authenticate and enforce user access controls.

   • jsse.jar
     This JAR file contains the class that makes up the Java Secure Socket Extension (JSSE) to enable secure Internet communications. JSSE implements a Java version of the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols and includes functionality for data encryption, server authentication, message integrity, and optional client authentication.

     The following two JAR files -- jcert.jar (for handling certificates) and jnet.jar (socket factories) -- are part of JSSE.

   • jcert.jar

   • jnet.jar

3. Create a directory called endorsed in the %J2EE_HOME%\lib\system directory
   (UNIX: $J2EE_HOME/lib/system). This system property, introduced in the J2SDK 1.4, specifies the directories where the Java runtime system will search for JAR files.

4. Extract jwsdp-endorsed.jar from

   %JWSDP_HOME%\work (UNIX: $JWSDP_HOME/work)
   to
   %J2EE_HOME%\lib\system\endorsed (UNIX: $J2EE_HOME/lib/system/endorsed)

5. Open the J2EE environment configuration script file %J2EE_HOME%\bin\setenv.bat
   (UNIX: $J2EE_HOME/bin/setenv.sh), where J2EE environment variables are set, and insert jwsdp-endorsed.jar at the beginning of the CPATH:

   set CPATH = %SYSTEM_LIB_DIR%\endorsed\jwsdp-endorsed.jar;%CLOUDJARS%;%CLASSESDIR%;

   The rest of the CPATH should remain the same.

   (UNIX: CPATH=$SYSTEM_LIB_DIR/endorsed/jwsdp-endorsed.jar and so on.)

6. Open the user configuration script file %J2EE_HOME%\bin\userconfig.bat
   (UNIX: $J2EE_HOME/bin/userconfig.sh) and add the JAR file jwsdp-common.jar to the J2EE_CLASSPATH by performing the following changes:

   • Uncomment J2EE_CLASSPATH by removing rem from the beginning of the line that sets the J2EE_CLASSPATH. (UNIX: uncomment J2EE_CLASSPATH and export J2EE_CLASSPATH.)

   • Add a new line to define the SYSTEM_LIB_DIR right before the J2EE_CLASSPATH as follows:

     set SYSTEM_LIB_DIR=%J2EE_HOME%\lib\system

     (UNIX: SYSTEM_LIB_DIR=$J2EE_HOME/lib/system)

   • Set the J2EE_CLASSPATH as follows:

     set J2EE_CLASSPATH=%SYSTEM_LIB_DIR%\jwsdp-common.jar

     (UNIX: J2EE_CLASSPATH=$SYSTEM_LIB_DIR/jwsdp-common.jar)

7. Open the J2EE server script file %J2EE_HOME%\bin\j2ee.bat (UNIX: $J2EE_HOME/bin/j2ee.sh), locate the %JAVA_COMMAND% (UNIX: JAVACMD), which is the last line in the file, and specify the system property java.endorsed.dirs as follows:

   %JAVA_COMMAND%-Djava.endorsed.dirs=%J2EE_HOME%\lib\system\endorsed
   (...the rest of line remains the same...) -classpath %CPATH% com.sun.enterprise.server.J2EEServer and so on

   (UNIX: $JAVACMD -Djava.endorsed.dirs=$J2EE_HOME/lib/system/endorsed and so on).

   Note: The system property java.endorsed.dirs specifies one or more directories where the Java runtime environment searches for JAR files. You must set this system property only when running J2EE SDK 1.3.x on the J2SE 1.4.

To configure the web server port and set security permissions:

1. Open the file %J2EE_HOME%\config\web.properties
   (UNIX: $J2EE_HOME/config/web.properties), change the http.port number from 8000 to 8080 because the Tomcat web server, which is used by Java WSDP, runs on port 8080 by default and some of the Java WSDP sample applications use that port. You use the web.properties file to set properties (such as port numbers, root HTML directory, log files, and so on) for the web. Therefore, http.port=8080 is the port that the HTTP service uses to service requests.

2. Open the file %J2EE_HOME%\lib\security\server.policy
   (UNIX: $J2EE_HOME/lib/security/server.policy) and specify the following permissions in the default domain (sentence with grant { ) toward the end of the file):

   permission java.io.FilePermission "<ALL FILES>", "read,write,delete"; permission java.util.PropertyPermission "*", "read,write"; permission java.lang.RuntimePermission "modifyThreadGroup"; //Permission needed for running Registry Server permission java.net.SocketPermission "*", "listen, connect, resolve";

   
   

   and then give full permissions for jwsdp-common.jar and jwsdp-endorsed.jar by adding the following at the end of file:

   grant codeBase "file:${com.sun.enterprise.home}/lib/system/jwsdp-common.jar" { permission java.security.AllPermission; }; grant codeBase "file:${com.sun.enterprise.home}/lib/system/endorsed/jwsdp-endors ed.jar" { permission java.security.AllPermission; };

   
   

   The server.policy is a Java security-policy file for the J2EE server. It contains Java security-policy settings for the J2EE engine, as well as permissions for specific access that are granted to a program.

   The first line added to the security-policy file is granting read, write, and delete permissions on any file. The second line allows for reading and writing any system property. The read permission allows System.getProperty to be called, and the write permission allows System.setProperty to be called. The third line is for runtime permissions. In this case, this property allows modification of thread groups through calls to ThreadGroup destroy, getParent, resume, setDaemon, setMaxPriority, stop and suspend methods.

   You need all of these permissions to run the JAXM Provider Admin tool, jaxm-remote, and jaxm-soaprp, which are examples that come with the Java WSDP.

Packaging and Deploying Web Services

Before we explain how to start deploying Web services on J2EE, let's review the steps required to deploy a service on top of the J2EE. You would follow the same steps to deploy other components introduced later in this article. (If you have plenty of J2EE experience and don't need a refresher on this technique, skip down to the next section, which details instructions for deploying one of the specific tools you need for Web services, Deploying JAXM Provider and Admin Tool.)

Deploying a Service on J2EE

When you deploy a service on J2EE, you create a new application EAR file with deploytool, and then you associate it with the appropriate WAR file and set its web context. The deploytool communicates with the J2EE server for deploying and undeploying components on J2EE.

Note: Keep in mind that jaxrservlet is an imaginary file dreamed up just for this example; the file does not actually exist in Java WSDP 1.0 FCS.

To deploy a service on the J2EE SDK container:

1. If it is not already running, start the J2EE server by going to %J2EE_HOME%\bin
   (UNIX: $J2EE_HOME/bin) and executing the command j2ee. The J2EE server must be running before you start the deploytool. The J2EE server may take several seconds to start. Wait until you see the message J2EE server startup complete, as follows:

   c:\j2sdkee1.3.1\bin> j2ee J2EE server listen port: 1050 Redirecting the output and error streams to the following files c:\j2sdkee1.3.1\logs\java\j2ee\j2ee\system.out c:\j2sdkee1.3.1\logs\java\j2ee\j2ee\system.err J2EE server startup complete.

   
   

2. Go to the directory %J2EE_HOME%\bin (UNIX: $J2EE_HOME/bin) and start the deploytool by executing the command deploytool.

3. Select File -> New Application to create a new application EAR file as shown in Figure 2.

   Note: We took the screenshots for this article on Windows, but because the deploytool uses Swing, they ought to look the same on UNIX. 

   
   Figure 2: Creating a new EAR file

4. In the box that appears, enter a name for the EAR file you're creating and the name you want the deploytool window to display for it. Enter any names you like. As shown in Figure 3, we have created a directory called ear-files where we store all EAR files, we have named the file jaxrservlet, and we want the display name to be the same as the file's.

   
   Figure 3: Choosing a file name

5. Add the WAR file (in this example, jaxrservlet.war) to the application. To do this, select File -> Add to Application -> Web War and then navigate to location of the WAR file and select it.

6. Set the web context:

   1. Select the application (our hypothetical jaxrservlet app, in this example).
   2. Select the Web Context tab.
   3. Enter the context in the Context Root field as shown in Figure 4.
      
      Figure 4: Setting the web context

7. Go to the Tools menu and select Deploy to deploy the application. A progress box reports how deployment is going, and tells you when the deployment is complete, as shown in Figure 5.

   
   Figure 5: The application has been deployed

Deploying JAXM Provider and Admin Tool

A JAXM Provider is a messaging provider required for asynchronous messaging. The JAXM Provider Admin Tool allows you to configure the provider. Before running the JAXM Provider Admin Tool, you deploy the JAXM Provider and the JAXM Provider Admin Tool into separate J2EE applications. Follow these instructions whenever you need to run an application that uses a JAXM provider.

To deploy the JAXM Provider:

1. Configure the JAXM Provider service to use port 8080: Open the file %JWSDP_HOME%\services\jaxm-provider\WEB-INF\provider.xml (UNIX: $JWSDP_HOME/services/jaxm-provider/WEB-INF/provider.xml) and then change
   http://127.0.0.1:8081/jaxm-provider/receiver/ebxml
   to
   http://127.0.0.1:8080/jaxm-provider/receiver/ebxml

   and also change

   http://127.0.0.1:8081/jaxm-provider/receiver/soaprp
   to
   http://127.0.0.1:8080/jaxm-provider/receiver/soaprp

2. Go to the %JWSDP_HOME%\services\jaxm-provider (UNIX: $JWSDP_HOME/service/jaxm-provider) directory and package the JAXM Provider into a WAR file by executing:

   jar cvf jaxm-provider.war .

   Note the dot at the end of the command.

3. Copy jaxm-provider.war to some location, say c:\jaxm_services, and delete it from %JWSDP_HOME%\services\jaxm-provider (UNIX: Copy jaxm-provider.war to a location such as $HOME/jaxm_services and delete it from $JWSDP_HOME/services/jaxm-provider). This step is necessary to prevent loading this service from your Java WSDP installation.

4. Package the jaxm-provider.war into an enterprise application with the context jaxm-provider and deploy it following the steps for deploying a service in the J2EE SDK container.

To deploy the JAXM Provider Admin Tool:

1. Configure the jaxm-provideradmin service to use port 8080. To do this, open the file %JWSDP_HOME%\services\jaxm-provideradmin\WEB-INF\provider.xml (UNIX: $JWSDP_HOME/services/jaxm-provideradmin/WEB-INF/provider.xml) and then change:
   http://127.0.0.1:8081/jaxm-provider/receiver/ebxml
   to
   http://127.0.0.1:8080/jaxm-provider/receiver/ebxml

   and also change

   http://127.0.0.1:8081/jaxm-provider/receiver/soaprp
   to
   http://127.0.0.1:8080/jaxm-provider/receiver/soaprp

2. Go to the %JWSDP_HOME%\services\jaxm-provideradmin (UNIX: $JWSDP_HOME/services/jaxm-provideradmin) directory and package the WAR file: jar cvf jaxm-provideradmin.war .

   Note the dot at the end of the command.

3. Copy the jaxm-provideradmin.war to some location, say c:\jaxm_services (UNIX: $HOME/jaxm_services), and delete it from %JWSDP_HOME%\services\jaxm-provideradmin (UNIX: $JWSDP_HOME/services/jaxm-provideradmin). Again, this step is necessary to prevent loading this service from your Java WSDP installation.

4. Package the jaxm-provideradmin.war into a new enterprise application with the context jaxm-provideradmin using deploytool as in previous examples.

5. Add the user j2ee to the provider role. To do this, select the jaxm-provideradmin application in deploytool. In the Security tabbed pane, select the provider role from the Role Name list. If the provider role is not shown, click on EditRoles and define provider. Make sure the jaxm-provideradmin archive is selected. Once the provider is added, you will be taken to the main security menu. Select the provider under role name and click on Add to select the j2ee user in the Users dialog box.

6. Ensure that the JAXM Provider application is deployed. Click Servers and look for jaxm-provider in the list of applications that have been deployed.

7. Deploy the JAXM Provider Admin Tool application (as detailed in the instructions for deploying a service on J2EE). Make sure the web context is jaxm-provideradmin.

To deploy Registry Server:

1. Package the registry-server.war, which is under %JWSDP_HOME%\webapps (UNIX: $JWSDP_HOME/webapps ) into an enterprise application with the context registry-server and deploy it following the steps for deploying a service in the J2EE SDK container.

   Note: Registry Server uses native XML database xindice as the repository. You must start the xindice database server before you can start the Registry Server, using the command %JWSDP_HOME%\bin\xindice-start.bat (UNIX: $JWSDP_HOME/bin/xindice-start.sh ).

Running the JAXM Admin Tool

Once the JAXM Provider and Admin Tool have been deployed, you can run the JAX Admin Tool.

To run the JAX Admin Tool:

1. Point your browser to http://127.0.0.1:8080/jaxm-provideradmin.

2. At the prompt, enter a login name and a password, as shown in Figure 6. In the example, we use j2ee as a login name and password. Once the network has verified your login name and password, you will be logged into the JAXM Admin Tool.

   
   Figure 6: JAXM Admin Tool Login

3. Configure the messaging provider as shown in Figure 7.

   
   Figure 7: JAXM Admin Tool

Running JAXM Samples

The Java WSDP download includes a set of JAXM examples in the %JWSDP_HOME\webapps directory (UNIX: $JWSDP_HOME/webapps). The examples illustrate various kinds of applications you can write with the JAXM API. This section explains how to run the examples on J2EE SDK 1.3.x.

jaxm-simple
This is a simple example of sending and receiving a message using the local messaging provider.

To deploy the jaxm-simple example:

1. Package jaxm-simple.war into an enterprise application, once again using the deploytool.
   The file jaxm-simple.war is available in %JWSDP_HOME%\webapps (UNIX: $HWSDP_HOME/webapps).

2. Set the context to jaxm-simple.

3. Deploy the application on J2EE.

Once deployed, you can run it the same way you would run it with the Java WSDP.

To run the jaxm-simple application:

1. Point your web browser to http://127.0.0.1:8080/jaxm-simple.
   A screen similar to Figure 8 appears.

2. Follow the link "here," and you should see a window similar to Figure 9.
   You can find the sent.msg and reply.msg  in %J2EE_HOME\bin (UNIX: $J2EE_HOME/bin).

Figure 8: Running jaxm-simple

Figure 9: Output of jaxm-simple

jaxmtags
This example uses JSP tags to generate and consume a SOAP message.

To deploy the jaxmtags example:

1. Package jaxmtags.war into an enterprise application.
2. Set the context to jaxmtags.
3. Deploy the application to J2EE SDK 1.3.x.

Now, you can run the example the same way you would run it with Java WSDP.

To run the jaxmtags application:

1. Point your browser to http://127.0.0.1:8080/jaxmtags to see a screen similar to Figure 10.

2. Click one of the three links to send a message and see the response displayed.

Figure 10: Running jaxmtags

jaxm-remote
This is an example of a round-trip message that uses a JAXM messaging provider that supports the basic ebXML profile to send and receive a message.

To deploy the jaxm-remote service:

1. Copy %JWSDP_HOME%\webapps\jaxm-remote.war to some location say, c:\remote
   (UNIX: Copy $JWSDP_HOME/webapps/jaxm-remote.war to a location such as $HOME/remote).

2. Go to the directory c:\remote (UNIX: $HOME/remote).

3. Extract the jaxm-remote.war file: jar xvf jaxm-remote.war.

4. Delete the WAR file: c:\remote> del jaxm-remote.war
   (UNIX: $HOME/remote$ rm jaxm-remote.war).

5. In the file c:\remote\WEB-INF\classes\client.xml (UNIX: $HOME/remote/WEB-INF/classes/client.xml) change

   http://127.0.0.1:8081/jaxm-provider/sender
   to
   http://127.0.0.1:8080/jaxm-provider/sender

6. Package the jaxm-remote.war file:

   c:\remote> jar cvf jaxm-remote.war .

   Note the dot at the end of the command.

7. Package the WAR file into an enterprise application.

8. Set the context to jaxm-remote.

9. Deploy the application to J2EE SDK 1.3.x.

To run the jaxm-remote application:

Point your browser to http://127.0.0.1:8080/jaxm-remote.

jaxm-soaprp
This is an example of a round-trip message that uses a JAXM messaging provider that supports the basic SOAP-RP profile to send and receive a message.

To deploy the jaxm-soaprp service:

1. Copy %JWSDP_HOME%\webapps\jaxm-soaprp.war to some location, for instance, c:\soaprp (UNIX: Copy $JWSDP_HOME/webapps/jaxm-soaprp.war to a location such as $HOME/soaprp).

2. Go to the c:\soaprp directory (UNIX: $HOME/soaprp).

3. Extract the jaxm-soaprp.war file: jar xvf jaxm-soaprp.war

4. Delete the WAR file: c:\soaprp> del jaxm-soaprp.war
   (UNIX: $HOME/soaprp$ rm jaxm-soaprp.war).

5. Open the file c:\soaprp\WEB-INF\classes\client.xml (UNIX: $HOME/soaprp/WEB-INF/classes/client.xml) and then change

   http://127.0.0.1:8081/jaxm-provider/sender
   to
   http://127.0.0.1:8080/jaxm-provider/sender

6. Package the jaxm-soaprp.war file:

   c:\soaprp> jar cvf jaxm-soaprp.war .

   Note the dot at the end of the command.

7. Package the WAR file into an enterprise application.

8. Set the context to jaxm-soaprp.

9. Deploy the application to J2EE SDK 1.3.x.

To run the jaxm-soaprp application:

1. Open a browser window.
2. Set it to http://127.0.0.1:8080/jaxm-soaprp.

jaxm-translator
This is an example of a simple translation service that translates text into different languages. The translation service talks to babelfish.altavista.com, making an HTTP connection, and extracts the translations of the input text string from the response. The text is translated to German, Italian, and French. Obvsiously, for this service to work, you must be connected to the Internet.

To deploy the translation service:

1. Package jaxm-translator.war into an enterprise application using the deploytool.

2. Set the context to jaxm-translator.

3. Deploy the application on J2EE SDK 1.3.x.

You run the example in the same way you would run it with the Java WSDP.

To run the translation service:

1. Make sure you have a live Internet connection.

2. Point your web browser to http://127.0.0.1:8080/jaxm-translator. You will get a screen similar to Figure 11 (here we entered the text goodbye to be translated).

3. Enter some text for translation.

4. Click a radio button to select how you want the translation returned: within the SOAPBody or as an attachment to the JAXM message.

5. If you're using a proxy host, enter the Proxy Host and Proxy Port. (Leave them blank if you're not using a proxy.)

6. Click Translate to execute the service. The output looks like Figure 12.


Figure 11: Running the translation web service
Figure 12: Output of the translation service

Conclusion

By following the step-by-step instructions in this article, you have learned how to configure the J2EE SDK 1.3.1 so that Web services can be deployed on top of it, and how to deploy sample Eeb-service applications that come with the Java Web Services Developer Pack.

Now you have the tools to build new Web services and the basic knowledge of how to deploy them on top of the J2EE platform. You'll learn quickly as you experiment, and you can learn more from other resources listed under For More Information, including the slides for more than 60 sessions on Web services that took place at JavaOne in March 2002.

For More Information

• Java Web Services Developer Pack (JWSDP)
• Java 2 Enterprise Edition (J2EE)
• The full track of 63 March 2002 JavaOne sessions on Web services
• Slides for the March 2002 JavaOne session on developing web applications using the Java WSDP

About the Authors

Qusay H. Mahmoud provides Java consulting and training services. He has published dozens of articles on Java, and is the author of Distributed Programming with Java (Manning Publications, 1999) and Learning Wireless Java (O'Reilly, 2002).

Ramesh Mandava is a staff engineer at Sun Microsystems. Currently, Ramesh leads the Web services SQE team, which ensures that Web services deliverables from Sun meet customer quality expectations and needs.