One of the technologies available in J2EE for developing and deploying web services is Java API for XML-Based RPC (JAX-RPC). However, using JAX-RPC technology requires a developer to specify a lot of information in deployment descriptors such as webservices.xml, web.xml, and ejb-jar.xml. These requirements are seen by many programmers as cumbersome and confusing.

To simplify the web services programming model, the Java API for XML Web Services (JAX-WS) was introduced. The main focus of JAX-WS technology is ease of web services development and deployment. A lot of this simplicity results from annotations. An earlier Tech Tip, "Developing Web Services Using JAX-WS" showed some of these annotations in use. These and other JAX-WS features have eliminated the requirement for deployment descriptors.

JAX-WS technology was initially made available in the Java Web Services Developer Pack (Java WSDP) Version 2.0. This allowed early adopters to develop JAX-WS-based web services and deploy them on J2EE 1.4 implementations such as the J2EE 1.4 SDK (which includes the Sun Java System Application Server 8.2 Platform Edition) or Apache Tomcat. However, because JAX-WS technology became available after the release of J2EE 1.4, using it with that level of the platform required the addition of some platform-specific information in various deployment descriptors. Unfortunately, that platform-specific information restricts porting to Java EE 5 of any JAX-WS-based web services developed using Java WSDP 2.0.

This Tech Tip describes what you need to do to change a JAX-WS-based web service developed using Java WSDP 2.0 and deployed on the J2EE 1.4 platform so that it can be ported to the Java EE5 platform.

Getting Started

A sample package accompanies this tip to help demonstrate the migration process. It contains the source code and associated files for building a web service. Two versions of the code and files are provided. One version is for building a web service using Java WSDP 2.0 and deploying it on Java System Application Server 8.2 Platform Edition. The other version is for building and deploying a web service on GlassFish, an open source reference implementation of Java EE 5.

If you haven't already done so, download and install the following:

• J2EE 1.4 SDK or Java Application Server 8.2 Platform Edition, from the J2EE 1.4 Downloads page. After installing it, set the S1AS_HOME environment variable to the directory in which you installed the J2EE 1.4 SDK or Java Application Server 8.2 Platform Edition.


• Java WSDP 2.0, from the Java Web Services Developer Pack Downloads page.


• GlassFish, from the GlassFish Community Downloads page. After installing it, set the GLASSFISH_HOME environment variable to the directory in which you installed GlassFish.

Building a Web Service With Java WSDP 2.0

To build the web service, you need to:

1. Write an endpoint implementation class.
2. Compile the endpoint implementation class.
3. Generate portable artifacts required for web service
execution.
4. Package the web service as a WAR file and deploy it.

    %S1AS_HOME%\bin\asadmin start-domain  

    <sample_install_dir>\jwsdp-82\asant service  

    %S1AS_HOME%\bin\asadmin deploy     <sample_install_dir>\jwsdp-82\build\jwsdp-add.war 

    <listener>     <listener-class>     com.sun.xml.ws.transport.http.servlet.WSServletContextListener     </listener-class>    </listener> 

    <servlet>      <servlet-name>AddService</servlet-name>      <servlet-class>       com.sun.xml.ws.transport.http.servlet.WSServlet      </servlet-class>      <load-on-startup>1</load-on-startup>    </servlet> 

Making the Web Service Portable

The specification "Implementing Enterprise Web Services", JSR-109, specifies the programming model for implementing a web service in Java EE 5. To make a web service developed using Java WSDP 2.0 and deployed on the J2EE 1.4 platform deployable on the Java EE5 platform, you need to ensure that it conforms to the JSR-109 specification.

You still need to provide an endpoint implementation class and compile it. However based on JSR-109, you no longer package the vendor-specific descriptor file, sun-jaxws.xml. All information required about the endpoint is derived by the platform implementation from the @WebService annotation in the endpoint implementation class.

• The web.xml file points to the latest servlet schema:

        <web-app xmlns="http://java.sun.com/xml/ns/javaee"       xmlns:j2ee="http://java.sun.com/xml/ns/javaee"       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"       version="2.5" xsi:schemaLocation=      "http://java.sun.com/xml/ns/javaee       http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> 

  This is important because annotation processing will happen only for applications that use Java EE5-based descriptors.



• There is no need for the <listener> element in the web.xml file. All the required initializations are done as part of the deployment of the web service in Java EE platform.



• A <servlet> element is required in which the <servlet-name> is the port-component-name of the web service endpoint (that is, @WebService.name). For example:

        <servlet>      <servlet-name>AddNumbers</servlet-name>      <servlet-class>endpoint.AddNumbers</servlet-class>      <load-on-startup>1</load-on-startup>      </servlet> 

  If you don't provide a <servlet-name> element, the name defaults to the simple name of the endpoint implementation class, and the <servlet-class> defaults to the full name of the endpoint implementation class.

You can see this by examining the files provided in the jwsdp-gf directory of the sample archive. Notice that there is no sun-jaxws.xml file. Also notice that in the jwsdp-web.xml file there is no <listener> element, and the <servlet> element follows the rules mentioned previously.

One other important item of note: You have the option of running the wsgen tool to generate portable artifacts or not. If you don't run wsgen, the Java EE 5 platform implementation will generate portable artifacts for you at the time of deployment.

You can build and deploy the same JAX-WS-based web service as you did for J2EE 1.4. This time you'll build and deploy it in Java EE 5, using the files in the jwsdp-gf directory. You can find the endpoint implementation class, AddNumbers, in the jwsdp-web.xml file\endpoint directory.

Start GlassFish as follows:

     %GLASSFISH_HOME%\bin\asadmin start-domain  

Then execute the following commands:

    <sample_install_dir>\jwsdp-gf\asant service          %GLASSFISH_HOME%\bin\asadmin deploy     <sample_install_dir>\jwsdp-gf\build\javaee-add.war 

Notice that the service task does not run wsgen. There is no wsgen in the build file for the task. The portable artifacts are generated automatically when you deploy the WAR file.

After you deploy the web service, you can view its generated WSDL file by pointing your browser to the URL http://localhost:8080/javaee-add/addnum?wsdl.

• Not requiring you to package all portable artifacts. Because of that, you do not need to run platform-specific tools such as wsgen.
• Not requiring you to package platform-specific descriptors such as sun-jaxws.xml.
• Not requiring a web.xml file for packaging. However, if you provide a web.xml for packaging, its contents do not have any platform-specific information.

Vijay Ramachandran is a senior member of the Sun Java Application Server team. He has worked in the J2EE group for the last six years, and was a key contributor to the deployment and web services-related features of Sun Java System Application Server versions 8.X and 9.X. Previously, Vijay was the technical lead for Java BluePrints team, where he co-authored books on the J2EE 1.3 and 1.4 platforms.

Step 1: Getting Started

If you haven't already done so, download GlassFish from the GlassFish Community Downloads page.

• GLASSFISH_HOME: This should point to where you installed GlassFish (for example C:\Sun\AppServer)


• JAVA_HOME: This should point to the location of JDK 5.0 on your system.

Step 2: Start GlassFish

    <GF_install_dir>/bin/asadmin start-domain domain1 

    http://localhost:4848 

Then login with the appropriate administrator user name and password (the default username is admin, and the default password is adminadmin).

Step 4: Enable Call Flow

You can enable Call Flow either in the Administration Console or by command.

1. In the tree component, select the Application Server node.
2. Click the Monitor tab.
3. Click the Call Flow tab. The Call Flow page appears.
4. Check the Enabled checkbox in the Configuration section of the page to initiate Call Flow monitoring for the server.
5. Optionally, specify the client host IP address and user ID for which you want to enable monitoring. Doing this can be very useful in a production system to track the flow (and possible performance problems) for a particular type of request.
6. Click Save

     <GF_install_dir>/bin/asadmin asadmin     start-callflow-monitoring server 

Step 5: Download and Deploy the Sample Archive

Download the sample archive for the tip. The sample archive is a deployable archive for an enterprise application that you will monitor with Call Flow.

After you download the sample archive deploy it. You can do this in various ways. For example, you can copy the sample archive to the GlassFish autodeploy directory (<GF_install_dir>/domains/domain1/autodeploy), or you can use the Administration Console to deploy the sample archive.

Step 6. Run the Application

Run the deployed application by entering the URL http://localhost:8080/helloworld in a browser window other than the one running the Administration Console. You should see a page that says "Hello World Sample Application". You should also see a prompt to enter a name.

    Hello World !     Good morning, Duke. Enjoy your morning.  

Step 7: Display Call Flow Data

Use the Administration Console to view the data that was recorded by Call Flow. Although Call Flow needs to be enabled to monitor and record call flow data, it doesn't need to be enabled for you to view data it already recorded. So you can optionally disable Call Flow before you view the data. (See "Step 8: Disable Call Flow" for instructions on how disable Call Flow.)

You can find the call flow data in the Call Flow Data section of the Call Flow page in the Administration Console. The data is displayed in a table, with each row of the table displaying data for a specific request. You should see a row of data for the Hello World sample application that you ran.

The table includes data such as the time stamp when the request was processed by the application server, the principal used to send the request (a call that is made without any user principal is displayed in the table as "anonymous"), and the name of the application to which the request was sent to.

• The final status of a request, that is, Success or Failure


• The start container, that is, the container in which the request originated. The containers are WEB, Web Service, EJB, Timer EJB, and Asynchronous Message. Note that JMS messages directed to the application server are flagged as asynchronous messages. So if you want data displayed about JMS messages, select Asynchronous Message as the start container. Also, if you want data about IIOP messages displayed (as well as data about EJB requests), select EJB as the start container.

You can display more detailed data about a request by clicking on the entry for the request in the Time Stamp column. In response, you should see a Call Flow Details page that displays information such as the response time for the request, and how much time the request spent in each container. You'll also see a table that presents in sequence the call flow of the request through the containers. For each step in the calling sequence, the table displays the pertinent container, component, and method.

You can display the a parent-child view of the methods called in the call flow by clicking the View Tree button.

Step 8: Disable Call Flow

As is the case for enabling Call Flow, you can disable it from the Administration console or by command. To display Call Flow from the Administration Console, uncheck the Enabled checkbox on the Call Flow configuration page.

    <GF_install_dir>/bin/asadmin asadmin     stop-callflow-monitoring server 

Note that Call Flow is automatically disabled when you stop the application server. After you next start the application server, you can reenable Call Flow by rechecking the Enabled checkbox on the Call Flow configuration page.

Additional Information About Call Flow

About the Authors

Harpreet Singh is a member of Sun Java System Application Server group at Sun Microsystems. He has been involved in J2EE development from the last seven years. His current interests are call flow monitoring and web services management. In the past, he has been a key contributor in security infrastructure of the Application Server.

Anissa Lam is a member of the Sun Java System Application Server group at Sun Microsystems. She has worked in the J2EE group for the last five years, focusing on various IDEs, such as Sun Java Studio, and deployment tools. Anissa has been a key contributor to the Administration Console function of the Application Server.

• Core Java Technologies Tech Tips. Get tips on using core Java technologies and APIs, such as those in the Java 2 Platform, Standard Edition (J2SE).
• Wireless Developer Tech Tips. Get tips on using wireless Java technologies and APIs, such as those in the Java 2 Platform, Micro Edition (J2ME).