Example 2: Deploying a Stateless Session EJB As a Web Service

The J2EE 1.4 specification includes the support for automatic exposure of a session EJB as a Web service. Geronimo has this capability built in.

This second example shows how to configure and deploy a session EJB as a Web service. The session EJB will be the session bean that you have used in Chapter 12. For more details on this application, please review Chapter 12. The focus in this example is on the additional pieces that are added to the application to expose the session EJB as a Web service.

The session bean supports one method called getAuthors() and returns the list of authors for this book. Each author’s name is returned as a Java String (containing the author’s name). The Web service interface and the JAX-RPC SEI are exactly the same as the one in Example 1. The Web service interface is described in the AuthorWS.wsdl file, and the JAX-RPC SEI is the com.wrox.progeronimo.Authors Locator interface.

However, the Web service implementation is no longer a servlet class. Instead, it is the com.wrox .progeronimo.AuthorBean class - which is a local session EJB in the example from Chapter 12.

Table 14-7 shows the additional Java classes added to the EJB example to support its exposure as a Web service.

Table 14-7: Java Classes Added to EJB to Support Its Exposure As Web Service
Open table as spreadsheet

Component	Description
AuthorsLocator	The JAX-RPC SEI that the Web service implements.
AuthorWS, GetAuthors, GetAuthorsResponse	JAX-RPC support classes that are generated by JAX-RPC tool - these classes are generated using the wscompile tool from the JWSDP.

Adding the WSDL and JAX-RPC Mapping Files

Similarly to example 1, the WSDL and JAX-RPC mapping files are vital for Geronimo during deployment - it parses them and generates the required tie and serializer classes for Web service deployment.

Instead of placing them under WEB-INF, however, for an EJB JAR archive, they must be placed under the META-INF directory. More specifically, both the AuthorWS.wsdl and the mapping.xml files are placed under META-INF directory of the EJB JAR file. In this second example, the EJB JAR file is called progeron-ejbs.jar and is placed inside the progws2.ear archive.

Configuring for EJB-Based Web Service Implementation

Since you are using the same WSDL, JAX-RPC mapping, and same JAX-RPC SEI as in the first example, you can also use the same webservices.xml file. Ensure that you place the webservices.xml file in the META-INF directory of the EJB JAR. You do, however, need to make one single major change to the webservices.xml. The file is shown in the following listing, with the major change highlighted:

 <?xml version="1.0" encoding="UTF-8"?> <webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1">     <webservice-description>         <webservice-description-name>Wrox Author List</webservice-description-name>         <wsdl-file>META-INF/AuthorsWS.wsdl</wsdl-file>         <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>         <port-component>             <port-component-name>AuthorsWS</port-component-name>             <wsdl-port>AuthorsLocatorPort</wsdl-port>             <service-endpoint- interface>com.wrox.progeronimo.AuthorsLocator</service-endpoint-interface>              <service-impl-bean>                <ejb-link>AuthorEJB</ejb-link>             </service-impl-bean>         </port-component>     </webservice-description> </webservices>

The highlighted major change tells Geronimo that the Web service is implemented by an EJB. The <ejb-link> element refers to the session EJB by name. The next section will show the EJB configuration in the ejb-jar.xml file, when the name of the session EJB is declared.

The other minor changes to the webservices.xml involve the META-INF directory (instead of WEB-INF from the WAR-based example).

Mapping a Session Bean to a Service Endpoint

To tell Geronimo that a session bean is actually used to implement a JAX-RPC SEI that corresponds to a Web service endpoint, you need to add the <service-endpoint> element to the <session> EJB description in the ejb-jar.xml J2EE deployment descriptor.

The ejb-jar.xml file from this example is shown in the following listing. The added <service- endpoint> element is highlighted.

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN'  'http://java.sun.com/dtd/ejb-jar_2_1.dtd'> <ejb-jar>   <enterprise-beans>       <session>           <display-name>Stateless Session Bean Local Interfaces</display-name>           <ejb-name>AuthorEJB</ejb-name>           <local-home>com.wrox.progeronimo.AuthorsHomeLocal</local-home>           <local>com.wrox.progeronimo.AuthorsLocal</local>           <service-endpoint>com.wrox.progeronimo.AuthorsLocator</service-endpoint>           <ejb-class>com.wrox.progeronimo.AuthorBean</ejb-class>           <session-type>Stateless</session-type>           <transaction-type>Container</transaction-type>       </session>     </enterprise-beans> </ejb-jar>

The <service-endpoint> element specifies the JAX-RPC SEI that is implemented by this session bean. Note that the Web service implementation class is always the EJB implementation class specified by the <ejb-class> element.

Note that the <ejb-name> contains the name of the EJB, and this is the name that is referenced in the webservices.xml’s <ejb-link> element.

Providing a Deployment Context for the Web Service

Next, you must tell Geronimo the root context used to address the Web service. For example, you may want to address the Web service at the following URL:

http://localhost:8080/ejbauthorsfinder

You must create a Geronimo-specific deployment plan called openejb-jar.xml and place that in the META-INF directory of the EJB JAR file. In this example, the openejb-jar.xml used is shown in the following listing:

 <?xml version="1.0"?> <openejb-jar   xmlns=" http://www.openejb.org/xml/ns/openejb-jar-2.1"     xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"     xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"     xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"> <sys:environment>     <sys:moduleId>       <sys:groupId>wrox</sys:groupId>       <sys:artifactId>progeronejbws</sys:artifactId>       <sys:version>1.0</sys:version>       <sys:type>car</sys:type>     </sys:moduleId> </sys:environment>      <enterprise-beans>         <session>             <ejb-name>AuthorEJB</ejb-name>             <web-service-address>ejbauthorsfinder</web-service-address>         </session>     </enterprise-beans>   </openejb-jar>

The highlighted code segment uses the <web-service-address> element to specify the root context path for the deployed Web service -ejbauthorsfinder.

Trying Out the Example

First, deploy the enterprise application EAR file, called progws2.ear. This will deploy both the EJB-based application and the Web service.

To access the old EJB-based application, use the following URL:

http://localhost:8080/ProGeronimo/authors.cgi

The application uses the AuthorBean session EJB to obtain the list of authors and shows it using a JSP, as shown in Figure 14-8.

Figure 14-8: The AuthorBean EJB-based application

Now, access the URL of the Web service, implemented by the same AuthorBean:

http://localhost:8080/ejbauthorsfinder?wsdl

You should see a display of the WSDL for the Web service.

To actually test out the Web service, you must run the standalone client supplied.

Change into the client directory. Assuming that you have Ant and JWSDP installed for the last example, you can run the client as follows:

ant run

You should see the standalone client accessing the EJB Web service and printing out names of the authors of this book - as it did in the first example.