JMS Step 6 - How to Set Up an AQ JMS (Advanced Queueing JMS) for SOA
Purposes
.jblist{list-style-type:disc;margin:0;padding:0;padding-left:0pt;margin-left:36pt}
ol{margin:0;padding:0}
.c17_6{vertical-align:top;width:468pt;border-style:solid;border-color:#000000;border-width:1pt;padding:5pt 5pt 5pt 5pt}
.c5_6{vertical-align:top;border-style:solid;border-color:#000000;border-width:1pt;padding:0pt 5pt 0pt 5pt}
.c6_6{vertical-align:top;width:156pt;border-style:solid;border-color:#000000;border-width:1pt;padding:5pt 5pt 5pt 5pt}
.c15_6{background-color:#ffffff}
.c10_6{color:#1155cc;text-decoration:underline}
.c1_6{text-align:center;direction:ltr}
.c0_6{line-height:1.0;direction:ltr}
.c16_6{color:#666666;font-size:12pt}
.c18_6{color:inherit;text-decoration:inherit}
.c8_6{background-color:#f3f3f3}
.c2_6{direction:ltr}
.c14_6{font-size:8pt}
.c11_6{font-size:10pt}
.c7_6{font-weight:bold}
.c12_6{height:0pt}
.c3_6{height:11pt}
.c13_6{border-collapse:collapse}
.c4_6{font-family:"Courier New"}
.c9_6{font-style:italic}
.title{padding-top:24pt;line-height:1.15;text-align:left;color:#000000;font-size:36pt;font-family:"Arial";font-weight:bold;padding-bottom:6pt}
.subtitle{padding-top:18pt;line-height:1.15;text-align:left;color:#666666;font-style:italic;font-size:24pt;font-family:"Georgia";padding-bottom:4pt}
li{color:#000000;font-size:10pt;font-family:"Arial"}
p{color:#000000;font-size:10pt;margin:0;font-family:"Arial"}
h1{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:24pt;font-family:"Arial";font-weight:normal}
h2{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:18pt;font-family:"Arial";font-weight:normal}
h3{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:14pt;font-family:"Arial";font-weight:normal}
h4{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:12pt;font-family:"Arial";font-weight:normal}
h5{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:11pt;font-family:"Arial";font-weight:normal}
h6{padding-top:0pt;line-height:1.15;text-align:left;color:#888;font-size:10pt;font-family:"Arial";font-weight:normal}
This post continues the series of JMS articles which demonstrate
how to use JMS queues in a SOA context. The previous posts were:
JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g
JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue
JMS Step 3 - Using the QueueReceive.java Sample Program to Read a Message from a JMS Queue
JMS Step 4 - How to Create an 11g BPEL Process Which Writes a Message Based on an XML Schema to a JMS Queue
JMS Step 5 - How to Create an 11g BPEL Process Which Reads a Message Based on an XML Schema from a JMS Queue
This example leads you through the creation of an Oracle database
Advanced Queue and the related WebLogic server objects in order to
use AQ JMS in connection with a SOA composite. If you have not already done so,
I recommend you look at the previous posts in this series, as they include steps
which this example builds upon.
The following examples will demonstrate how to write and read from the
queue from a SOA process.
1. Recap and Prerequisites
In the previous examples, we created a JMS Queue, a Connection
Factory and a Connection Pool in the WebLogic Server Console. Then
we wrote and deployed BPEL composites, which enqueued and dequeued a
simple XML payload.
AQ JMS allows you to interoperate with database Advanced Queueing
via JMS in WebLogic server and therefore take advantage of database
features, while maintaining compliance with the JMS architecture. AQ
JMS uses the WebLogic JMS Foreign Server framework. A full
description of this functionality can be found in the following
Oracle documentation
Oracle® Fusion Middleware Configuring and Managing
JMS for Oracle WebLogic Server
11g Release 1 (10.3.6)
Part Number E13738-06
7. Interoperating with Oracle AQ JMS
http://docs.oracle.com/cd/E23943_01/web.1111/e13738/aq_jms.htm#CJACBCEJ
For easier reference, this sample will use the same names for the
objects as in the above document, except for the name of the
database user, as it is possible that this user already exists in
your database. We will create the following objects
Database Objects
Name
Type
AQJMSUSER
Database User
MyQueueTable
Advanced Queue (AQ) Table
UserQueue
Advanced Queue
WebLogic Server Objects
Object Name
Type
JNDI Name
aqjmsuserDataSource
Data Source
jdbc/aqjmsuserDataSource
AqJmsModule
JMS System Module
AqJmsForeignServer
JMS Foreign Server
AqJmsForeignServerConnectionFactory
JMS Foreign Server Connection Factory
AqJmsForeignServerConnectionFactory
AqJmsForeignDestination
AQ JMS Foreign Destination
queue/USERQUEUE
eis/aqjms/UserQueue
Connection Pool
eis/aqjms/UserQueue
2. Create a Database User and Advanced Queue
The following steps can be executed in the database client of your
choice, e.g. JDeveloper or SQL Developer. The examples below use
SQL*Plus.
Log in to the database as a DBA user, for example SYSTEM or SYS.
Create the AQJMSUSER user and grant privileges to enable the user to
create AQ objects.
Create Database User and Grant AQ Privileges
sqlplus system/password as SYSDBA
GRANT connect, resource TO aqjmsuser IDENTIFIED BY aqjmsuser;
GRANT aq_user_role TO aqjmsuser;
GRANT execute ON sys.dbms_aqadm TO aqjmsuser;
GRANT execute ON sys.dbms_aq TO aqjmsuser;
GRANT execute ON sys.dbms_aqin TO aqjmsuser;
GRANT execute ON sys.dbms_aqjms TO aqjmsuser;
Create the Queue Table and Advanced Queue and Start the AQ
The following commands are executed as the aqjmsuser database user.
Create the Queue Table
connect aqjmsuser/aqjmsuser;
BEGIN
dbms_aqadm.create_queue_table (
queue_table = 'myQueueTable',
queue_payload_type = 'sys.aq$_jms_text_message',
multiple_consumers = false
);
END;
/
Create the AQ
BEGIN
dbms_aqadm.create_queue (
queue_name = 'userQueue',
queue_table = 'myQueueTable'
);
END;
/
Start the AQ
BEGIN
dbms_aqadm.start_queue (
queue_name = 'userQueue');
END;
/
The above commands can be executed in a single PL/SQL block, but are
shown as separate blocks in this example for ease of reference.
You can verify the queue by executing the SQL command
SELECT object_name, object_type FROM user_objects;
which should display the following objects:
OBJECT_NAME OBJECT_TYPE
------------------------------ -------------------
SYS_C0056513 INDEX
SYS_LOB0000170822C00041$$ LOB
SYS_LOB0000170822C00040$$ LOB
SYS_LOB0000170822C00037$$ LOB
AQ$_MYQUEUETABLE_T INDEX
AQ$_MYQUEUETABLE_I INDEX
AQ$_MYQUEUETABLE_E QUEUE
AQ$_MYQUEUETABLE_F VIEW
AQ$MYQUEUETABLE VIEW
MYQUEUETABLE TABLE
USERQUEUE QUEUE
Similarly, you can view the objects in JDeveloper via a Database
Connection to the AQJMSUSER.
3. Configure WebLogic Server and Add JMS Objects
All these steps are executed from the WebLogic Server Administration
Console. Log in as the webLogic user.
Configure a WebLogic Data Source
The data source is required for the database connection to the AQ
created above.
Navigate to domain >
Services >
Data Sources
and press
New then
Generic Data
Source.
Use the values:Name: aqjmsuserDataSource
JNDI Name: jdbc/aqjmsuserDataSource
Database type: Oracle
Database Driver: *Oracle’ Driver (Thin XA) for Instance
connections; Versions:9.0.1 and later
Connection Properties: Enter the connection information to the
database containing the AQ created above and enter
aqjmsuser
for the User Name and Password.
Press Test Configuration to verify the connection details and press
Next.
Target the data source to the soa server.
The data source will be displayed in the list.
It is a good idea to test the data source at this stage. Click on
aqjmsuserDataSource, select Monitoring > Testing > soa_server1
and press Test Data Source. The result is displayed at the top of
the page.
Configure a JMS System Module
The JMS system module is required to host the JMS foreign server for
AQ resources.
Navigate to Services > Messaging > JMS Modules and select New.
Use the values:
Name: AqJmsModule
(Leave Descriptor File Name and Location in Domain empty.)
Target: soa_server1
Click Finish. The other resources will be created in separate steps.
The module will be displayed in the list.
Configure a JMS Foreign Server
A foreign server is required in order to reference a 3rd-party JMS
provider, in this case the database AQ, within a local WebLogic
server JNDI tree.
Navigate to Services > Messaging > JMS Modules and select
(click on) AqJmsModule to configure it.
Under Summary of Resources, select New then Foreign Server.
Name: AqJmsForeignServer
Targets: The foreign server is targeted automatically to
soa_server1, based on the JMS module’s target.
Press Finish to create the foreign server.
The foreign server resource will be listed in the Summary of
Resources for the AqJmsModule, but needs additional configuration
steps.
Click on AqJmsForeignServer and select Configuration > General to
complete the configuration:
JNDI Initial Context Factory:
oracle.jms.AQjmsInitialContextFactory
JNDI Connection URL: <empty>
JNDI Properties Credential:<empty>
Confirm JNDI Properties Credential: <empty>
JNDI Properties:
datasource=jdbc/aqjmsuserDataSource
This is an important property. It is the JNDI name of
the data source created above, which points to the AQ schema in
the database and must be entered as a name=value pair, as in
this example, e.g. datasource=jdbc/aqjmsuserDataSource, including
the “datasource=” property name.
Default Targeting Enabled: Leave this value checked.
Press Save to save the configuration.
At this point it is a good idea to verify that the data
source was written correctly to the config file. In a terminal window,
navigate to
$MIDDLEWARE_HOME/user_projects/domains/soa_domain/config/jms
and open the file
aqjmsmodule-jms.xml
. The foreign server configuration should contain
the datasource name-value pair, as follows:
<foreign-server name="AqJmsForeignServer">
<default-targeting-enabled>true</default-targeting-enabled>
<initial-context-factory>oracle.jms.AQjmsInitialContextFactory</initial-context-factory>
<jndi-property>
<key>
datasource
</key>
<value>
jdbc/aqjmsuserDataSource
</value>
</jndi-property>
</foreign-server>
</weblogic-jms>
Configure a JMS Foreign Server Connection Factory
When creating the foreign server connection factory, you enter local
and remote JNDI names. The name of the connection factory itself and
the local JNDI name are arbitrary, but the remote JNDI name must
match a specific format, depending on the type of queue or topic to
be accessed in the database. This is very important and if the
incorrect value is used, the connection to the queue will not be
established and the error messages you get will not immediately
reflect the cause of the error. The formats required (Remote JNDI
names for AQ JMS Connection Factories) are described in the section
Configure AQ
Destinations
of the
Oracle® Fusion Middleware Configuring and Managing
JMS for Oracle WebLogic Server
document mentioned earlier.
In this example, the remote JNDI name used is
XAQueueConnectionFactory
because it matches the AQ and data source created earlier, i.e.
thin with AQ.
Navigate to JMS Modules > AqJmsModule > AqJmsForeignServer >
Connection Factories then New.Name: AqJmsForeignServerConnectionFactory
Local JNDI Name: AqJmsForeignServerConnectionFactory
Note: this local JNDI name is the JNDI name which your
client application, e.g. a later BPEL process, will use
to access this connection factory.
Remote JNDI Name: XAQueueConnectionFactory
Press OK to save the configuration.
Configure an AQ JMS Foreign Server Destination
A foreign server destination maps the JNDI name on the foreign JNDI
provider to the respective local JNDI name, allowing the foreign
JNDI name to be accessed via the local server. As with the foreign
server connection factory, the local JNDI name is arbitrary (but
must be unique), but the remote JNDI name must conform to a specific
format defined in the section
Configure AQ
Destinations
of the
Oracle® Fusion Middleware Configuring and Managing
JMS for Oracle WebLogic Server
document mentioned earlier.
In our example, the remote JNDI name is
Queues/USERQUEUE
, because it references a queue (as opposed to a topic) with the name USERQUEUE.
We will name the local JNDI name queue/USERQUEUE, which is a little confusing (note
the missing “s” in “queue), but conforms better to the JNDI
nomenclature in our SOA server and also allows us to differentiate between
the local and remote names for demonstration purposes.
Navigate to JMS Modules > AqJmsModule > AqJmsForeignServer >
Destinations and select New.Name: AqJmsForeignDestination
Local JNDI Name: queue/USERQUEUE
Remote JNDI Name:Queues/USERQUEUE
After saving the foreign destination configuration, this completes
the JMS part of the configuration. We still need to configure the
JMS adapter in order to be able to access the queue from a BPEL
processt.
4. Create a JMS Adapter Connection Pool in Weblogic Server
Create the Connection Pool
Access to the AQ JMS queue from a BPEL or other SOA process in our
example is done via a JMS adapter. To enable this, the JmsAdapter in
WebLogic server needs to be configured to have a connection pool
which points to the local connection factory JNDI name which was
created earlier.
Navigate to Deployments > Next and select (click on) the
JmsAdapter.
Select Configuration > Outbound Connection Pools and New.
Check the radio button for
oracle.tip.adapter.jms.IJmsConnectionFactory and press Next.
JNDI Name: eis/aqjms/UserQueue
Press Finish
Expand oracle.tip.adapter.jms.IJmsConnectionFactory and click on
eis/aqjms/UserQueue to configure it.
The ConnectionFactoryLocation must point to the foreign
server’s local connection factory name created earlier.
In our example, this is
AqJmsForeignServerConnectionFactory
.
As a reminder, this connection factory is located under JMS Modules
> AqJmsModule > AqJmsForeignServer > Connection Factories and the value needed
here is under Local JNDI Name.
Enter
AqJmsForeignServerConnectionFactory
into the Property Value field for ConnectionFactoryLocation. You must
then press Return/Enter then Save for the value to be accepted.
If your WebLogic server is running in Development mode, you should
see the message that the changes have been activated and the
deployment plan successfully updated. If not, then you will manually
need to activate the changes in the WebLogic server console.Although
the changes have been activated, the JmsAdapter needs to be redeployed
in order for the changes to become effective. This should be
confirmed by the message
Remember to update your deployment to reflect the new plan when
you are finished with your changes.
Redeploy the JmsAdapter
Navigate back to the Deployments screen, either by selecting it in
the left-hand navigation tree or by selecting the “Summary of
Deployments” link in the breadcrumbs list at the top of the
screen. Then select the checkbox next to JmsAdapter and press the
Update button.
On the Update Application Assistant page, select “Redeploy
this application using the following deployment files” and
press Finish.
After a few seconds you should get the message that the selected
deployments were updated.
The JMS adapter configuration is complete and it can now be used to
access the AQ JMS queue. You can verify that the JNDI name was
created correctly, by navigating to Environment > Servers >
soa_server1 and View JNDI Tree. Then scroll down in the JNDI Tree
Structure to eis and select aqjms.
This concludes the sample.
In the following post, I will show you how to create a BPEL process which sends a message
to this advanced queue via JMS.
Best regards
John-Brown Evans
Oracle Technology Proactive Support Delivery
