AQ JMS - WL JMS - Bridge Configuration_small

Created by P.V.J. Pavan Kumar 1

1 A White Paper on AQ – Weblogic Interaction

A WHITE PAPER ON

AQ – WEBLOGIC INTERACTION

WITH A USE-CASE

Authors: P. V. J. Pavan Kumar

Creation Date: 01-Dec-2008

Last Updated: 04-Dec-2008

Version: 1.0



AQ JMS - WL JMS - Bridge Configuration

This white paper discusses the interaction between the queues lying in Oracle Database (AQ)

and the queues lying in the Weblogic.

To start with, to the novice, I will explain the terms first and then the background between this

interaction. Next, we will see the steps to configure the bridge.

Queues in Oracle:

i. Oracle has two different types of queues:

a. Queues in Database

b. Queues in OC4J (in the middleware. Oracle has a middleware called Internet

Application Server, Oracle iAS in short. And as the product matured, the

integration components like BPEL, ESB etc were added to iAS and combinedly, it

is called as SOA Suite. OC4J is the JEE container which holds all these

components including the queues).

Queues in the Database:

When the queueing concept has evolved, Oracle has created the queueing

framework in the database and called this as Advanced Queueing, AQ in short. The

queueing framework contains all the logic to be dealt with the queues like producing and

consuming into/from the queues, creating/dropping of the queues etc. All this framework

(APIs) are written in PL/SQL only. When any application has to use the queues, they

need to use these PLSQL APIs and manage their data. It was relatively tough for the

applications to use Oracle AQs without PLSQL code. When such a requirement has

come, the developers had to code their procedures/functions to use the queues and call

these custom procedures and functions in the JDBC calls to manage the data in their

queues within their applications.

Queues in the Middleware:

Meanwhile, when the technology is grown, JEE has evolved and Sun

Microsystems has defined their standards for JNDI and JMS. All the Middleware vendors

like Weblogic, Websphere etc were implementing these APIs. Oracle as a middleware

vendor has to implement these APIs. Oracle has a middleware container called Oracle

Containers for Java (OC4J, in short) which had implemented these JNDI and JMS APIs.

These set of APIs again resulted in a new set of queues called Oracle OC4J JMS

queues. These queues are in-memory queues and persistent mechanism is different

from that of the AQs.



Background for JMS Providers:

Now, as the Java EE community has grown, the demand for using the AQs has come

from the Java community. So, Oracle has written Java Wrappers for the AQs in the

database.

After these implementations of JMS and JNDI APIs, Oracle now has two different JMS

Providers:

i. OJMS (AQ/JMS)

ii. OC4J/JMS.

Which JMS Provider to be used:

Now, comes the question, as to which JMS provider we need use.

OJMS is the JEE 1.4 compliant JMS provider. It has been integrated into iAS/SOA

Suite/OC4J (Middleware) using a resource provider interface, while at the same time

leveraging Advanced Queuing in the Oracle Database for persistence and recoverability.

If you are planning on using JMS in your development then Oracle strongly recommends

using OJMS as the JMS provider.

OC4J/JMS will also be J2EE 1.3 compliant.

Developers have the choice of which JMS provider best fits into the architecture:

a. One based on Advanced Queuing (OJMS) with all the inherent qualities that come

with being part of the Oracle Database or

b. A lightweight, in-memory based queuing system (OC4J/JMS).

The other choice of choosing the provider depends on the interactions of the Oracle JMS

providers with other JMS providers such as Weblogic.



Queues in Weblogic:

All the queues are implementations of the JEE specifications for JMS and JNDI. The

default persistent mechanisms of the queues are file-based in Weblogic. And we have only 1

type of JMS providers in Weblogic unlike in Oracle.

Interaction between Oracle JMS (both OJMS and OC4J JMS) and

Weblogic JMS

In a typical A2A or B2B applications, there arises a requirement for an interaction between

different systems and architectures. One of the requirements, which we had, was an interaction

between Oracle JMS and Weblogic JMS.

I will try to explain the difficulties we faced in making them work. Our requirement is as follows:

Requirements:

a. One of my applications (say, Application M), deployed in Weblogic, exposes their APIs

as Webservices and can create/manage orders using Webservices. For this, it uses

Weblogic queues as communication medium.

Any client, which needs to create an order, will need to enqueue an appropriate

message into the Weblogic queue (say Queue MA), via JMS or HTTP (depends on the

business requirement). The Application-M will then, dequeue the message from Queue-

MA and process it and puts it back in another queue (Queue MB) with the

response/result of the action. The client reads this response message from this queue

(Queue MB) and takes appropriate action.

b. My client, here, is another application (say, Application S).

c. It needs to use BPEL and ESB framework to enqueue/dequeue the messages to/from

the Weblogic queues.

Approach we have taken:

There are quite a few approaches we have taken to make the above interaction successful.

There are different considerations that need to be taken like guaranteed delivery for this

interaction to be successful.

1. Webservice interaction: Since the target application is exposing their APIs as

webservices, we can use HTTP protocol to invoke this service and pass the input. In this

case, we don’t use the Weblogic queues. It is a direct interaction.

Disadvantage:



The main disadvantage with this is the protocol itself. HTTP, being a stateless protocol,

doesn’t guarantee the delivery of the messages. This is a serious requirement as our

Integration is mainly based on the orders and we don’t want to loose our messages,

resulting in loss of the orders.

Next consideration:

So, the next consideration we need to make is to use JMS protocol instead of HTTP to

make the interaction. This is SOAP over JMS protocol i.e., we need to wrap our SOAP

envelope in the JMS envelope and pass the data to a JMS server. The JMS server, will

then enqueue the message to a JMS queue.

2. Next, we need to either write a program to create the JMS envelope and invoke the

enqueue on the JMS server.

Oracle BPEL/ESB has an adapter (pre-defined configurable client) called JMS Adapter.

Using this, we can enqueue/dequeue the message into any JMS server (compatibility

still holds good).

This approach is considered next to enqueue/dequeue the messages into/from the

Weblogic queues.

Please see the document “Steps to connect to Weblogic 92 using JMS Adapter” for the

detailed steps to do this. You can also check the link – Steps to connect to Weblogic 9.2

with JMS Adapter with BPEL/ESB.

Disadvantage:

The main disadvantage with this approach is that Weblogic Container has a limitation

with the trasancationability. Weblogic doesn’t support the transactions outside its

container i.e., if there is an error while enqueue/dequeue operations, the message will

be lost and will not be placed back in the queue. This again hampers the guaranteed

delivery approach.

Next consideration:

So, the next consideration we wanted to try is to use JMS Bridge approach. Weblogic

JMS Bridge moves the message to-and-from Weblogic-AQ and AQ-Weblogic (it can

move the messages between any 3rd party JMS providers infact).

3. Weblogic JMS Bridge:

Note: Please the document “JMS Bridge” for understanding the JMS Bridging concept

and configuration before reading the below approach (those who know about the JMS

Bridge can ignore this).



The bridge acts a JMS client dequeueing the messages and enqueueing the messages

as and when needed, between the JMS servers.

Issue:

The next uphill task is to make a bridge between Weblogic JMS and Oracle AQ. All the

queues that we are using on the Application-S side are AQ queues. We need to move

the messages from AQ queues to Weblogic queues and back with a response.

Note: Generally, whenever we are using the queues, the queues are accessed via the

JNDI. So, in the following text, if I refer queue, it means that I am referring to the JNDI

entry of the queue.

Now, there is a catch here. Weblogic can see the OC4J JMS queues because they are

implementations of JEE specifications. But, the implementations of AQ JMS APIs (Java

APIs) by Oracle are proprietary and so, Weblogic cannot see the AQ queues (JNDI

entries).

For a more detailed explanation, please look the below picture:

Figure 1

In this picture, Application-S has two approaches to enqueue the message into AQ:

a. Using JMS API (green-line path in the above diagram), it can use the JNDI defined in

the OEMS (Oracle Enterprise Messaging Service – which is nothing but

implementation of Sun’s JMS specification) and enqueue the message into the AQ

JMS. For this, we need to write a code manually. Also, an OC4J resource adapter

needs to be created/deployed which can connect to the database and talk to AQ.



b. Using OC4J JMS Adapter (red-line path in the above diagram). BPEL/ESB uses

OC4J JMS Adapter which can talk to the AQ JMS directly. This is the same

consideration which we saw previously (2nd approach).

Now, while configuring the Weblogic JMS Bridge, the configuration requires the details

of the JMS Server host, port, and protocol used, connection factory name, and the JNDI

name associated with the queue, something like below:

Figure 2

If we closely observe, the protocol used here is:

opmn://ormi://[hostname:port:oc4j_container]

It means that we are asking Weblogic to follow the green-line path as in Figure 1. But

since the queues are AQ queues and the AQ JMS APIs are proprietary to Oracle,

Weblogic will not be able to invoke the appropriate InitialContextFactory and view the

queues.

To be more technical, Weblogic makes JMS standard calls to instantiate the

InitialContextFactory and view the JNDI tree to connect to the queues (AQ). But since

Oracle APIs are proprietary, the API calls are differently implemented. So, Weblogic,



when tries to instantiate the InitialContextFactory on the OC4J, will receive an exception

from OC4J as the function/method call doesn’t exist.

So, Weblogic will NOT be able to view the JNDI tree of the AQ queues. It can although

view the OC4J JNDI tree i.e., only the in-memory queues are visible and not the AQ

queues although AQs have JNDI in the OC4J.

Alternative:

The solution to this is to implement the JMS and JNDI Standard APIs so that the

appropriate call to the method returns AQ JNDI names to the Weblogic. For this, AQ

JMS implementation has to be changed which is tedious.

Thanks to Robert Patrick’s framework (AQJMS). This framework wraps the AQ JMS

objects, so that they are Weblogic JNDI compatible and binds them to the Weblogic

JNDI. As a result of implementing AQJMS Framework, we will be able to view the AQ

JMS Objects in the Weblogic JNDI tree. From that point, we can pretty much do

whatever we would do with any standard JMS objects, including Weblogic MDBs

transactionally enqueue/dequeue messages to/from AQ JMS.

The framework allows AQ JMS ConnectionFactory and Destination objects to be bound

into Weblogic JNDI (and the code actually creates these bindings at WLS startup). By

doing this, it allows JEE applications deployed in Weblogic Server to use the normal

JMS mechanisms for using AQ JMS (since AQ JMS does not have native support for

JNDI lookups of ConnectionFactory and Destination objects).

After the implementation of AQJMS Framework, the AQ JMS will be local to Weblogic as

JNDI objects. Please see the below picture for more clarity:

Figure 3



After implementing the AQJMS framework, a JMS Bridge can be created from Weblogic

queues to AQ JMS queues. Since, both the Weblogic JMS and AQ JMS are within the

Weblogic container (via JNDI), a Bridge with transaction can be created and used which

suffice our requirement.

The final configuration will be as follows:

Figure 4



AQJMS (Robert Patrick) framework implementation steps

Implementing AQJMS Framework is pretty easy. All the steps are mentioned in the README.txt

in the AQJMS.zip file.

1. Unzip the AQJMS.zip. We get AQJMS Directory with all the required files. In this, we

need only the StartupClass directory. Other two directories are of not interest to us in

this exercise.

2. Let’s assume the directory where AQJMS is extracted is called AQJMSHOME. Next , we

need to change $AQJMSHOME/build.properties file to reflect the libraries.



Following properties have to be changed:

a. oracle.aq.client.jar - point to the location where we have the Jar file located.

b. oracle.jdbc.driver.jar - point to the location where we have the Jar file located.

c. oracle.jms.common.jar - point to the location where we have the Jar file located.

d. oracle.jta.jar - point to the location where we have the Jar file located.

e. wl.home – enter the directory name to Welogic server eg: $ /installs/bea/weblogic92

By default, both the WLS 9.0 and WLS 10.0 properties are enabled (weblogic.version

and weblogic.jms.version and wl.home). Please comment out the unwanted version’s

properties.

3. For our implementation, the StartupClass folder is the most important one. This folder

contains all the classes needed to expose AQ queues into Weblogic JNDI. Goto

StartupClass folder in the $AQJMSHOME.



4. There are two files that needs to be edited : setEnv90.cmd (choose the approriate

version’s cmd file) and aqjms.properties.

Unfortunately, there are no Linux scripts (setEnv90.cmd) and all the scripts are window

based. So, just copy the existing script and change it accordingly to Linux commands.

setEnv90.cmd:

Has the environment details. Point them accordingly to your environment.

Following properties needs to be set:

a. WL_HOME

b. JAVA_HOME

c. PATH

d. CLASSPATH

There is another variable ‘ORACLE_HOME’. This should point to the location where my

Oracle software (database or the client) is installed. But if we don’t want to install the

Oracle, that should be fine. We can just get the necessary JAR files from Oracle Home

and keep them in a folder and point them in the CLASSPATH and that will work fine. I

don’t have ORACLE_HOME, I copied the files to a directory named ‘jar_files’ and use

them in the classpath.

Following is my configuration in setEnv90.sh:

export WL_HOME=/sundev/sunenv706/bea92MP1/weblogic92

export JAVA_HOME=/sundev/sunenv706/bea92MP1/jdk150_06

export PATH=$JAVA_HOME/bin:$WL_HOME/server/bin:$PATH

export CLASSPATH=$WL_HOME/server/lib/weblogic.jar:/sundev/aiadev1osm7/AQJMS/jar_

files/ojdbc14.jar:/sundev/aiadev1osm7/AQJMS/jar_files/aqapi13.jar

aqjms.properties:

This file has the properties to be set for Database and AQ JMS objects to be exposed.

Following properties needs to be set:

a. Server

b. Port

c. DBInstance

d. XAQueueConnectionFactoryJNDIName

e. QueueConnectionFactoryJNDIName



f. QueueName1

g. QueueJNDIName1

My requirement needs only the XAQueueConnectionFactoryJNDIName and

QueueConnectionFactoryJNDIName. There are properties for Topic as well. Please set

them if needed else we can comment them out.

QueueName# denotes the Queues in the AQ and that needs to be exposed. You can

add as many queues as possible.

QueueJNDIName# denotes the JNDI name in Weblogic to which the AQ Queue to be

binded. Weblogic will look into this JNDI to connect to the queue. There has to be a

JNDI name exisiting for the AQ else the queue will not be visible to Weblogic JMS.

Similarly, there are entries for Topic and TopicJNDI as well. Use them as per need else

can comment out.

Following is my aqjms.properties:

5. Ensure the utility ANT is there in the PATH (do $which ant) and then goto

$AQJMSHOME/StartupClass and run $ant. This action will then compile the classes in



the “src” directory and build a AQJMSStartupClass.jar file in

$AQJMSHOME/StartupClass/lib/WLS90 directory.

6. Then append this JAR file in the CLASSPATH as follows:

$export CLASSPATH = $AQJMSHOME/StartupClass/lib/WLS90/

AQJMSStartupClass.jar:$CLASSPATH

And run the following command:

$ java com.oracle.oems.weblogic.AQJMSPasswordUtility -username jmsuser -password

jmsuser

Where, jmsuser is the username and password in the Oracle Database where the

queues are present. Remember that, in the aqjms.properties, we gave the Oracle

database details but didn’t give the username and password to connect to the queues.

That is because of the security reason that anyone having access to this file will know

the DB details and also user credentials.

The above command will encrypt the username and password and then create a file

called aqjms_user.properties, and stores the values in this file.

7. Now, we need to setup this JAR file as StartupClass to the Weblogic server so that

whenever the Weblogic Server is starting up, it tries to connect to the Oracle Database

and get the AQ queues details and bind them to the Weblogic JNDI.

For this, include the JAR into the classpath of the Weblogic and make an entry into the

Startup Class of Weblogic server configuration.



a. To include the JAR file into the Classpath, edit setDomainEnv.sh. This file is located

in the $[USER_PROJECTS]/domains/[AdminServer]/bin directory. Append the JAR

file to the classpath as follows:

AQ_CLASSPATH=$/usr/lib/AQJMSStartupClass.jar:/usr/lib/aqapi13.jar

export AQ_CLASSPATH

CLASSPATH=…………:$AQ_CLASSPATH

export CLASSPATH

Please substitute the values accordingly. Also, add aqapi.jar file to the aq_classpath.

8. Two additional properties are needed to be set for the Weblogic server:

a. -Doracle.jms.useEmulatedXA=false

b. -Doracle.jms.useNativeXA=true

Set these properties in the startWebLogic.sh file located in

$[USER_PROJECTS]/domains/[AdminServer]/bin directory as follows:



Goto # START WEBLOGIC section and modify as follows:

# START WEBLOGIC echo "starting weblogic with Java version:" ${JAVA_HOME}/bin/java ${JAVA_VM} -version if [ "${WLS_REDIRECT_LOG}" = "" ] ; then echo "Starting WLS with line:" echo "${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblog ic.policy ${PROXY_SETTINGS} ${SERVER_CLASS}" ${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.pol icy ${PROXY_SETTINGS} -Doracle.jms.useEmulatedXA=false -Doracle.jms.useNativeXA=true ${SERVER_CLASS} else echo "Redirecting output from WLS window to ${WLS_REDIRECT_LOG}" ${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${JAVA_OPTIONS} -Dweblogic.Name=${SERVER_NAME} -Djava.security.policy=${WL_HOME}/server/lib/weblogic.pol icy ${PROXY_SETTINGS} -Doracle.jms.useEmulatedXA=false -Doracle.jms.useNativeXA=true ${SERVER_CLASS} >"${WLS_REDIRECT_LOG}" 2>&1 fi



9. The final step would be to specify the AQJMSStartupClass as a Startup class to the

Weblogic server so that this JAR file is loaded and executed when the Weblogic starts.

But before that, let us see the JNDI Tree to ensure there are no AQ objects available.

a. For this, goto Weblogic console -> under Environment section, click on Server ->

click on AdminServer -> and click on View JNDI Tree.



The below JNDI objects are the default JNDI objects which are available before AQJMS

framework is started.



b. Now, to include StartupClass, goto Weblogic console -> under Environment section,

click on Startup and Shutdown classes -> click on Lock and Edit -> and click on New.



c. Select “Startup Class” and click on Next

d. Enter name as “AQJMS_Startup” (can be anything) and specify the Class Name as:

com.oracle.oems.weblogic.AQJMSStartupClass -- and click on Next, select

AdminServer as Target and click on Finish.



e. Now, again, click on the Startup class and enter the details as follows:

Arguments:

AQJMSPropertiesFile=aqjms.properties,AQJMSPasswordFile=aqjms_user.properties,A

QJMSSecretFile=aqjms.dat,AQJMSConfigDirectory=/sundev/aiadev1osm7/AQJMS/Start

upClass

f. Select “Failure is Fatal” and “Run before Application Activation” checkboxes

g. Save the configuration and click on “Activate Changes” and RESTART the Weblogic.



h. Now, again goto the JNDI Tree and now we will see all the AQ queues that are there

in the Oracle AQ available to us a JNDI objects in the Weblogic.



Creating the JMS Bridge between AQ and Weblogic queues:

1. To create a JMS Bridge, first create the destinations. For that, click on the Servers >

Messaging > Bridges > Destinations on the Left hand side tree.

2. Enter the bridge destination details as follows:

The above figure is the source (i.e., AQ queue details). Except for Name,

ConnectionFactory and Destination JNDI, other details can be left empty.



3. Enter the target destination details (i.e., Weblogic queue details)

Here also, we can just enter the Name, ConnectionFactory and Destination JNDI and leave

others empty including InitialContextFactory, Username and password.

4. Once the Destinations are ready, now create a bridge. For that, click on click on the

Servers > Messaging > Bridges on the Left hand side tree.



5. Enter the name and select the checkbox “Started”

6. Choose the Source and Destination





Note: For both the Source and Target, choose the Messaging Provider as Weblogic Server

7.0 or higher because for both the AQ and Weblogic, all JMS objects are now local to the

Weblogic server via JNDI.

7. Choose the Target server as Admin Server and click on Finish.



8. Click on Activate changes and restart the server if prompted.



Now, you can enqueue the message into the AQ using PLSQL APIs or via BPEL/ESB or

anyway and you can see that the JMS Bridge consumes that message and pass it to the

Weblogic queue. This action can also be viewed in the Weblogic console or in the

AdminServer.log file.

Tips:

1. All the Weblogic / bridge configuration is available in the

$[USER_PROJECTS]/domains/[AdminServer]/config/config.xml file. The experienced Weblogic

administrator / user can edit this file and restart the server quickly.

2. For transaction-enabled bridging use the Adapter JNDI name as:

eis.jms.WLConnectionFactoryJNDIXA. For non-transactions, use

eis.jms.WLConnectionFactoryJNDINOXA.



Quick Troubleshooting:

1. Weblogic server doesn’t start and end with an error stating that the JDBC connection has

failed.

Cause: It means that database is NOT up and running or NOT reachable. Since, we have selected the checkboxes “Failure is Fatal” and “Run before Application Activation” checkboxes, the Weblogic stops.

Solution: 1. Start the database or database listener. Also, ensure the database details –

database host, port, SID, username and password are correct in aqjms.properties. 2. Remove the StartupClass if your Database is not up and running (OR) Comment the

StartupClass property in the config.xml so that it is not loaded when Weblogic is started.

3. Uncheck the “Failure is Fatal” so that the Weblogic is started. But note that the StartupClass would still be loaded.

2. If there is an exception that the Source/Target is not reachable, then ensure that you have

got the following similar lines in the Weblogic console / AdminServer.log file:

<Dec 3, 2008 5:22:11 PM EST> <Info> <WebLogicServer> <BEA-000288> <com.oracle.oems.weblogic.AQJMSStartupClass reports: SUCCESS: Bound the following Oracle AQ objects into WebLogic JNDI: XAQueueConnectionFactory -> AQJMS_XAQueueConnectionFactory QueueConnectionFactory -> AQJMS_QueueConnectionFactory Queue(s): 1.) AIA_UPDTT_OSM_OUT_JMSQ -> AIA_UPDTT_OSM_OUT_JNDI 2.) AIA_UPDSO_OUT_JMSQ -> AIA_UPDSO_OUT_JNDI 3.) AIA_UPDCUST_IN_JMSQ -> AIA_UPDCUST_IN_JNDI 4.) AIA_UPDBO_IN_JMSQ -> AIA_UPDBO_IN_JNDI 5.) AIA_SUSFO_OUT_JMSQ -> AIA_SUSFO_OUT_JNDI 6.) AIA_SALESORDERJMSQUEUE -> AIA_SALESORDERJMSQUEUE_JNDI 7.) AIA_RESFO_OUT_JMSQ -> AIA_RESFO_OUT_JNDI 8.) AIA_GTF_OUT_JMSQ -> AIA_GTF_OUT_JNDI 9.) AIA_FOPROV_OUT_JMSQ -> AIA_FOPROV_OUT_JNDI 10.) AIA_FOPROV_IN_JMSQ -> AIA_FOPROV_IN_JNDI 11.) AIA_FOCFS_IN_JMSQ -> AIA_FOCFS_IN_JNDI 12.) AIA_FALLOUT_IN_JMSQ -> AIA_FALLOUT_IN_JNDI

The above entry is made if the AQJMS Framework is successfully loaded and Weblogic is

able to bind the JNDI to the AQ queues.

Documents

AQ JMS - WL JMS - Bridge Configuration_small