4
Developing and Deploying EJB Web Services

This chapter describes the procedures you use to write and deploy Oracle9iAS Web Services that are implemented as stateless session Enterprise Java Beans (EJBs).

This chapter covers the following topics:

• Using Oracle9iAS Web Services With Stateless Session EJBs

• Writing Stateless Session EJB Web Services

• Preparing and Deploying Stateless Session EJB Based Web Services

Using Oracle9iAS Web Services With Stateless Session EJBs

Oracle9iAS Web Services can be implemented as any of the following:

• Java Classes

• Stateless Session EJBs

• PL/SQL Stored Procedures or Functions

This chapter shows sample code for writing Web Services implemented with stateless session EJBs.

Oracle9iAS supplies Servlets to access the EJBs which implement a Web Service. The Servlet handles requests generated by a Web Service client, locates the EJB home and remote interfaces, runs the EJB that implements the Web Service, and returns results back to the Web Service client.

See Also: Chapter 3, "Developing and Deploying Java Class Web Services" Chapter 5, "Developing and Deploying Stored Procedure Web Services" Chapter 6, "Building Clients that Use Web Services"

Writing Stateless Session EJB Web Services

Writing EJB based Web Services involves obtaining or building an EJB that implements a service. The EJB should contain one or more methods that a Web Services Servlet running under Oracle9iAS invokes when a client makes a Web Services request. There are very few restrictions on what actions Web Services can perform. At a minimum, Web Services usually generate data that is sent to a Web Services client or perform an action as specified by a Web Services method request.

This section shows how to write a simple stateless session EJB Web Service, HelloService that returns a string, "Hello World", to a client. This EJB Web Service receives a client request with a single String parameter and generates a response that it returns to the Web Service client.

The sample code for the complete Web Service is supplied with Oracle9iAS Web Services installation in the following directory:
$ORACLE_HOME/j2ee/home/demo/web_services\stateless_ejb on UNIX %ORACLE_HOME%\j2ee\home\demo\web_services\stateless_ejb on Windows.

Create a stateless session EJB Web Service by writing a standard J2EE stateless session EJB containing a remote interface, a home interface, and an enterprise bean class. Oracle9iAS Web Services runs EJBs that are deployed as Oracle9iAS Web Services in response to a request issued by a Web Service client.

Developing a stateless session EJB consists of the following steps:

• Defining a Stateless Session Remote Interface

• Defining a Stateless Session Home Interface

• Defining a Stateless Session EJB Bean

• Returning Results From EJB Web Services

• Error Handling for EJB Web Services

• Serializing and Encoding Parameters and Results for EJB Web Services

• Using Supported Data Types

• Writing a WSDL File or Client-Side Proxy Stubs for EJB Web Services

Defining a Stateless Session Remote Interface

When looking at the HelloService EJB Web Service, note that the .ear file, HelloService.ear defines the Web Service and its configuration files. In the sample directory, the file HelloService.java provides the remote interface for the HelloService EJB.

Example 4-1 shows the Remote interface for the sample stateless session EJB.

Example 4-1 Stateless Session EJB Remote Interface for Web Service

public interface HelloService extends javax.ejb.EJBObject {
java.lang.String hello(java.lang.String phrase) throws java.rmi.RemoteException;
}

Defining a Stateless Session Home Interface

The sample file HelloServiceHome.java provides the home interface for the HelloService EJB.

Example 4-2 shows the EJBHome interface for the sample stateless session EJB.

Example 4-2 Stateless Session EJB Home Interface for Web Service

package demo;
/**
 * This is a Home interface for the Session Bean
 */
public interface HelloServiceHome extends javax.ejb.EJBHome {

HelloService create() throws javax.ejb.CreateException, java.rmi.RemoteException
;
}

Defining a Stateless Session EJB Bean

The sample file HelloServiceBean.java provides the Bean logic for the HelloService EJB. When you create a Bean to implement a Web Service, the parameters and return values must be of supported types. Table 4-1 lists the supported types for parameters and return values for stateless session EJBs that implement Web Services.

Example 4-3 shows the source code for the HelloService Bean.

Example 4-3 Stateless Session EJB Bean Class for Web Services

package demo;

import java.rmi.RemoteException;
import java.util.Properties;
import javax.ejb.*;

/**
 * This is a Session Bean Class.
 */
public class HelloServiceBean implements SessionBean {
    private javax.ejb.SessionContext mySessionCtx = null;

public void ejbActivate() throws java.rmi.RemoteException {}
public void ejbCreate() throws javax.ejb.CreateException, 
java.rmi.RemoteException {}

public void ejbPassivate() throws java.rmi.RemoteException {}
public void ejbRemove() throws java.rmi.RemoteException {}
public javax.ejb.SessionContext getSessionContext() {
    return mySessionCtx;
}
public String hello(String phrase)
{
    return "HELLO!! You just said :" + phrase;
}
public void setSessionContext(javax.ejb.SessionContext ctx) throws 
java.rmi.RemoteException {
    mySessionCtx = ctx;
}
}

Returning Results From EJB Web Services

The hello() method shown in Example 4-3 returns a String. An Oracle9iAS Web Services server-side Servlet runs the Bean that calls the hello() method when the Servlet receives a Web Services request from a client. After executing the hello() method, the Servlet returns a result to the Web Services client.

Example 4-3 shows that the EJB Bean writer only needs to return values of supported types to create Web Services implemented as stateless session EJBs.

See Also: "Using Supported Data Types"

Error Handling for EJB Web Services

When an error occurs while running a Web Service implemented as an EJB, the EJB should throw an exception. When an exception is thrown, the Web Services Servlet returns a Web Services (SOAP) fault. Use the standard J2EE and OC4J administration facilities for logging Servlet errors for a Web Service that uses stateless session EJBs for its implementation.

Serializing and Encoding Parameters and Results for EJB Web Services

Parameters and results sent between Web Service clients and a Web Service implementation need to be encoded and serialized. This allows the call and return values to be passed as XML documents using SOAP.

See Also: "Serializing and Encoding Parameters and Results for Web Services"

Using Supported Data Types

Table 4-1 lists the supported data types for parameters and return values for Oracle9iAS Web Services.

Table 4-1  Web Services Supported Data Types

Primitive Type	Object Type
Boolean	java.lang.Boolean
byte	java.lang.Byte
double	java.lang.Double
float	java.lang.Float
int	java.lang.Integer
long	java.lang.Long
short	java.lang.Short
string	java.lang.String
	java.util.Date
	org.w3c.dom.Element
	org.w3c.dom.Document
	org.w3c.dom.DocumentFragment
	Java Beans (whose property types are listed in this table or are another supported Java Bean)
	Single-dimensional arrays of types listed in this table.

A Bean for purposes of Web Services is any Java class which conforms to the following restrictions:

• It must have a constructor taking no arguments.

• It must expose all interesting state through properties.

• It must not matter what order the accessors for the properties, for example, the setX or getX methods, are in.

Oracle9iAS Web Services allows Beans to be returned or passed in as arguments to J2EE Web Service methods, as long as the Bean only consists of property types that are listed in Table 4-1 or are another supported Java Bean.

Note: When Web Service proxy classes and WSDL are generated, all Java primitive types in the service implementation on the server-side are mapped to Object types in the proxy code or in the WSDL. For example, when the Web Service implementation includes parameters of primitive Java type int, the equivalent parameter in the proxy is of type java.lang.Integer. This mapping occurs for all primitive types.

See Also: Chapter 6, "Building Clients that Use Web Services"

Writing a WSDL File or Client-Side Proxy Stubs for EJB Web Services

When writing an EJB Web Service, this step is optional. If you do not perform this step, the Oracle9iAS Web Services runtime generates a WSDL file and the client-side proxy stubs for deployed Web Services. These files allow Oracle9iAS Web Services to supply a Web Service client with the WSDL or the client-side proxy stubs that a client-side developer can use to build an application that uses a Web Service.

When you do not want to use the Oracle9iAS Web Services generated WSDL file or client-side proxy stubs, and you want to supply your own versions of these files, perform the following steps:

1. Manually create either the WSDL file or the client-side proxy Jar file, or both files for your service.

2. Name the supplied WSDL file or client-side proxy Jar file and place it in the appropriate location. The WSDL file must have a .wsdl extension. The client-side proxy Jar must have an _proxy.jar extension.The extension is placed after the service name.

   For example,

   simpleservice.wsdl
   simpleservice_proxy.jar
   

3. Add the manually created WSDL file or client-side Jar file to the .war file that is associated with the Web Service servlet for the service implementation. There are several choices for adding the files to the .war file:
   • Place the files in the correct package directory under WEB-INF/classes. For example, if simpleservice.wsdl describes a service that is part of the demo package, place the file in the following directory:

     WEB-INF/classes/demo/simpleservice.wsdl
     
     

   • Place the Jar file that you create in a Jar file under the WEB-INF/lib component of the .war file that is added to the .ear file and deployed as a Web Service. For example, the file simpeservice_proxy.jar could be added to simpleservice.jar and placed in WEB-INF/lib, or added to a Jar file namex.jar in WEB-INF/lib (where namex is a file name).

     Note: The Jar file containing the proxy stubs, and optionally the proxy source must be a Jar component of a Jar file in WEB-INF/lib, it cannot simply be added to the WEB-INF/lib directory.

     See Also: "Preparing and Deploying Stateless Session EJB Based Web Services" "Getting WSDL Descriptions and Client-Side Proxy Jar for Web Services"

Preparing and Deploying Stateless Session EJB Based Web Services

To deploy a stateless session EJB as a Web Service you need to assemble a J2EE .ear file that includes the deployment descriptors for the Oracle9iAS Web Services Servlet and the ejb.jar file that supplies the EJB implementation. A Web Service implemented using a stateless session EJB includes a .war file that provides descriptive information for the Oracle9iAS Web Services Servlet running under Oracle9iAS Containers for J2EE (OC4J). This section describes the procedures you use to assemble the .ear file that contains a stateless session EJB and the Web Services Servlet configuration, placed in a .war file, required to run a stateless session EJB as a Web Service.

This section covers the following topics:

• Preparing a JAR File With an EJB

• Modifying web.xml to Support EJB Web Services

• Preparing a WAR File for EJB Web Services

• Preparing an EAR File for EJB Web Services

• Deploying Web Services Implemented as EJBs

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services. The Web Services assembly tool takes a configuration file which describes the location of the J2EE/EJB Jar files and produces a J2EE .ear file that can be deployed under Oracle9iAS Web Services. This section describes how to assemble Oracle9iAS Web Services implemented as stateless session EJBs manually, without using WebServicesAssembler.

See Also: "Running the Web Services Assembly Tool"

Preparing a JAR File With an EJB

To prepare a stateless session EJB to implement a Web Service, you need to prepare a JAR file as you would for any other standard J2EE stateless session EJB.

The JAR file should contain the following:

• The EJB classes and interfaces

• The EJB Deployment Descriptor: ejb-jar.xml

For the sample stateless session EJB, the EJB classes should include the classes developed for the HelloServiceBean, organized in the standard J2EE directory format.

Example 4-4 shows the stateless session EJB deployment descriptor for the HelloServiceBean that is included in the JAR file.

Example 4-4 EJB Deployment Configuration File: ejb-jar.xml

<?xml version="1.0"?>
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.
//DTD Enterprise JavaBeans 1.1
//EN' 'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>

<ejb-jar>
    <enterprise-beans>
      <session>
        <ejb-name>HelloService</ejb-name>
        <home>demo.HelloServiceHome</home>
        <remote>demo.HelloService</remote>
        <ejb-class>demo.HelloServiceBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
      </session>
    </enterprise-beans>
</ejb-jar>

Modifying web.xml to Support EJB Web Services

This section provides instructions for assembling a Web Service based on a stateless session EJB. To use an EJB as a Web Service you need to add a <servlet> entry and corresponding <ejb-ref> and <servlet-mapping> entries in a web.xml file for each stateless session EJB that is deployed as a Web Service. The resulting web.xml file is packaged as part of a J2EE .war file that is included in the .ear file that is deployed to OC4J.

Note: All stateless session EJBs deployed as Oracle9iAS Web Services must conform to the restrictions limiting parameter and return types. See Table 4-1 for the list of supported types for parameters and return values.

To modify web.xml to support Web Services implemented as stateless session EJBs, perform the following steps:

• Configure the servlet Tag in web.xml for EJB Web Services

• Configure the ejb-ref Tag in web.xml for EJB Web Services

• Configure the servlet-mapping Tag in web.xml for EJB Web Services

Configure the servlet Tag in web.xml for EJB Web Services

To add Web Services based on stateless session EJBs, you need to modify the <servlet> tag in the web.xml file. This supports using the Oracle9iAS Web Services Servlet with a stateless session EJB. Table 4-2 describes the <servlet> tag and the values that it must include to add a Web Service based on a stateless session EJB.

Example 4-5 shows the sample <servlet> tag for the HelloService EJB Web Service, as extracted from the web.xml file in the .ear file, statelessejb.ear.

Table 4-2  Servlet Tags Supporting EJB Deployment

Servlet Tag	Description
<init-param>	The <init-param> tag contains a <param-name> and <param-value> pair. jndi-name: The Web Services Servlet definition requires a <param-name> with the value jndi-name, and a corresponding <param-value> set to the EJBs JNDI URL relative to the java:comp/env for the Servlet.
<servlet-class>	This is always oracle.j2ee.ws.SessionBeanWebService for all stateless session EJB Web Services.
<servlet-name>	Specifies the name for the Servlet that runs the Web Service.

Example 4-5 Sample Stateless <servlet> Entry for an EJB Based Web Service

<servlet>
  <servlet-name>stateless session bean web service - HelloService</servlet-name>
  <servlet-class>oracle.j2ee.ws.SessionBeanWebService</servlet-class>
  <init-param>
    <param-name>jndi-name</param-name>
    <param-value>ejb/HelloService</param-value>
  </init-param>
</servlet>

Configure the ejb-ref Tag in web.xml for EJB Web Services

To add Web Services based on stateless session EJBs, you need to modify the <ejb-ref> tag in the web.xml file. This tag defines the EJB reference that is used as the implementation of the Web Service.

Example 4-6 shows the <ejb-ref> tag for the HelloServiceBean for the HelloService EJB, as extracted from the web.xml file in the .ear file, HelloService.ear.

Example 4-6 Stateless Session EJB <ejb-ref> Entry for a Web Service

<ejb-ref>
  <ejb-ref-name>ejb/HelloService</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>demo.HelloServiceHome</home>
  <remote>demo.HelloService</remote>
  <ejb-link>HelloService</ejb-link>
</ejb-ref>

See Also: Java 2 Platform Enterprise Edition Specification, v1.3 for more information on using the <ejb-ref> tag in web.xml, at http://java.sun.com/j2ee/docs.html

Configure the servlet-mapping Tag in web.xml for EJB Web Services

To add Web Services based on stateless session EJBs, you need to modify the <servlet-mapping> tag in the web.xml file. This tag specifies the URL for the Servlet that implements a Web Service.

Example 4-7 shows a sample <servlet-mapping> entry corresponding to the servlet entry shown in Example 4-5.

Example 4-7 Sample <servlet-mapping> Entries for Web Services

<servlet-mapping>
  <servlet-name>stateless session bean web service - HelloService</servlet-name>
  <url-pattern>/HelloService</url-pattern>
</servlet-mapping>

Preparing a WAR File for EJB Web Services

To add Web Services based on stateless session EJBs, you need to use a .war file to package the J2EE Servlet configuration files. After modifying the web.xml file, add any required support classes under WEB-INF/classes or WEB-INF/lib and package all the files as a .war file.

Note: All the classes the are required for a Web Service implementation must conform to the standard J2EE class loading norms. Thus, the implementation classes and support classes must be packaged in the .war or .ear file, or they must be available in the OC4J classpath.

Preparing an EAR File for EJB Web Services

To add Web Services based on stateless session EJBs, you need to include an application.xml file and package the application.xml, the .war file and the ejb.jar file containing the stateless session EJB into a J2EE .ear file.

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services.

See Also: "Running the Web Services Assembly Tool"

Deploying Web Services Implemented as EJBs

After creating the .ear file containing a stateless session EJB, you can deploy the Web Service as you would any standard J2EE application stored in an .ear file (to run under OC4J).

See Also: Oracle9iAS Containers for J2EE User's Guide in the Oracle9iAS Documentation Library