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

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. A Servlets handle 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:

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/webservices/demo/basic/stateless_ejb on UNIX %ORACLE_HOME%\webservices\demo\basic\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

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

package demo;

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 Service 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.

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.

Using Supported Data Types for Stateless Session EJB Web Services

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.

Note:

Oracle9iAS Web Services does not support Element[], (arrays of org.w3c.dom.Element).

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.

When Java Beans are used as parameters to Oracle9iAS Web Services, the client-side code should use the generated Bean included with the downloaded client-side proxy. This is because the generated client-side proxy code translates Simple Object Access Protocol (SOAP) structures to and from Java Beans by translating SOAP structure namespaces to and from fully qualified Bean class names. If a Bean with the specified name does not exist in the specified package, the generated client code will fail.

However, there is no special requirement for clients using Web Services Description Language (WSDL) to form calls to Oracle9iAS Web Services, rather than the client-side proxy. The generated WSDL document describes SOAP structures in a standard way. Application development environments, such as JDeveloper, which work directly from WSDL documents can correctly call Oracle9iAS Web Services with Java Beans as parameters.

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.

Writing a WSDL File for EJB Web Services (Optional)

The WebServicesAssembler supports the <wsdl-gen> and <proxy-gen> tags to allow a Web Service developer to generate WSDL files and client-side proxy files. You can use these tags to control whether the WSDL file and the client-side proxy are generated. Using these tags you can also specify that the generated WSDL file or a WSDL file that you write is packaged with the Web Service J2EE .ear.

A client-side developer either uses the WSDL file that is obtained from a deployed Web Service, or the client-side proxy that is generated from the WSDL to build an application that uses the Web Service.

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 includes the ejb.jar that supplies the Java implementation. This section describes how to use the Oracle9iAS Web Services tool, WebServicesAssembler. WebServicesAssembler takes an XML configuration file that describes the stateless session EJB Web Service and produces a J2EE .ear file that can be deployed under Oracle9iAS Web Services.

This section contains the following topics.

Creating a Configuration File to Assemble Stateless Session EJB Web Services

The Oracle9iAS Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle9iAS Web Services. This section describes how to create a configuration file to use with stateless session EJB Web Services.

Create WebServicesAssembler configuration file by adding the following:

Adding Web Service Top Level Tags

Table 4-2 describes the top level WebServicesAssembler configuration file tags. Add these tags to provide top level information describing the Java Stateless Web Service or a Java Stateful Web Service. These tags are included within a <web-service> tag in the configuration file.

Example 4-4 shows a complete config.xml file, including the top level tags.

Table 4-2 Top Level `WebServicesAssembler` Configuration Tags

Tag	Description
`<context>`context `</context>`	Specifies the context root of the Web Service. This tag is required.
`<datasource-JNDI-name>` `</datasource-JNDI-name>`	Specifies the datasource associated with the Web Service.
`<description>`description `</description>`	Provides a simple description of the Web Service. This tag is optional.
`<destination-path>`dest_path `</destination-path>`	Specifies the name of the generated J2EE .ear file output. The dest_path specifies the complete path for the output file. This tag is required.
`<display-name>`disp_name `</display-name>`	Specifies the Web Service display name. This tag is optional.
`<option name="source-path">`path `<option>`	Includes a specified file in the output .ear file. Use this option to include Java resources. The path specifies the path to the file to include. This tag is optional.
`<stateless-session-ejb-service>`sub-tags `</stateless-session-ejb-service>`	Use this tag to add a stateless session EJB Web Service. See Table 4-3 for a description of the valid sub-tags.
`<temporary-directory>`temp_dir `</temporary-directory>`	Specifies a directory where the assembler can store temporary files. This tag is optional.

Adding Stateless Session EJB Service Tags

Prepare Stateless Session EJB Web Services using the WebServicesAssembler <stateless-session-ejb-service> tag. This tag is included within a <web-service> tag in the configuration file. Add this tag to provide information required for generating a stateless session EJB Web Service.

Table 4-3 shows the <stateless-session-ejb-service> sub-tags.

Example 4-4 shows a complete config.xml file, including <stateless-session-ejb-service>.

Table 4-3 Stateless Session EJB Web Service Sub-Tags

Tag	Description
`<ejb-name>`name `</ejb-name>`	Specifies the name of the stateless session EJB. This tag is required
`<ejb-resource>`resource `</ejb-resource>`	This is a backwards compatibility tag. See Also: the top level `<option name="source-path">` tag in Table 4-2. This tag is optional
`<path>`path `</path>`	This is a backwards compatibility tag. See Also: the top level `<option name="source-path">` tag in Table 4-2. This tag is optional
`<uri>`URI `</uri>`	Specifies servlet mapping pattern for the Servlet that implements the Web Service. The path specified as the URI is appended to the `<context>` to specify the Web Service location. This tag is required.

Example 4-4 Sample Stateless Session EJB WebServicesAssembler Configuration File

<web-service>
    <display-name>EJB Web Services Demo</display-name>
    <destination-path>tmp/HelloService.ear</destination-path>
    <temporary-directory>tmp</temporary-directory>
    <context>/sejb_webservices</context>

    <stateless-session-ejb-service>
        <path>tmp/Hello.jar</path>
        <uri>/HelloService</uri>
        <ejb-name>HelloService</ejb-name>
    </stateless-session-ejb-service>
</web-service>

Adding WSDL and Client-Side Proxy Generation Tags

Running WebServicesAssembler To Prepare Stateless Session EJB Web Services

After you create the WebServicesAssembler configuration file, you can generate a J2EE .ear file for the Web Service. The J2EE .ear file includes the stateless session EJB Web Service servlet configuration information.

Run the Oracle9iAS Web Services assembly tool, WebServicesAssembler as follows:

java -jar WebServicesAssembler.jar -config config_file

Where: config_file is the configuration file that contains the <stateless-session-ejb-service> tag.

See Also:

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

4 Developing and Deploying EJB Web Services

Using Oracle9iAS Web Services With Stateless Session EJBs

Writing Stateless Session EJB Web Services

Defining a Stateless Session Remote Interface

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

Defining a Stateless Session Home Interface

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

Defining a Stateless Session EJB Bean

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

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 for Stateless Session EJB Web Services

Table 4-1 Web Services Supported Data Types

Writing a WSDL File for EJB Web Services (Optional)

Preparing and Deploying Stateless Session EJB Based Web Services

Creating a Configuration File to Assemble Stateless Session EJB Web Services

Adding Web Service Top Level Tags

Table 4-2 Top Level WebServicesAssembler Configuration Tags

Adding Stateless Session EJB Service Tags

Table 4-3 Stateless Session EJB Web Service Sub-Tags

Example 4-4 Sample Stateless Session EJB WebServicesAssembler Configuration File

Adding WSDL and Client-Side Proxy Generation Tags

Running WebServicesAssembler To Prepare Stateless Session EJB Web Services

Deploying Web Services Implemented as EJBs

4
Developing and Deploying EJB Web Services

Table 4-2 Top Level `WebServicesAssembler` Configuration Tags