How-To Configure and Use OC4J 10g (10.1.3) JCA 1.5 Resource Adapters


First Created: 01-Nov-2004
Last Updated: 16-Jan-2006
Author: Frances Zhao

Introduction

This demo application showcases OC4J's JCA 1.5 support and Oracle's generic JMS resource adapter (OracleASjms).

The application is a rather simplified inventory control program. It uses a JSP to let users update the inventory with information such as inventory id, order amount, order description, and stores such information on each new update into a JMS queue. In doing so, it uses a JCA 1.5 JMS resource adapter for outbound communication to the JMS provider. Meanwhile, the application includes an MDB that listens to the same JMS queue provided by the JMS provider. The MDB will get triggered when a message is entered into that JMS queue. It checks on each new inventory update, and would send e-mail notification using JavaMail APIs to a contact personnel once the inventory level of a particular item is below a threshold. This part of the application logic makes use of the same JCA 1.5 JMS resource adapter for inbound communication from the JMS provider.

The JMS provider we use is OC4J JMS, and the JCA 1.5 resource adapter we use is OC4J 10.1.3's generic JMS resource adapter (OracleASjms).

What are the Prerequisites?

What you should know

  • You should be familiar with these technologies: JMS, MDB, JSP;
  • Link to other OC4J Howto's on OTN

What are the Software Requirements?

This demo requires that the following sofware components are installed and configured correctly:

  • Oracle Containers for J2EE 10g (10.1.3) , standalone version, with a web site configured (example http-web-site)
  • Sun's JDK 1.4.1 or above
  • Apache Ant 1.6.2 or above, to build the application, available from here
  • Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

What are the Notations?

  • %ORACLE_HOME% - The directory where you installed OC4J.
  • %JAVA_HOME% - The directory where your JDK is installed
  • %HOWTO_HOME% - The directory where this demo is unzipped

How to Build the Application?

Please look at the companion article for detailed explanations on this demo application. The Javadoc's of this application are under the directory %HOWTO_HOME%/doc/javadoc/.

The important configuration files are all under %HOWTO_HOME%/etc directory, with the subdirectory OC4J_DP3_REF holding the sample OC4J configuration files like ra.xml, oc4j-ra.xml, etc. that do not need to be changed to build/run this application but are nevertheless relevant.

How to Run the Application?

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3).

Examining the How to Distribution

  • build - temporary directory created during the build
  • log - temporary directory holding build/deploy logs
  • etc - all necessary files to package the application
    • OC4J_DP3_REF - contains the sample OC4J config files under the subdirectories of %ORACLE_HOME%/j2ee/home
  • lib - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
  • doc - the How-to document and Javadoc's
    • javadoc - the javadoc of the different source files
    • how-to-jca-intro.html - this How-to page
  • src - the source of the demo
    • ejb - contains the MDB code
    • web - contains HTML pages and the JSP code

Setting Up the Application

Environment Configuration

Please check to make sure that the following properties are configured correctly in the ant-oracle.properties file located in the root of the sample's distribution (NOTE:  Some of these properties will default to the values of corresponding environment variables as noted below.  If you have these variables setup in your environment you may not have to alter the values in the file).  If necessary, modify these variable to the proper values for you environment:
  • oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
  • java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
  • oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
  • oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
  • oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
  • oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".
In addition, please make sure that the ant command associated with the OC4J ant distribution is in your execution path ( %ORACLE_HOME%/ant/bin).

Configuring the Environment for a Managed OracleAS Instance

If you are running a managed version of the Oracle Application Server 10 g, you are using OPMN, you must change the following values to match your configuration:
  • oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
  • oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
  • oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
  • oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
  • oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

JMS Provider Configuration

The JMS provider we use is OC4J JMS. Edit %ORACLE_HOME%/j2ee/home/config/application.xml and if commented, uncomment the definition of the resource-provider named oc4jjms.

Resource Adapter Configuration

Edit %ORACLE_HOME%/j2ee/home/config/oc4j-connectors.xml and if commented, uncomment the definition of the connector named OracleASjms. After this step, restart (shutdown and startup) OC4J 10g if necessary. The OC4J JMS resource provider should be loaded and functioning upon restart.

Starting the OC4J Instance

Start an OracleAS 10 g (10.1.3) instance as follows:
  • Stand Alone Installation: %ORACLE_HOME%/bin/oc4j start
    Note that the oc4j command expects the JAVA_HOME environment variable to point to a full JDK installation.

  • OracleAS Managed Installation: %ORACLE_HOME%/opmn/bin/opmnctl startall

Generating, Compiling and Deploying the Application

Build the Application

In the top-level %HOWTO_HOME% directory, type the command:

  • ant

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

This command would also attempt to deploy the application if the build is successful. It will first test whether OC4J is running.

You might want to modify the onMessage() method in the file %HOWTO_HOME%/src/ejb/bean/simpleMdb.java, to replace some of the hard-coded e-mail addresses to fit your particular environment, before building the demo application. Or you could do the modifications second and rebuild the application.

Deploy and bind the Application

You can also deploy and bind the application separately by using the following command. Make sure the %ORACLE_HOME% environment variable is defined. In the top-level %HOWTO_HOME% directory, type the command:

  • ant bind-web-app

Running the Application

In a browser window, browse to:

If the website hostname or port number are different, then use those values instead.

Follow the instructions on the displayed web page to continue with the demo. Use the "Back" button on the result page to go back to the front demo page.

Summary

In this document, you should have:

  • Known that OC4J 10g (10.1.3) fully supports JCA 1.5
  • Learned how to configure and use OC4J's generic JMS Resource Adapter

 

Left Curve
Popular Downloads
Right Curve
Untitled Document