A Web Service Example: HelloServiceBean - The J2EE 1.4 Tutorial

A Web Service Example: HelloServiceBean

This example demonstrates a simple web service that generates a response based on information received from the client. HelloServiceBean is a stateless session bean that implements a single method, sayHello. This method matches the sayHello method invoked by the clients described in Static Stub Client. Later in this section, you'll test the HelloServiceBean by running one of these JAX-RPC clients.

Web Service Endpoint Interface

HelloService is the bean's web service endpoint interface. It provides the client's view of the web service, hiding the stateless session bean from the client. A web service endpoint interface must conform to the rules of a JAX-RPC service definition interface. For a summary of these rules, see Coding the Service Endpoint Interface and Implementation Class. Here is the source code for the HelloService interface:

package helloservice;
import java.rmi.RemoteException;
import java.rmi.Remote;

public interface HelloService extends Remote {
 
   public String sayHello(String name) throws RemoteException;
} 

Stateless Session Bean Implementation Class

The HelloServiceBean class implements the sayHello method defined by the HelloService interface. The interface decouples the implementation class from the type of client access. For example, if you added remote and home interfaces to HelloServiceBean, the methods of the HelloServiceBean class could also be accessed by remote clients. No changes to the HelloServiceBean class would be necessary. The source code for the HelloServiceBean class follows:

package helloservice;
import java.rmi.RemoteException; 
import javax.ejb.SessionBean;
import javax.ejb.SessionContext;

public class HelloServiceBean implements SessionBean {

   public String sayHello(String name) {

      return "Hello "+ name + " from HelloServiceBean";
   }

   public HelloServiceBean() {}
   public void ejbCreate() {}
   public void ejbRemove() {}
   public void ejbActivate() {}
   public void ejbPassivate() {}
   public void setSessionContext(SessionContext sc) {}
}  

Building HelloServiceBean

In a terminal window, go to the <INSTALL>/j2eetutorial14/examples/ejb/helloservice/ directory. To build HelloServiceBean, type the following command:

asant build-service 

This command performs the following tasks:

Compiles the bean's source code files
Creates the MyHelloService.wsdl file by running the following wscompile command:

wscompile -define -d build/output -nd build -classpath build -mapping build/mapping.xml config-interface.xml

The wscompile tool writes the MyHelloService.wsdl file to the <INSTALL>/j2eetutorial14/examples/ejb/helloservice/build/ subdirectory. For more information about the wscompile tool, see Chapter 8.

Use deploytool to package and deploy this example.

Creating the Application

In this section, you'll create a J2EE application named HelloService, storing it in the file HelloService.ear.

In deploytool, select FileNewApplication.
Click Browse.
In the file chooser, navigate to <INSTALL>/j2eetutorial14/examples/ejb/helloservice/.
In the File Name field, enter HelloServiceApp.
Click New Application.
Click OK.
Verify that the HelloServiceApp.ear file resides in <INSTALL>/j2eetutorial14/examples/ejb/helloservice/.

Packaging the Enterprise Bean

Start the Edit Enterprise Bean wizard by selecting FileNewEnterprise Bean. The wizard displays the following dialog boxes.

Introduction dialog box
Read the explanatory text for an overview of the wizard's features.
Click Next.
EJB JAR dialog box
Select the button labeled Create New JAR Module in Application.
In the combo box below this button, select HelloService.
In the JAR Display Name field, enter HelloServiceJAR.
Click Edit Contents.
In the tree under Available Files, locate the <INSTALL>/j2eetutorial14/examples/ejb/helloservice/build/ directory.
In the Available Files tree select the helloservice directory and mapping.xml and MyHelloService.wsdl.
Click Add.
Click OK.
Click Next.
General dialog box
In the Enterprise Bean Class combo box, select helloservice.HelloServiceBean.
Under Enterprise Bean Type, select Stateless Session.
In the Enterprise Bean Name field, enter HelloServiceBean.
Click Next.
In the Configuration Options dialog box, click Next. The wizard will automatically select the Yes button for Expose Bean as Web Service Endpoint.
In the Choose Service dialog box:
Select META-INF/wsdl/MyHelloService.wsdl in the WSDL File combo box.
Select mapping.xml from the Mapping File combo box.
Make sure that MyHelloService is in the Service Name and Service Display Name edit boxes.
In the Web Service Endpoint dialog box:
Select helloservice.HelloIF in the Service Endpoint Interface combo box.
In the WSDL Port section, set the Namespace to urn:Foo, and the Local Part to HelloIFPort.
In the Sun-specific Settings section, set the Endpoint Address to hello-ejb/hello.
Click Next.
Click Finish.
Select FileSave.

Deploying the Enterprise Application

Now that the J2EE application contains the enterprise bean, it is ready for deployment.

Select the HelloService application.
Select ToolsDeploy.
Under Connection Settings, enter the user name and password for the Application Server.
Click OK.
In the Distribute Module dialog box, click Close when the deployment completes.
Verify the deployment.
In the tree, expand the Servers node and select the host that is running the Application Server.
In the Deployed Objects table, make sure that HelloService is listed and that its status is Running.

Building the Web Service Client

In the next section, to test the web service implemented by HelloServiceBean, you will run the JAX-RPC client described in Chapter 8.

To verify that HelloServiceBean has been deployed, click on the target Application Server in the Servers tree in deploytool. In the Deployed Objects tree you should see HelloServiceApp.

To build the static stub client, perform these steps:

In a terminal go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/helloservice/ directory and type

asant build

In a terminal go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/ directory.
Open config-wsdl.xml in a text editor and change the line that reads

<wsdl location="http://localhost:8080/hello-jaxrpc/hello?WSDL"

to

<wsdl location="http://localhost:8080/hello-ejb/hello?WSDL"

Type

asant build

Edit the build.properties file and change the endpoint.address property to

http://localhost:8080/hello-ejb/hello

For details about creating the JAX-RPC service and client, see these sections: Creating a Simple Web Service and Client with JAX-RPC and Static Stub Client.

Running the Web Service Client

To run the client, go to the <INSTALL>/j2eetutorial14/examples/jaxrpc/staticstub/ directory and enter

asant run 

The client should display the following line:

Hello Duke! (from HelloServiceBean) 

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.