The OracleAS JMS Router provides a reliable asynchronous
JMS message routing service that can bridge:
Destinations of the same JMS provider.
Destinations of different JMS providers.
The OracleAS JMS Router guarantees the following behavior:
For persistent JMS message, the OracleAS JMS
Router guarantees exactly-once message delivery.
For non-persistent JMS messages, the OracleAS
JMS Router guarantees at-most-once message delivery.
The OracleAS JMS Router guarantees the delivery
of messages in the order they are received by the OracleAS JMS Router
from the source destination.
The application accompanying this how-to provides two
demonstrations for the OracleAS JMS Router. The first requires
minimal configuration and illustrates JMS message routing between
two OracleAS JMS destinations. The second demonstration illustrates
JMS message routing from an OracleAS JMS destination to an Oracle OJMS
destination. The second demonstration requires access to an
Oracle database with OJMS installed and is optional for completing
this how-to.
how-to overview - 2 routing jobs will be configured
Prerequisites
What you need to know
You should be familiar with these technologies:
JMS, JCA, and Oracle OJMS if trying the OracleAS JMS to Oracle OJMS
demonstration.
Oracle Database 10g (optional; only for the second part of this how-to)
Any HTML browser like Mozilla, Microsoft Internet
Explorer, Netscape, etc.
Notations
%ORACLE_HOME% - The directory you installed
OracleAS 10.1.3.
%JAVA_HOME% - The directory where
your JDK is installed
%HOWTO_HOME% - The directory where this
demo is unzipped.
%DB_HOST% - The hostname for Oracle OJMS.
%DB_SID% - Database Sid for Oracle OJMS.
%DB_PORT% - Database connection port for Oracle OJMS.
Building the Application
The javadoc for this application is located in the %HOWTO_HOME%/doc/javadoc
directory.
The configuration files for deploying the application
are located in the %HOWTO_HOME%/etc directory.
OracleAS JMS Configuration
This demo will utilize the default OracleAS JMS JCA 1.5
compliant resource adapter for messages that are routed to and from
the OracleAS JMS provider. This resource adapter is pre configured
with the OracleAS 10.1.3 distribution and requires no additional
changes for use with this how-to.
Oracle OJMS Configuration
The To use Oracle OJMS, this how-to requires additional configuration to
use the Oracle OJMS provider. These additional steps are provided
in detail in the next section and entail:
Setting up the OJMS schema in the database hosting
Oracle OJMS.
Deploying a JCA 1.5 compliant Oracle OJMS resource
adapter.
Defining the Oracle OJMS resource provider in the
default application.xml file.
Defining the data-source in the default data-sources.xml
which will provide connection detail for the resource-provider.
Updating the contents of the default oc4j-connectors.xml
for the OJMS resource adapter.
The configuration descriptors for the Oracle OJMS resource adapter are
located within the ./etc/rar directory.
Running the Application
Examining the Sample File Directories
The contents of the zip file include:
build - temporary directory created during
the build.
doc - the How-to document and Javadocs
javadoc - the javadoc of the source
file
How-to-JMSRouter
etc - all the necessary files to package
the application.
application.xml - application descriptor.
orion-application.xml - OC4J specific
application descriptor.
orion-web.xml - J2EE web deployment
descriptor.
web.xml - OC4J specific deployment descriptor.
rar
META-INF
oc4j-ra.xml - OC4J specific resource
adapter deployment descriptor.
ra.xml - resource adapter deployment
descriptor.
lib - holds the application archives that
could be deployed.
log - temporary directory for holding
build/deploy logs.
src - contains all Java source code for
the example
web
java
JMSRouterDemo.java - Servlet code
which drives this demonstration.
ant-oracle.properties - property settings
for building/deploying.
ant-oracle.xml - used by the Ant build
file.
build.xml - Ant build file.
Configuring the Environment
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 env variable.
java.home -
the root directory of JDK installation. Defaults to JAVA_HOME
env 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 "http-web-site".
If you intend to use the OracleAS JMS Router with the
Oracle OJMS provider:
db.host - the hostname of the database
where Oracle OJMS resides. Defaults to DB_HOST env variable.
db.sid - the database SID for Oracle OJMS.
Defaults to DB_SID env variable.
db.port - the database port number for
Oracle OJMS. Defaults to DB_PORT env variable.
In addition, please make sure that the ant command
associated with the OC4J ant distribution is in your execution path
(%ORACLE_HOME%/ant/bin).
Starting the OC4J Instance
Start an OC4J 10.1.3 instance as follows:
%ORACLE_HOME%/bin/oc4j start
Note that the oc4j command expects
the JAVA_HOME environment variable to point to a full JDK installation.
Generating, Compiling and Deploying the Application
ant
You should now have the newly created jmsrouterdemo.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.
Note that you can also deploy the application separately . Ensure the
%ORACLE_HOME% environment variable is defined,
and from the %HOWTO_HOME% directory, type the
commands:
ant bind-web-app
Adding 'job1': OracleASjms to OracleASjms
JMS Message Routing
For this demo application,
we will set up a OracleAS JMS Routing job that will route messages
between OracleASjms Queue 'jms/demoQueue' to OracleASjms Topic 'jms/demoTopic'.
Both of these OracleASjms destinations are pre-configured within
OC4J so we will simply add the necessary OracleAS JMS Router job and
call the application.
In a browser window, enter the Application Server
Control URL (note that this URL, especially the port number, might be different in your environment):
http://<your_server_host>:8888/em
Enter the logon details and select your Home.
Select the Administration link.
Select JMS Providers under Services.
Select OracleAS JMSRouter under Related Links.
In the right frame, select the Operations
tab, then addRouterJob
To create a routing job you will have to provide a JMS Router jobName.
Enter job1 for value.
Click on pencil icon to define custom job properties.
Click 4 times on "Add Row".
Enter Key and Element values as per table below:
Custom job properties for job1.
Key
Element
messageSource
OracleASjms/Topics/jms/demoTopic
sourceConnectionFactory
OracleASjms/MyCF
messageTarget
OracleASjms/Queues/jms/demoQueue
targetConnectionFactory
OracleASjms/MyCF
Then press the invoke operation button. When this
completes, a new JMS Router job called "job1" is added that will
route messages enqueued on OracleASjms' jms/demoTopic to OracleASjms'
jms/demoQueue.
At this point you can continue on to the
next step and configure 'job2', the OracleASjms to Oracle OJMS JMS Messsage
Routing job or proceed to Running the JMS Router Application.
Adding 'job2': OracleASjms to Oracle
OJMS JMS Message Routing
Define the Oracle OJMS Database Schema
Prior to using Oracle
OJMS, we have to define the OJMS database schema. To do this, copy
./sql/jmsrouteruser.sql to the database host and execute the following
command:
sqlplus system/<password_for_system>
as sysdba @jmsrouteruser.sql
When complete, a database user called "jmsrouteruser" is created
along with the Oracle OJMS Queues ojmsQ1 and ojmsLogQ.
Deploy the Resource Adapter
The resource adapter descriptors are located located within %HOWTO_HOME%/etc/rar.
To deploy them to oc4j, type the following command from the %HOWTO_HOME%
directory:
ant deploy-rar
Update the default OC4J configuration descriptors
To finish the resource adapter deployment, complete the following
steps:
Add the following data-source definitions to data-sources.xml
Be sure to replace url variables %DB_HOST%, %DB_PORT%,
and %DB_SID% with the values which point to your database hosting
Oracle OJMS.
Update oc4j-connectors.xml, locate the connector definition for
aqojms (search for string "aqojms"). It will be empty, add the
following to complete aqojms' connector definition:
Adding the JMS Message Router Job for OracleASjms to Oracle OJMS
For this part of the demo, we will set up a OracleAS
JMS Routing job that will route messages between OracleASjms Topic
'jms/demoTopic' to OJMS Queue 'ojmsQ1'.
In a browser window, enter the Application Server
Control URL (this URL might be different in your environment depending on the options you selected during the AS installation)
http://<your_server_host>:8888/em.
Enter the logon details and wait for the Home page to
display.
Select the Administration link.
Select JMS Providers under Services.
Select OracleAS JMSRouter under Related Links.
In the right frame, select the Operations tab, then
addRouterJob
provide a JMS Router jobName: job2
Click on pencil icon to define custom job properties.
Click 5 times on "Add Row".
Enter Key and Element values as per table below:
Key
Element
messageSource
OracleASjms/Topics/jms/demoTopic
sourceConnectionFactory
OracleASjms/MyCF
messageTarget
aqojms/Queues/Queues/ojmsQ1
targetConnectionFactory
aqojms/AQCF
targetLogQueue
aqojms/Queues/Queues/ojmsLogQ
Then press the invoke operation button. When this
completes, a new JMS Router job called "job2" is added that will route
messages enqueued on OracleASjms' jms/demoTopic to Oracle OJMS' ojmsQ1.
Running the JMS Router Application
Execute the JMS Router application in a browser window by
entering the URL
When both job1 and job2 are configured, the following output will be
displayed:
OracleAS JMS Message Router Demonstration
Sending messages to OracleASjms/jms/demoTopic
(OracleASjms source for 'job1' and 'job2')
Sent Message: #1 :This is the message:
Sent Message: #2 :This is the message:
Sent Message: #3 :This is the message:
Sent Message: #4 :This is the message:
Sent Message: #5 :This is the message:
Receiving messages from OracleASjms/jms/demoQueue
(OracleASjms target for 'job1')
Received Message #1 :This is the message:
Received Message #2 :This is the message:
Received Message #3 :This is the message:
Received Message #4 :This is the message:
Received Message #5 :This is the message:
Receiving messages from aqojms/Queues/Queues/ojmsQ1
(OJMS target for 'job2')
Received Message #1 :This is the message:
Received Message #2 :This is the message:
Received Message #3 :This is the message:
Received Message #4 :This is the message:
Received Message #5 :This is the message:
Bookmark
