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,
available from here
- 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:
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:
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
Bookmark
