Developing J2EE 1.4 Web Services on the Fly

Source Code for this article

As Web services technology becomes pervasive, the beta release of Java 2 Enterprise Edition (J2EE) 1.4, which focuses primarily on Web services, flags a milestone in the Web services developer community. Sun's J2EE Reference Implementation (RI) helps developers to easily understand the technology through its robust implementation of the specification. The J2EE 1.4 specification (JSR-151) adds a lot of functionality to the platform. The core theme of J2EE 1.4 circumvents Web services. It has incorporated most of the Web services-related JSRs in its specification, including JSR-109 (Implementing Enterprise Web Services), JSR-101 (Java APIs for XML-based RPC), JSR-67 (Java APIs for XML Messaging 1.0), and JSR-93 (Java API for XML Registries 1.0).

Basically, a Web service client can access J2EE applications in two ways. First, the client can access a Web service created with JAX-RPC. Second, the client can access an EJB Web service (only stateless session beans) through its Web service endpoints. The bottom line is that JAX-RPC uses a servlet to implement the Web service. This helps in exposing the existing stateless session beans as Web services.

In this article, I'll deal with the development of a Web service using the J2EE 1.4 platform. I'll use the JAX-RPC APIs that form the basis for developing J2EE 1.4 Web services on the fly.

Creating a Web Service with JAX-RPC
Remote Procedure Call (RPC) is a mechanism through which you invoke procedures (or services) from a remote client. In the Java world, we have the Java API for XML-based RPC (JAX-RPC) in which service invocation takes place through an XML-based protocol called Simple Object Access Protocol (SOAP) over HTTP transport. Since the J2EE 1.4 platform uses standard technologies such as XML, SOAP, and HTTP, it is easy for developers to create Web services that are platform independent and interoperable.

The typical life cycle of a Web service has three stages: develop the Web service, deploy the Web service, and invoke the Web service. We'll follow this life cycle in developing our Web services using J2EE 1.4. We will consider the familiar stock quote application for our illustration. A stock quote service is deployed in the server. The client invokes the service by passing a stock symbol. Here, the service and the client are developed using the JAX-RPC APIs. Figure 1 shows the interactions between the Stock quote Web service and the stock quote client. Stubs are the client-side proxies used to communicate with the service. Ties are the classes the server needs to communicate with a remote client. Stubs and ties are low-level classes that perform similar functions, i.e, stubs on the client side and ties on the server side.

Building and Deploying the Service
The steps that are involved in building and deploying the service are:

Define the interface class for the service.
Implement the interface class.
Compile the classes and generate WSDL.
Package the classes as an EAR file.
Deploy the service.

Service Interface
Our stock quote service has one method, getQuote, which takes the symbol as the argument and returns the value of the stock symbol. The interface definition for the stock quote service is shown in Listing 1 .

Service Implementation
The service implementation StockQuoteImpl implements the interface StockQuote IF. This connects to an Axis stock quote service that is running on the www. xmethods.net server. The getQuote request made to this service returns an XML document that contains the value of the stock. If you are behind a firewall, you need to specify the proxyHost and proxyPort properties in order to access the service. The implementation for the stock quote service is shown in Listing 2 .

Generating the WSDL File
J2EE 1.4 provides a tool called wscompile.bat, which generates the WSDL file for the service. The Ant target generate-wsdl does this for you and runs this tool as follows:

wscompile.bat -define -d build/server -nd build/server
-classpath build/server service-config.xml

The generated WSDL file MyStock QuoteService.wsdl is shown in Listing 3 . The Ant target build-service compiles the service classes and the generation of the WSDL file for the service.

Packaging the Service
To package the service, use the ant target package-service, which packages the service and its dependent files in a stockquote.ear file. This EAR file bundles the stockquote-jaxrpc.war file in it. The contents of these WAR and EAR files are:

stockquote-jaxrpc.war
META-INF/
META-INF/MANIFEST.MF
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/stockquote/
MyHelloService.wsdl
WEB-INF/classes/stockquote/StockQuoteIF.class
WEB-INF/classes/stockquote/StockQuoteImpl.class
WEB-INF/mapping.xml
WEB-INF/web.xml
WEB-INF/webservices.xml

stockquote.ear
META-INF/
META-INF/MANIFEST.MF
stockquote-jaxrpc.war
META-INF/application.xml
META-INF/sun-j2ee-ri.xml

Deploying the Service
J2EE 1.4 provides a tool called deploytool.bat for deploying Web applications. The developed EAR file is deployed in the server using this tool. This can be done with the help of the Ant target deploy-service. As a precondition, you need to start the database server from the command prompt by typing

%J2EE_HOME%/bin/cloudscape.bat -start

Start the J2EE server from the command prompt by typing

%J2EE_HOME%/bin/j2ee.bat -verbose

to start the server in verbose mode. The Ant target runs the deploy tool as follows:

deploytool.bat -id stockquote-jaxrpc
-deployModule stockquote.ear

This deploys the stock quote service in the server. To verify that the service has been successfully deployed, execute the Ant target "list", which lists all the applications that are deployed on the server. You can verify the successful service deployment by typing the following URL in your browser:

http://localhost:8000/stockquote-jaxrpc/mystockquote?WSDL

If you can see the WSDL file on your browser, the service is deployed successfully.

Building and Running the Client
The steps involved in building and running the client are:

Generate the stubs.
Code the client class.
Compile the client class.
Package the classes as a JAR file.
Run the client.

Generate the Stubs
Stubs are the client-side proxies for the service. J2EE 1.4 provides a tool called wscompile.bat for generating these stubs. The Ant target generate-stubs, defined in our build.xml, does this task for you. This target runs the tool as follows:

wscompile.bat -gen:client -d build/client
-classpath build/server client-config.xml

The wscompile.bat tool generates files based on the information that it reads from the MyStockQuoteService.wsdl. The -gen: client option instructs the tool to generate the client-side classes called stubs. The -d option instructs the tool in which directory the generated stubs are to be placed. The -classpath option instructs the tool where to find the input classes. The tool reads the config file "client-config.xml" which has the information about the location of the WSDL file. The client configuration file client-config. xml is shown in Listing 4 .

Service Client
Once the service is defined, implemented, and deployed, it is ready for access by the clients. The client uses the generated stubs to interact with the service. This is a static client as it was created before runtime. The client takes the service endpoint as the input argument, and invokes the getQuote method by passing the symbol "HPQ". The service returns the value of the symbol to the system console. This is the real-time quote of the symbol with a delay of 20 minutes. The client for accessing the stock quote service is shown in Listing 5 .

Compiling and Packaging the Client
The Client sources along with the stubs are compiled and packaged as a JAR file by the Ant targets compile-client and package-client. This generates a file - client.jar that is used in invoking the stock quote service.

Setup Instructions for Running the Web Service
Required Software:

Download Ant 1.5.3 from http://ant.apache.org

Download J2SE 1.4.1 from http://java.sun.com/j2se/1.4.1/download.html

Download J2EE 1.4 Beta from http://java.sun.com/j2ee/1.4/download.html#sdk

Setting Up Environment Variables
To run the StockQuote application, you need to set the following environment variables:

J2EE_HOME=C:\j2sdkee1.4

JAVA_HOME=C:\j2sdk1.4.1_02

ANT_HOME=H:\apache-ant-1.5.3

PATH=%JAVA_HOME%/bin;%J2EE_HOME%\bin;%ANT_HOME%\bin;%PATH%

Invoke the Service Using the Web Service Client
Download the source code of the developed Web service. Extract this under "J2EE_HOME\doc\samples". The "build. xml" file bundled with this application defines all of the tasks discussed above as Ant targets. Before proceeding further, you need to change the proxy-related information in the StockQuoteImpl.java class.

As a precondition, you need to start the database and J2EE servers by using the following commands:

%J2EE_HOME%/bin/cloudscape.bat -start
"%J2EE_HOME%/bin/j2ee.bat -verbose

This starts the server in verbose mode. Wait until the command window displays "J2EE server startup complete." Now you are ready to execute the Ant targets that will help you build, deploy, and invoke the Web service.

Execute the following targets:

Ant build-service: Compiles the service sources.

Ant package-service: Packages the service classes and related files in an EAR file.

Ant deploy-service: Deploys the service in the server.

Ant list: Lists the deployed service.

Ant build-client: Compiles the client sources.

Ant package-client: Packages the client classes as a JAR file.

Ant run: Invokes the service. Figure 2 shows the output of the client after invoking the service. It returns the value of the symbol with a delay of 20 minutes.

Ant undeploy: Undeploys the service from the server.

Conclusion
Tools always ease the development of application software. With the help of robust tools, developers can spend more time designing the applications than developing the applications. The current release of the J2EE 1.4 platform provides some basic tools that ease the development of Web services. The J2EE 1.4 final release plans to have support for Web Services - Interoperability (WS-I) basic profiles. Developing and deploying Web services on the fly is a reality with the arrival of the J2EE 1.4 platform.

References

J2EE 1.4 Platform Home: http://java.sun.com/j2ee/

J2EE 1.4 Specification: http://java.sun.com/j2ee/j2ee-1_4-pfd2-spec.pdf

JSR 151: www.jcp.org/en/jsr/detail?id=151

The J2EE Tutorial Addendum: http://java.sun.com/j2ee/1.4/docs/tutorial/index.html

Author Bio
Arulazi Dhesiaseelan has been involved in designing and building Java-based applications and SDK for more than 3 years. He was also involved in the API development of the UDDI4j project hosted at http://uddi4j.org. Arul works with Hewlett-Packard (India Software Operations) in Bangalore. He is currently involved in the development of an open-service framework for mobile infrastructures. aruld@acm.org

Developing J2EE 1.4 Web Services on the Fly by Arulazi Dhesiaseelan
WSJ Vol 03 Issue 06 - pg.26

	



Listing 1: StockQuoteIF.java

package stockquote;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface StockQuoteIF extends Remote {
    public float getQuote(String symbol) throws RemoteException, Exception;
}

Listing 2: StockQuoteImpl.java

package stockquote;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.NodeList;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import java.net.URL;

public class StockQuoteImpl implements StockQuoteIF {

  // 20 minute delayed stock quote
  public float getQuote (String symbol) throws Exception {

    System.setProperty("http.proxyHost", "rio");//Replace with your proxy host
    System.setProperty("http.proxyPort", "8088");//Replace with your proxy port
    URL url = new URL("http://services.xmethods.net/axis/getQuote?s=" + symbol);

    DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
    DocumentBuilder db  = dbf.newDocumentBuilder();

    Document doc  = db.parse( url.toExternalForm() );
    Element  elem = doc.getDocumentElement();
    NodeList list = elem.getElementsByTagName("stock_quote");

    if (list != null && list.getLength() != 0) {
      elem = (Element) list.item(0);
      list = elem.getElementsByTagName("price");
      elem = (Element) list.item(0);
      String quoteStr = elem.getAttribute("value");

      return Float.valueOf(quoteStr).floatValue();
    }
    return(0);
  }
}

Listing 3: MyStockQuoteService.wsdl

<?xml version="1.0" encoding="UTF-8"?>

<definitions name="MyStockQuoteService" targetNamespace="urn:Foo"
 	xmlns:tns="urn:Foo" xmlns="http://schemas.xmlsoap.org/wsdl/"  
 	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 	xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <types/>
  <message name="StockQuoteIF_getQuote">
    <part name="String_1" type="xsd:string"/>
  </message>
  <message name="StockQuoteIF_getQuoteResponse">
    <part name="result" type="xsd:float"/>
  </message>
  <portType name="StockQuoteIF">
    <operation name="getQuote" parameterOrder="String_1">
      <input message="tns:StockQuoteIF_getQuote"/>
      <output message="tns:StockQuoteIF_getQuoteResponse"/></operation></portType>
  <binding name="StockQuoteIFBinding" type="tns:StockQuoteIF">
    <operation name="getQuote">
      <input>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
		 use="encoded" namespace="urn:Foo"/></input>
      <output>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
		 use="encoded" namespace="urn:Foo"/></output>
      <soap:operation soapAction=""/></operation>
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
	 style="rpc"/></binding>
  <service name="MyStockQuoteService">
    <port name="StockQuoteIFPort" binding="tns:StockQuoteIFBinding">
	
      <soap:address location="http://localhost:8000/stockquote-jaxrpc/mystockquote"/>
</port></service>
</definitions>

Listing 4: client-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration
 	xmlns="http://java.sun.com/xml/ns/jax-rpc/ri/config">
  <wsdl location="http://localhost:8000/stockquote-jaxrpc/mystockquote?WSDL"
       packageName="stockquote"/>
</conf5guration>

Listing 5: StockQuoteClient.java

package stockquote;

import javax.xml.rpc.Stub;

public class StockQuoteClient {

    private String endpointAddress;

    public static void main(String[] args) {

        System.out.println("Endpoint address = " + args[0]);
        try {
            Stub stub = createProxy();
            stub._setProperty(javax.xml.rpc.Stub.ENDPOINT_ADDRESS_PROPERTY,
                args[0]);
            StockQuoteIF stock = (StockQuoteIF)stub;
            System.out.println(stock.getQuote("HPQ"));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }

    private static Stub createProxy() {
        // Note: MyStockQuoteService_Impl is implementation-specific.
        return (Stub)(new MyStockQuoteService_Impl().getStockQuoteIFPort());
    }
}

Additional Code for this Article (~48.6 KB)

Java and Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. SYS-CON Publications, Inc. is independent of Sun Microsystems, Inc.