How-To Configure and Use Oracle
Container for Java EE 11 Technology Preview JCA 1.5 Resource Adapters
First Created: 01-Nov-2004
Last Updated: 12-Apr-2007
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 Oracle Container for Java EE 11 Technology Preview'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 Java EE 11 Technology
Preview, standalone version, with a web site configured
(example http-web-site)
- Sun's JDK 1.5.0 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 Java EE 11 Technology Preview.
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 10g, 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 11 Technology Preview instance
as follows:
o
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.
o
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 11 Technology
Preview fully supports JCA 1.5
- Learned how to configure and use
OC4J's generic JMS Resource Adapter
Bookmark
