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:

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.

  1. In deploytool, select FileRight ArrowNewRight ArrowApplication.
  2. Click Browse.
  3. In the file chooser, navigate to <INSTALL>/j2eetutorial14/examples/ejb/helloservice/.
  4. In the File Name field, enter HelloServiceApp.
  5. Click New Application.
  6. Click OK.
  7. 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 FileRight ArrowNewRight ArrowEnterprise Bean. The wizard displays the following dialog boxes.

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

Deploying the Enterprise Application

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

  1. Select the HelloService application.
  2. Select ToolsRight ArrowDeploy.
  3. Under Connection Settings, enter the user name and password for the Application Server.
  4. Click OK.
  5. In the Distribute Module dialog box, click Close when the deployment completes.
  6. Verify the deployment.
    1. In the tree, expand the Servers node and select the host that is running the Application Server.
    2. 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:

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

    2. asant build

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

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

    to

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

  4. Type

    5. asant build

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

    6. 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)