How-To Develop a Stateless Session EJB Web Service using EJB 3.0 and Web services metadata

• Introduction
• Example of a Stateless Session Bean as a Web Service using EJB 3.0 and Web services metadata
• Prerequisites
• What you need to know
• Software requirements
• Notations
• Building the Application
• Running the Application
• Examine the Sample Files Directories
• Configure the Environment
• Start the Server
• Generate, Compile and Deploy the Application
• Run the Application
• Summary

Introduction

Stateless Session Web Service example using EJB 3.0

import javax.jws.WebService;
import javax.jws.WebMethod; 

@WebService
public interface HelloServiceInf extends java.rmi.Remote{
    @WebMethod java.lang.String sayHello(java.lang.String name) throws java.rmi.RemoteException;

}

The actual bean class which provides the implementation of the EJB is just a plain Java class that implements the endpoint interface.

@WebService
@Remote(HelloServiceInf.class)
@Stateless(name="HelloServiceEJB")
public class HelloServiceBean implements HelloServiceInf {

     public String sayHello(String name) {
        return("Hello "+name +" from first EJB3.0 Web Service");
    }

}

The @Stateless annotations markes the bean as a stateless EJB. The name attribute specifies HelloServiceEJB as the name to be used by the EJB. 

The @WebService annotation can be used to annotate a web service interface and deployment descriptor for the EJB, but is not required. You will NOT need to package other web service deployment descriptors such as webservices.xml to deploy the stateless EJB web service.

Note: Certain EJB 3.0 API may change when EJB 3.0 specification becomes final and you may have to change your application to comply your application with final EJB 3.0 speciation. Oracle cannot guarantee backward compatibility of all EJB 3.0 features in future version of OC4J that complies with final version of the specification.

Prerequisites

What you need to know

• General EJB principles, a basic understanding of how EJBs can be exposed as standard web services components
• EJB 3.0

• Link to other EJB 3.0 How-Tos on OTN

Software Requirements

• Oracle Application Server 10g 10.1.3
• Sun JDK 1.5 or above, available here
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

Notations

• %ORACLE_HOME% - The directory where you installed Oracle Application Sever 10g 10.1.3
• %JAVA_HOME% - The directory where your JDK is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

Building the Application

The Javadoc for this application is located in the %HOWTO_HOME%/doc/javadoc/ directory.

The configuration files are located in the %HOWTO_HOME%/etc directory, including deployment descriptor files such as application.xml, ejb-jar.xml, webservices.xml, etc.

Running the Application

1. Examine the Sample File Directories

• build - temporary directory created during the build
• log - temporary directory holding build/deploy logs
• etc - all necessary files to package the application
• lib - holds the application archives that could be deployed
• doc - the How-to document and Javadoc's
• javadoc - the javadoc of the different source files
• how-to-ejb30-slsb.html - this How-to page
• src - the source of the demo
• ejb - contains the sample SLSB code
• client - contains application client code

2. Configure the Environment

• %ORACLE_HOME% - The directory where you installed OC4J.
• %JAVA_HOME% - The directory where you installed the JDK.
• %PATH% - includes %ORACLE_HOME% /ant/bin

3. Starting OC4J instance

Start OC4J stand alone using the following command after you make the above changes.

 >%ORACLE_HOME%/bin/oc4j -start 

If you are using an OracleAS managed install, start using the following command after you make the above changes.

> %ORACLE_HOME%/opmn/bin/opmnctl startall

4. Generate, Compile, and Deploy the Application

Ant 1.6.2 is shipped with OC4J and you have to set your PATH environment variable to $ORACLE_HOME/ant/bin. On some operating systems, Ant does not currently support the use of environment variables. If this is the case for your operating system, please modify the ant-oracle.xml file located in the %HOWTO_HOME% directory.

Edit ant-oracle.properties (in the demo directory) and ensure the following properties are set to the correct values, as indicated below for OC4J standalone:

• oc4j.host: host where OC4J is running (default localhost)
• oc4j.admin.port: RMI port number (default 23791)
• oc4j.admin.user: admin user name (default oc4jadmin)
• oc4j.admin.password: admin user password (default welcome)
• oc4j.binding.module: website name where deployed web modules are bound (default http-web-site)

If you are using OracleAS managed install then you have appropriately change the following properties beside changing oc4j.admin.user and oc4j.admin.password for your managed OC4J instance in OracleAS install.

• opmn.host: the hostname/IP where OracleAS is running (default localhost)
• opmn.port: OPMN request port (default 6003) for the OracleAS install
• oc4j.instance: admin user name (default oc4jadmin)

You have to uncomment appropriate deployer.uri in the ant-oracle.properties based on your environment i.e. a single instance OC4J or a clustered OC4J instance/group managed by OPMN.

Note: If you are using OracleAS install or hostname other than localhost and port other than 8888 then you have to make appropriate changes in the URL for the WSDL in the client code (HelloClient.java).

>ant

You should now have the newly created ejb30ws.ear in your %HOWTO_HOME%/lib directory.

This command also attempts to deploy the application if the build is successful. It first tests whether OC4J is running before commencing the deployment phase of the build script.

You can also deploy the application directly using the deploy task in the Ant build script. Ensure that the %ORACLE_HOME% environment variable is defined and from the %HOWTO_HOME% directory, type the command:

  >ant deploy 
  >ant bind-web-app 

5. Run the Application

>ant run 

You will observe that the web service client invokes the EJB web service and returns

Summary

• How a stateless session web service is built and configured using EJB 3.0.
• How to deploy and test a simple stateless session bean web service in the Oracle Application Server 10g 10.1.3.