4 Developing and Deploying EJB Web Services

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

package demo;

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

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

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
;
}

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

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;
}
}

4.2.4 Returning Results From EJB Web Services

The hello() method shown in Example 4-3 returns a String. An Oracle Application Server 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.

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

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

4.2.7 Using Supported Data Types for Stateless Session EJB Web Services

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

Document Style Web Service implementations under Oracle Application Server Web Services restrict the signature of the Java methods that implement the Web Service. Only org.w3c.dom.Element can be passed to or sent from these Web Services.

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.

Oracle Application Server 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 Oracle Application Server 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 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 Oracle Application Server Web Services, rather than the client-side proxy. The generated WSDL document describes SOAP structures in a standard way. Application development environments, such as Oracle JDeveloper, which work directly from WSDL documents can correctly call Oracle Application Server Web Services with Java Beans as parameters.

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

4.3.1 Creating a Configuration File to Assemble Stateless Session EJB Web Services

The Oracle Application Server Web Services assembly tool, WebServicesAssembler, assists in assembling Oracle Application Server 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

• Adding Stateless Session EJB Service Tags

• Adding WSDL and Client-Side Proxy Generation Tags

<option name="source-path" contextroot="/test">/myTestArea/ws/src/statefull.war
</option>

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

4.3.2 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 Oracle Application Server 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.

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