JMS Step 8 - How to Read from an AQ JMS (Advanced Queueing JMS) from a BPEL Process

Welcome to the last post in the series of JMS articles on using JMS queues from within SOA. The previous posts were:

1. JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g
2. JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue
3. JMS Step 3 - Using the QueueReceive.java Sample Program to Read a Message from a JMS Queue
4. JMS Step 4 - How to Create an 11g BPEL Process Which Writes a Message Based on an XML Schema to a JMS Queue
5. JMS Step 5 - How to Create an 11g BPEL Process Which Reads a Message Based on an XML Schema from a JMS Queue
6. JMS Step 6 - How to Set Up an AQ JMS (Advanced Queueing JMS) for SOA Purposes
7. JMS Step 7 - How to Write to an AQ JMS (Advanced Queueing JMS) Queue from a BPEL Process

This example demonstrates how to read a simple message from an Oracle AQ via the WebLogic AQ JMS functionality from a BPEL process and a JMS adapter. It is part of a step-by-step series of samples. If you have not yet reviewed the previous posts, please do so first, as this one references objects created created there.

1. Recap and Prerequisites

In the last two examples we created an Oracle Advanced Queue (AQ) some related JMS objects in WebLogic Server, which allow us to be able to access it via JMS. Here are the objects which were created and their names and JNDI names:

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

In the example JMS Step 7 - How To Write To an AQ JMS Queue From a BPEL Process  we wrote a simple message to that queue. In this example, we will create a composite with a BPEL process, which reads the same message from the AQ JMS using a JMS adapter.

2 . Create a BPEL Composite with a JMS Adapter Partner Link

This step requires that you have a valid Application Server Connection defined in JDeveloper, pointing to the application server on which you created the JMS Queue and Connection Factory. You can create this connection in JDeveloper under the Application Server Navigator. Give it any name and be sure to test the connection before completing it.

This sample will read a simple XML message from the AQ JMS queue via the JMS adapter, based on the following XSD file, which consists of a single string element. A message based on this XSD was written to the queue in the previous example.

stringPayload.xsd

<?xml version="1.0" encoding="windows-1252" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"                xmlns="http://www.example.org"                targetNamespace="http://www.example.org"                elementFormDefault="qualified">  <xsd:element name="exampleElement" type="xsd:string">  </xsd:element> </xsd:schema>

The following steps are all executed in JDeveloper. The SOA project will be created inside a JDeveloper Application. If you do not already have an application to contain the project, you can create a new one via File > New > General > Generic Application. Give the application any name, for example JMSTests and, when prompted for a project name and type, call the project   JmsAdapterReadAqJms  and select SOA as the project technology type. If you already have an application, continue below.

Create a SOA Project

Create a new project and select SOA Tier > SOA Project as its type. Name it JmsAdapterReadAqJms . When prompted for the composite type, choose Empty Composite.

Create a JMS Adapter Partner Link

In the composite editor, drag a JMS adapter over from the Component Palette to the left-hand swim lane, under Exposed Services.

Image may be NSFW.
Clik here to view.

This will start the JMS Adapter Configuration Wizard. Use the following entries:

Service Name: JmsAdapterRead
Oracle Enterprise Messaging Service (OEMS): Oracle Advanced Queueing
AppServer Connection: Use an existing application server connection pointing to the WebLogic server on which the connection factory created earlier is located. You can use the “+” button to create a connection directly from the wizard, if you do not already have one.

Adapter Interface > Interface: Define from operation and schema (specified later)

Operation Type: Consume Message
Operation Name: Consume_message

Consume Operation Parameters

Destination Name: Wait for the list to populate. (Only foreign servers are listed here, because Oracle Advanced Queuing was selected earlier, in step 3) .

        Select the foreign server destination created earlier,

AqJmsForeignDestination (queue) .

This will automatically populate the Destination Name field with the name of the foreign destination, queue/USERQUEUE .

JNDI Name: The JNDI name to use for the JMS connection. This is the JNDI name of the connection pool created in the WebLogic Server. JDeveloper does not verify the value entered here. If you enter a wrong value, the JMS adapter won’t find the queue and you will get an error message at runtime. In our example, this is the value eis/aqjms/UserQueue .

Messages

URL: We will use the XSD file created during the previous examples, e.g. the JmsAdapterWriteSchema or JmsAdapterWriteAqJms projects to define the format for the incoming message payload and, at the same time, demonstrate how to import an existing XSD file into a JDeveloper project.

Press the magnifying glass icon to search for schema files. In the Type Chooser, press the Import Schema File button.

Image may be NSFW.
Clik here to view.

Select the next magnifying glass next to URL to search for schema files. Navigate to the location of the JmsAdapterWriteSchema or JmsAdapterWriteAqJms projects > xsd and select the stringPayload.xsd file.

Image may be NSFW.
Clik here to view.

Check the “Copy to Project” checkbox, press OK and confirm the following Localize Files popup.
Image may be NSFW.
Clik here to view.

Now that the XSD file has been copied to the local project, it can be selected from the project’s schema files. Expand Project Schema Files > stringPayload.xsd and select exampleElement : string .

Press Next and Finish, which will complete the JMS Adapter configuration.
Save the project.

Create a BPEL Component

Drag a BPEL Process from the Component Palette (Service Components) to the Components section of the composite designer. Name it JmsAdapterReadAqJms  and select Template: Define Service Later and press OK.

Wire the JMS Adapter to the BPEL Component

Now wire the JMS adapter to the BPEL process, by dragging the arrow from the adapter to the BPEL process. A Transaction Properties popup will be displayed. Set the delivery mode to async.persist. Image may be NSFW.
Clik here to view.

This completes the steps at the composite level.

3. Complete the BPEL Process Design

Invoke the BPEL Flow via the JMS Adapter

Open the BPEL component by double-clicking it in the design view of the composite.xml, or open it from the project navigator by selecting the JmsAdapterReadAqJms.bpel file. This will display the BPEL process in the design view. You should see the JmsAdapterRead partner link in the left-hand swim lane.

Drag a Receive activity onto the BPEL flow diagram, then drag a wire (left-hand yellow arrow) from it to the JMS adapter. This will open the Receive activity editor. Auto-generate the variable by pressing the green “+” button and check the “Create Instance” checkbox. This will result in a BPEL instance being created when a new JMS message is received.

Image may be NSFW.
Clik here to view.

At this point the composite can be deployed and it will pick up any messages from the AQ JMS queue. This is very rudimentary, but is sufficient for our demonstration purposes as we will see in the next step.

As with the previous examples, you can extend the BPEL process to do something useful with the message, such as pass it to another web service, write it to a file using a file adapter or to a database via a database adapter. Also see JMS Step 5 - How To Create an 11g BPEL Process Which Reads a Message Based on an XML Schema from a JMS Queue  for an example of how to add a Java Embedding activity to the process to print the message to standard output.

4. Test the Composite

Execute an instance of the previous example JmsAdapterWriteAqJms  which will write a message to the AQ called UserQueue, if you have not yet done so. That example also explains how to view and monitor the queue from SQL*Plus or JDeveloper. You should see a message similar to the following in the queue:

Image may be NSFW.
Clik here to view.

Now compile and deploy the composite JmsAdapterReadAqJms. It will immediately begin dequeuing messages from the AQ. Requery the queue to confirm that the message has been dequeued. Then, in Enterprise Manager 11g Fusion Middleware Control (EM), navigate to SOA > soa-infra (soa_server1) > default (or wherever you deployed your composite) and click on  JmsAdapterReadAqJms [1.0] . You should see an instance ID listed under Recent Instances. Select it, to view its flow trace, then select the JmsAdapterReadAqJms BPEL Component.

Image may be NSFW.
Clik here to view.

This should display the Audit Trail, including the successful Receive activity. Click on “View XML Document” to see the dequeued message.

Image may be NSFW.
Clik here to view.

This concludes this example and the SOA/JMS series.

Please make use of the comments section for your feedback and questions. If there is enough interest, I will plan to do a series of webcasts to go over and demonstrate the samples shown here.

Thanks-you

John-Brown Evans
Senior Principal Support Engineer
Oracle Technology Proactive Support Delivery