Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g (10.1.3.5.0)
Part Number E13982-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
View PDF

8 Assembling a Web Service with EJBs

This chapter describes how to use the WebServicesAssembler tool to expose version 2.1 Enterprise Java Beans (EJBs) as Web services.

This chapter has the following sections.

Exposing EJBs as Web Services

You can use WebServicesAssembler to expose version 2.1 EJBs as Web services that conform to J2EE 1.4 standards. Many EJBs have been written to encapsulate business functions in the middle tier. If you use EJBs in your enterprise applications, you can expose them as Web services.

Note:

WebServicesAssembler cannot be used to expose version 3.0 EJBs as a Web service.

EJB components, by design, are meant for distributed computing and are well-suited for exposure as Web services. The EJB specification supports declarative transactions, thread management, and role-based security. You can leverage these benefits if you decide to use EJB components as Web services. EJBs exposed as Web services can still be accessed by traditional RMI EJB clients as well as by SOAP protocols. J2EE 1.4 allows exposing only stateless session beans as Web services.

By their nature, SOAP and Web services are stateless. Therefore, stateless session beans are an ideal medium for exposure as Web services. Stateless session beans can be used for checking someone's credit, charging a bank account, or placing an order. Session beans that implement a business function to be used by other remote applications are a perfect fit for exposure as Web services.

Writing an EJB Web service using JAX-RPC involves writing an EJB that implements a service and provides an interface for it. The EJB should contain the business logic that a client can invoke when it makes a Web service request.

An EJB Web service does not differ from any other Web service and can be invoked by a client written in Java, .NET, or any other programming language. The client of an EJB Web service can leverage static stubs, dynamic proxies, or Dynamic Invocation Interfaces (DII).

These are the general steps for exposing an EJB as a Web service.

  1. Create the service endpoint interface for the stateless EJB component.

    The developer performs this step.

  2. Assemble the service artifacts. This includes generating the WSDL and mapping files, and packaging the application into a deployable archive.

    WebServicesAssembler can be used to perform this step.

See Also:

"Steps for Assembling a Web Service from an EJB" for more detailed information on each of these steps.

Working with Version 2.0 EJBs

Although this chapter focuses on exposing version 2.1 EJBs as Web services, version 2.0 EJBs can also be exposed. All the functionality in Oracle Application Server Web Services for working with version 2.1 EJBs is also available for version 2.0 EJBs. OracleAS Web Services and WebServicesAssembler can detect version 2.0 EJBs and ensure that they are processed correctly. Its remote interface methods must define the methods to be exposed as a Web service.

See Also:

"How to Write EJBs for Web Services" for more information on the J2EE Web Services requirements for EJBs.

Working with Version 3.0 EJBs

You cannot use the WebServicesAssembler tool to expose version 3.0 EJBs as a Web service. However, you can expose these EJBs by using the J2SE 5.0 Web Service Annotations, which is supported by OracleAS Web Services.

See Also:

Chapter 11, "Assembling Web Services with Annotations" and "Steps to Use Annotations to Assemble a Web Service from a Version 3.0 EJB" provides more information on using annotations to expose version 3.0 EJBs as Web services.

How to Assemble a Web Service with EJBs

This section contains the following subsections:

Prerequisites

Before you begin, provide the following files and information.

  • Write an Enterprise Java Bean that contains the business functions that you want to expose and its interface. The EJB and its interface must conform to EJB 2.1 standards and the J2EE 1.4 standard for a Web service.

    See "How to Write EJBs for Web Services" for more information on these requirements.

  • Decide whether you want WebServicesAssembler to only generate the service files or generate and package the files into a deployable archive. The ear argument packages the files into an archive. If you do not specify ear, then the files are stored in a directory specified by the output argument.

    See "ear", "output", and "war" for more information on output and packaging arguments.

  • If the methods in the EJB use nonstandard data types, you must specify a custom serializer to process them.

    See "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide and in Table 5-1 for more information on non-standard data types.

    See "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on writing custom serializers.

  • If your EJB needs to work with any additional message processing components, for example to process SOAP header information, you can specify message handlers.

    See Chapter 17, "Processing SOAP Headers" and "How to Configure Handlers in an Ant Task" for more information on these topics.

Steps for Assembling a Web Service from an EJB

The following steps describe how to use WebServicesAssembler to expose a session bean as a Web service.

  1. Write the EJB that you want to expose as a Web service and its service endpoint interface.

  2. Inspect the ejb-jar.xml deployment descriptor.

    Enter a <service-endpoint> element and a value if it is not already in the file. This element identifies the service endpoint interface for this Web service. In the following ejb-jar.xml fragment the <service-endpoint> element is highlighted in bold.

    <enterprise-beans>
    <session>
        <ejb-name>HelloServiceBean</ejb-name>
        <service-endpoint>oracle.demo.ejb.HelloServiceIntf</service-endpoint>
        <ejb-class>oracle.demo.ejb.HelloserviceBean</ejb-class>
        <session-type>Stateless</session-type>
        <transaction-type>Container</transaction-type>
    </session>
</enterprise-beans>

  3. Generate the service artifacts by running the WebServicesAssembler tool with the ejbAssemble command. For example:

    Command line:

    java -jar wsa.jar -ejbAssemble 
               -appName helloServices-ejb 
               -ear dist/helloServices-ejb.ear 
               -output build 
               -targetNamespace http://oracle.j2ee.ws/ejb/Hello 
               -typeNamespace http://oracle.j2ee.ws/ejb/Hello/types 
               -input dist/HelloServiceejb.jar 
               -ejbName HelloServiceBean

    Ant task:

    <oracle:ejbAssemble appName="ejbApp" 
          targetNamespace="http://oracle.j2ee.ws/ejb/Hello"
          ear="dist/ejbApp.ear"
          output="build"
          typeNamespace="http://oracle.j2ee.ws/ejb/Hello/types"
          input dist/HelloServiceejb.jar
          ejbName HelloServiceBean
/>

    In this command and Ant task:

    • ejbAssemble—Creates an EAR or EJB JAR that can expose an EJB as a Web service. You must specify a valid version 2.1 EJB JAR as input; the system will create a WSDL and the proprietary oracle-webservices.xml deployment descriptor. See "ejbAssemble".

    • appName—Specifies the name of an application. Usually, this name is used as a base value for other arguments like context and uri. See "appName".

    • ear—Specifies the name and location of the generated EAR. See "ear".

    • output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".

    • targetNamespace—Specifies the target namespace to be used in the generated WSDL. The value can be either a conforming HTTP URL, a non-conforming HTTP URL, or even a URI. See "targetNamespace".

    • typeNamespace—Specifies the type namespace to be used in the schema types in the generated WSDL. The name that you specify will always be used and it will not be reversed. See "typeNamespace".

    • input—Specifies the directory or JAR containing the classes that should be copied to WEB-INF/classes. This argument will be added to the classpath used by the WebServicesAssembler. See "input".

    • ejbName—Specifies the name of the EJB to be exposed as a Web service. Note that this is not a class name; it is the unique name of the EJB that is specified in the <ejb-name> tag in the ejb-jar.xml file. See "ejbName".

    This command assembles the EJB 2.1 Web service by generating the WSDL and mapping files, and packaging the application into a deployable archive, dist/helloServices-ejb.ear. This archive contains the helloService-ejb.jar, which stores all of the service artifacts, such as the EJB implementation classes, the generated WSDL and mapping file, standard Web service descriptor file, webservices.xml, and the Oracle proprietary deployment descriptor file oracle-webservices.xml. For more information on the ejbAssemble command, see "ejbAssemble".

  4. Deploy the service and bind the application.

    EAR files are deployed into a running instance of OC4J. For more information on deployment, see the Oracle Containers for J2EE Deployment Guide. The following is a sample deployment command.

    java -jar <OC4J_HOME>/j2ee/home/admin_client.jar deployer:oc4j:localhost:port <user> <password>
            -deploy 
            -file dist/ejbApp.ear 
            -deploymentName ejbApp 
            -bindWebApp default-web-site

    The following list describes the parameters in this code example.

    • <OC4J_HOME>—the directory containing the OC4J installation.

    • <user>—the user name for the OC4J instance. The user name is assigned at installation time.

    • <password>—the password for the OC4J instance. The password is assigned at installation time.

    • ejbApp—the name of the application.

    • default-web-site—the Web site to which the application will be bound. This is usually default-web-site. To configure Web sites, see the server.xml file in <OC4J_HOME>/j2ee/home/config.

    After deployment, this Web service's WSDL will be available at the following Web address. The values for context-root and endpoint-address-uri can be found in the META-INF/oracle-webservices.xml file.

    http://host:port/context-root/endpoint-address-uri

  5. (Optional) Check that deployment succeeded.

    OracleAS Web Services provides a Web Service Test Page for each deployed Web service. See "How to Use the Web Services Test Page" for information on accessing and using the Web Service Test Page.

  6. Generate the client-side code:

    • For the J2SE environment, generate stubs (client proxies) for a J2SE Web service client by running the WebServicesAssembler tool with the genProxy command. For more information on generating and assembling a stub, see Chapter 15, "Assembling a J2SE Web Service Client".

    • For the J2EE environment, generate a service endpoint interface and a JAX-RPC mapping file for a J2EE Web service client by running the WebServicesAssembler tool with the genInterface command. For more information on generating and assembling a client for a J2EE Web service, see Chapter 14, "Assembling a J2EE Web Service Client".

    For example, the following command and Ant task generates stubs that can be used for a J2SE client. The client proxies are stored them in the directory build/src/client. The client application will use the stub to invoke operations on a remote service. For more information on the required and optional arguments to genProxy, see "genProxy".

    Command line:

    java -jar wsa.jar -genProxy 
                  -output build/src/client/ 
                  -wsdl http://localhost:8888/hello/HelloService?WSDL 
                  -packageName oracle.demo.hello

    Ant task:

    <oracle:genProxy 
           wsdl="http://localhost:8888/hello/HelloService?WSDL"
           output="build/src/client"
           packageName="oracle.demo.hello"
/>

    In this command line and Ant task:

    • genProxy—Creates a static proxy stub that can be used by a J2SE Web service client. See "genProxy".

    • output—Specifies the directory where generated files will be stored. If the directory does not exist, it will be created. See "output".

    • wsdl—Specifies the absolute file path, relative file path, or URL to a WSDL document. See "wsdl".

    • packageName—Specifies the package name that will be used for generated classes if no package name is declared in the JAX-RPC mapping file. See "packageName".

  7. Compile and run the client.

    List the appropriate JARs on the classpath before compiling the client. Table A-2, "Classpath Components for a Client Using a Client-Side Proxy" lists all of the JAR files that can possibly be used on the client classpath. As an alternative to listing individual JARs, you can include the client-side JAR, wsclient_extended.jar on the client classpath. This JAR file contains all the classes necessary to compile and run a Web service client. The classes are from the individual JAR files listed in Table A-2. See "Setting the Classpath for a Web Service Proxy" for more information on wsclient_extended.jar and the client classpath.

How to Write EJBs for Web Services

Writing EJB-based Web services using JAX-RPC involves writing an EJB that implements a service and providing an interface for it. The EJB should contain the business functions that OracleAS Web Services can invoke when a client makes a Web service request.

This section provides information on how to write an EJB Web service that returns a string, "HELLO!! You just said:phrase", where phrase is input from a client. The EJB Web service receives a client request with a single String parameter and generates a response that it returns to the Web service client.

Writing a J2EE 1.4-compliant EJB implementation for Web services consists of these tasks.

How to Write an EJB Service Endpoint Interface

To use JAX-RPC to create a Web service with EJBs, you must write a public service endpoint interface to which the EJB must conform. The requirements for creating a service endpoint interface for a stateless session bean are summarized in Section 5.3.2.1 of the Enterprise Web Services 1.1 specification. The specification is available from the following Web site.

http://www.jcp.org/en/jsr/detail?id=921

The interface must extend java.rmi.Remote, and all methods must throw a java.rmi.RemoteException. You can use only Java primitives and classes that are JAX-RPC value types and nonstandard data types as parameters or return types for the EJB methods defined in the service endpoint interface.

Some examples of JAX-RPC value types are non-primitives such as java.lang.String or java.lang.Double and Java mappings of Multipurpose Internet Mail Extensions (MIME) types such as java.awt.Image or javax.xml.transform.Source.

You can use custom Java data types in the service endpoint interface, but you must also provide a serializer to process them.

See Also:

  • "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide and in Table 5-1 for descriptions of nonstandard data types.

  • "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on using custom data types and their serialization.

Example 8-1 illustrates a sample service endpoint interface.

Example 8-1 Sample Service Endpoint Interface

package oracle.demo.ejb;

import java.rmi.Remote;
import java.rmi.RemoteException;
/**
 * This is an Enterprise Java Bean Service Endpoint Interface
 */
public interface HelloServiceInf extends java.rmi.Remote {
    /**
     * @param phrase java.lang.String
     * @return java.lang.String
     * @throws String The exception description.
     */
    java.lang.String sayHello(java.lang.String phrase) 
          throws java.rmi.RemoteException;
}

How to Implement an EJB Interface for Web Services

Create an Enterprise Java Bean by implementing the business functions that you want the Web service to expose.

The HelloServiceBean described in Example 8-2 is a sample session bean. The class defines a public method, sayHello, that returns HELLO!! You just said: phrase, where phrase was input from a client. In general, a Java bean for a Web service defines one or more public methods.

An Enterprise Java Bean, for the purposes of Web services, is any Java class that conforms to the following requirements:

  • It must have a constructor that takes no arguments.

  • All properties that you want to use must be exposed through accessors.

See Also:

"Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide and in Table 5-1 for descriptions of JAX-RPC supported data types for EJBs parameters and return types.

To comply with the JAX-RPC standard, all the methods in HelloServiceBean throw a java.rmi.RemoteException. They must also follow all the requirements of the version 2.1 EJB specification and Enterprise Web Services 1.1 specification.

Example 8-2 Sample HelloService Session Bean

package oracle.demo.ejb;

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

/**
 * This is a Session Bean Class.
 */
public class HelloServiceBean implements SessionBean {
    public String sayHello(String phrase) {
        return "HELLO!! You just said :" + phrase;
    }

    public void setSessionContext(javax.ejb.SessionContext ctx)
            throws java.rmi.RemoteException {
    }

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

Packaging and Deploying Web Services that Expose EJBs

The packaging structure of Web services that expose EJBs is described in "Packaging for a Web Service Based on EJBs".

See Also:

Oracle Containers for J2EE Deployment Guide for a detailed description of the deployment of EJBs.

Note:

WebServicesAssembler cannot detect whether the configuration of the 2.1 EJB is correct. This can be detected only during deployment and server-side code generation of the 2.1 EJB Web service.

How to Secure EJB-Based Web Services at the Transport-Level

You can use the <ejb-transport-security-constraint> and <ejb-transport-login-config> elements in the oracle-webservices.xml deployment descriptor to configure transport-level security constraints for a version 2.1 or 3.0 EJB. These elements are described in "Securing EJB-Based Web Services at the Transport Level".

See Also:

"Adding Transport-level Security for Web Services Based on EJBs" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide for more information on providing transport-level security for EJBs, and how to write clients to access Web services secured on the transport level.

Tool Support for Exposing EJBs as a Web Service

With Oracle JDeveloper, you can use modeling tools and wizards to create, modify, and deploy J2EE-compliant EJBs. The EJB wizards can be used to perform the following tasks.

For more information on using Oracle JDeveloper to create EJBs and expose them as a Web service, see the Oracle JDeveloper on-line help.

Limitations

See "Assembling Web Services From EJBs".

Additional Information

For more information on:

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Index
Index		 Go to Feedback page
Contact Us