Wednesday Jan 02, 2013

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

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.

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.


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.

Check the “Copy to Project” checkbox, press OK and confirm the following Localize Files popup.

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.

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.

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:

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.

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

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

Wednesday Dec 19, 2012

JMS Step 7 - How to Write to an AQ JMS (Advanced Queueing JMS) Queue from a BPEL Process

JMS Step 7 - How to Write to an AQ JMS (Advanced Queueing JMS) Queue from a BPEL Process

This post continues the series of JMS articles which demonstrate how to use JMS queues in a SOA context. 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

This example demonstrates how to write a simple message to an Oracle AQ via the the WebLogic AQ JMS functionality from a BPEL process and a JMS adapter. If you have not yet reviewed the previous posts, please do so first, especially the JMS Step 6 post, as this one references objects created there.

1. Recap and Prerequisites

In the previous example, we created an Oracle Advanced Queue (AQ) and some related JMS objects in WebLogic Server 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

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 write a simple XML message to the AQ JMS queue via the JMS adapter, based on the following XSD file, which consists of a single string element:

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   JmsAdapterWriteAqJms  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 JmsAdapterWriteAqJms . When prompted for the composite type, choose Composite With BPEL Process.

When prompted for the BPEL Process, name it JmsAdapterWriteAqJms too and choose Synchronous BPEL Process as the template.
This will create a composite with a BPEL process and an exposed SOAP service. Double-click the BPEL process to open and begin editing it. You should see a simple BPEL process with a Receive and Reply activity. As we created a default process without an XML schema, the input and output variables are simple strings.

Create an XSD File

An XSD file is required later to define the message format to be passed to the JMS adapter. In this step, we create a simple XSD file, containing a string variable and add it to the project.

First select the xsd item in the left-hand navigation tree to ensure that the XSD file is created under that item.

Select File > New > General > XML and choose XML Schema.

Call it stringPayload.xsd  and when the editor opens, select the Source view.

then replace the contents with the contents of the stringPayload.xsd example above and save the file. You should see it under the XSD item in the navigation tree.

Create a JMS Adapter Partner Link

We will create the JMS adapter as a service at the composite level. If it is not already open, double-click the composite.xml file in the navigator to open it.

From the Component Palette, drag a JMS adapter over onto the right-hand swim lane, under External References.

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

Service Name: JmsAdapterWrite

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: Produce Message
Operation Name: Produce_message

Produce 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 we created earlier, stringPayload.xsd to define the message format for the JMS adapter. Press the magnifying glass icon to search for schema files. Expand Project Schema Files > stringPayload.xsd and select exampleElement : string .

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

Wire the BPEL Component to the JMS Adapter

In this step, we link the BPEL process/component to the JMS adapter. From the composite.xml editor, drag the right-arrow icon from the BPEL process to the JMS adapter’s in-arrow.

  This completes the steps at the composite level.

3. Complete the BPEL Process Design

Invoke the JMS Adapter

Open the BPEL component by double-clicking it in the design view of the composite.xml. This will display the BPEL process in the design view. You should see the JmsAdapterWrite partner link under one of the two swim lanes. We want it in the right-hand swim lane. If JDeveloper displays it in the left-hand lane, right-click it and choose Display > Move To Opposite Swim Lane.

An Invoke activity is required in order to invoke the JMS adapter. Drag an Invoke activity between the Receive and Reply activities. Drag the right-hand arrow from the Invoke activity to the JMS adapter partner link. This will open the Invoke editor. The correct default values are entered automatically and are fine for our purposes. We only need to define the input variable to use for the JMS adapter. By pressing the green “+” symbol, a variable of the correct type can be auto-generated, for example with the name Invoke1_Produce_Message_InputVariable.

Press OK after creating the variable.

Assign Variables

Drag an Assign activity between the Receive and Invoke activities. We will simply copy the input variable to the JMS adapter and, for completion, so the process has an output to print, again to the process’s output variable.

Double-click the Assign activity and create two Copy rules:

for the first, drag Variables > inputVariable > payload > client:process > client:input_string to Invoke1_Produce_Message_InputVariable > body > ns2:exampleElement

for the second, drag the same input variable to outputVariable > payload > client:processResponse > client:result

This will create two copy rules, similar to the following:

Press OK.

This completes the BPEL and Composite design.

4. Compile and Deploy the Composite

Compile the process by pressing the Make or Rebuild icons or by right-clicking the project name in the navigator and selecting Make... or Rebuild...

If the compilation is successful, deploy it to the SOA server connection defined earlier. (Right-click the project name in the navigator, select Deploy to Application Server, choose the application server connection, choose the partition on the server (usually default) and press Finish. You should see the message

----  Deployment finished.  ----


in the Deployment frame, if the deployment was successful.

5. Test the Composite

Execute a Test Instance

In a browser, log in to the Enterprise Manager 11g Fusion Middleware Control (EM) for your SOA installation. Navigate to SOA > soa-infra (soa_server1) > default (or wherever you deployed your composite) and click on  JmsAdapterWriteAqJms [1.0] , then press the Test button. Enter any string into the text input field, for example “Test message from JmsAdapterWriteAqJms” then press Test Web Service.

If the instance is successful, you should see the same text you entered in the Response payload frame.

Monitor the Advanced Queue

The test message will be written to the advanced queue created at the top of this sample. To confirm it, log in to the database as AQJMSUSER and query the MYQUEUETABLE database table. For example, from a shell window with SQL*Plus

sqlplus aqjmsuser/aqjmsuser

SQL> SELECT user_data FROM myqueuetable;

which will display the message contents, for example

Similarly, you can use the JDeveloper Database Navigator to view the contents. Use a database connection to the AQJMSUSER and in the navigator, expand Queues Tables and select MYQUEUETABLE. Select the Data tab and scroll to the USER_DATA column to view its contents.

This concludes this example.

The following post will be the last one in this series. In it, we will learn how to read the message we just wrote using a BPEL process and AQ JMS.

Best regards
John-Brown Evans
Oracle Technology Proactive Support Delivery

Wednesday Dec 05, 2012

JMS Step 5 - How to Create an 11g BPEL Process Which Reads a Message Based on an XML Schema from 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

Welcome to another post in the series of blogs which demonstrates how to use JMS queues in a SOA context. 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

Today we will create a BPEL process which will read (dequeue) the message from the JMS queue, which we enqueued in the last example. The JMS adapter will dequeue the full XML payload from the queue.

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 designed and deployed a BPEL composite, which took a simple XML payload and enqueued it to the JMS queue. In this example, we will read that same message from the queue, using a JMS adapter and a BPEL process. As many of the configuration steps required to read from that queue were done in the previous samples, this one will concentrate on the new steps. A summary of the required objects is listed below. To find out how to create them please see the previous samples. They also include instructions on how to verify the objects are set up correctly.

WebLogic Server Objects

Object Name

Type

JNDI Name

TestConnectionFactory

Connection Factory

jms/TestConnectionFactory

TestJMSQueue

JMS Queue

jms/TestJMSQueue

eis/wls/TestQueue

Connection Pool

eis/wls/TestQueue

Schema XSD File

The following XSD file is used for the message format. It was created in the previous example and will be copied to the new process.

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>

JMS Message

After executing the previous samples, the following XML message should be in the JMS queue located at jms/TestJMSQueue:

<?xml version="1.0" encoding="UTF-8" ?><exampleElement xmlns="http://www.example.org">Test Message</exampleElement>

JDeveloper Connection

You will need a valid Application Server Connection in JDeveloper pointing to the SOA server which the process will be deployed to.

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

In the previous example, we created a composite in JDeveloper called JmsAdapterWriteSchema. In this one, we will create a new composite called JmsAdapterReadSchema.

There are probably many ways of incorporating a JMS adapter into a SOA composite for incoming messages. One way is design the process in such a way that the adapter polls for new messages and when it dequeues one, initiates a SOA or BPEL instance. This is possibly the most common use case. Other use cases include mid-flow adapters, which are activated from within the BPEL process. In this example we will use a polling adapter, because it is the most simple to set up and demonstrate. But it has one disadvantage as a demonstrative model. When a polling adapter is active, it will dequeue all messages as soon as they reach the queue. This makes it difficult to monitor messages we are writing to the queue, because they will disappear from the queue as soon as they have been enqueued. To work around this, we will shut down the composite after deploying it and restart it as required. (Another solution for this would be to pause the consumption for the queue and resume consumption again if needed. This can be done in the WLS console JMS-Modules -> queue -> Control -> Consumption -> Pause/Resume.)

We will model the composite as a one-way incoming process. Usually, a BPEL process will do something useful with the message after receiving it, such as passing it to a database or file adapter, a human workflow or external web service. But we only want to demonstrate how to dequeue a JMS message using BPEL and a JMS adapter, so we won’t complicate the design with further activities. However, we do want to be able to verify that we have read the message correctly, so the BPEL process will include a small piece of embedded java code, which will print the message to standard output, so we can view it in the SOA server’s log file. Alternatively, you can view the instance in the Enterprise Manager and verify the message.

The following steps are all executed in JDeveloper. Create the project in the same JDeveloper application used for the previous examples or create a new one.

Create a SOA Project

Create a new project and choose SOA Tier > SOA Project as its type. Name it JmsAdapterReadSchema. 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.

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

Service Name: JmsAdapterRead

Oracle Enterprise Messaging Service (OEMS): Oracle WebLogic JMS

AppServer Connection: Use an application server connection pointing to the WebLogic server on which the JMS queue and connection factory mentioned under Prerequisites above are located.

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

Operation Type: Consume Message
Operation Name:
Consume_message

Consume Operation Parameters

Destination Name: Press the Browse button, select Destination Type: Queues, then press Search. Wait for the list to populate, then select the entry for TestJMSQueue , which is the queue created in a previous example.

JNDI Name: The JNDI name to use for the JMS connection. As in the previous example, this is probably the most common source of error. This is the JNDI name of the JMS adapter’s connection pool created in the WebLogic Server and which points to the connection factory. 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, which is very difficult to trace. In our example, this is the value eis/wls/TestQueue . (See the earlier step on how to create a JMS Adapter Connection Pool in WebLogic Server for details.)


Messages/Message Schema
URL:
We will use the XSD file created during the previous example, in the JmsAdapterWriteSchema project 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.


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

Check the “Copy to Project” checkbox, press OK and confirm the following Localize Files popup.

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 JmsAdapterReadSchema 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.

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 JmsAdapterReadSchema.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.

At this point it would actually be OK to compile and deploy the composite and it would pick up any messages from the JMS queue. In fact, you can do that to test it, if you like. But it is very rudimentary and would not be doing anything useful with the message. Also, you could only verify the actual message payload by looking at the instance’s flow in the Enterprise Manager.

There are various other possibilities; we could pass the message to another web service, write it to a file using a file adapter or to a database via a database adapter etc. But these will all introduce unnecessary complications to our sample. So, to keep it simple, we will add a small piece of Java code to the BPEL process which will write the payload to standard output. This will be written to the server’s log file, which will be easy to monitor.

Add a Java Embedding Activity

First get the full name of the process’s input variable, as this will be needed for the Java code. Go to the Structure pane and expand Variables > Process > Variables. Then expand the input variable, for example, "Receive1_Consume_Message_InputVariable > body > ns2:exampleElement”, and note variable’s name and path, if they are different from this one.

Drag a Java Embedding activity from the Component Palette (Oracle Extensions) to the BPEL flow, after the Receive activity, then open it to edit.


Delete the example code and replace it with the following, replacing the variable parts with those in your sample, if necessary.:

System.out.println("JmsAdapterReadSchema process picked up a message");

oracle.xml.parser.v2.XMLElement inputPayload =  

 (oracle.xml.parser.v2.XMLElement)getVariableData(

                          "Receive1_Consume_Message_InputVariable",

                          "body",

                          "/ns2:exampleElement");  

String inputString = inputPayload.getFirstChild().getNodeValue();

System.out.println("Input String is " + inputPayload.getFirstChild().getNodeValue());

Tip. If you are not sure of the exact syntax of the input variable, create an Assign activity in the BPEL process and copy the variable to another, temporary one. Then check the syntax created by the BPEL designer.

This completes the BPEL process design in JDeveloper. Save, compile and deploy the process to the SOA server.

3. Test the Composite

Shut Down the JmsAdapterReadSchema Composite

After deploying the JmsAdapterReadSchema composite to the SOA server it is automatically activated. If there are already any messages in the queue, the adapter will begin polling them. To ease the testing process, we will deactivate the process first

Log in to the Enterprise Manager (Fusion Middleware Control) and navigate to SOA > soa-infra (soa_server1) > default (or wherever you deployed your composite to) and click on JmsAdapterReadSchema [1.0] . Press the Shut Down button to disable the composite and confirm the following popup.

Monitor Messages in the JMS Queue

In a separate browser window, log in to the WebLogic Server Console and navigate to Services > Messaging > JMS Modules > TestJMSModule > TestJMSQueue > Monitoring. This is the location of the JMS queue we created in an earlier sample (see the prerequisites section of this sample). Check whether there are any messages already in the queue. If so, you can dequeue them using the QueueReceive Java program created in an earlier sample. This will ensure that the queue is empty and doesn’t contain any messages in the wrong format, which would cause the JmsAdapterReadSchema to fail.

Send a Test Message

In the Enterprise Manager, navigate to the JmsAdapterWriteSchema created earlier, press Test and send a test message, for example “Message from JmsAdapterWriteSchema”.

Confirm that the message was written correctly to the queue by verifying it via the queue monitor in the WLS Console.

Monitor the SOA Server’s Output

A program deployed on the SOA server will write its standard output to the terminal window in which the server was started, unless this has been redirected to somewhere else, for example to a file. If it has not been redirected, go to the terminal session in which the server was started, otherwise open and monitor the file to which it was redirected.

Re-Enable the JmsAdapterReadSchema Composite

In the Enterprise Manager, navigate to the JmsAdapterReadSchema composite again and press Start Up to re-enable it. This should cause the JMS adapter to dequeue the test message and the following output should be written to the server’s standard output:

JmsAdapterReadSchema process picked up a message.

Input String is Message from JmsAdapterWriteSchema

Note that you can also monitor the payload received by the process, by navigating to the the JmsAdapterReadSchema’s Instances tab in the Enterprise Manager. Then select the latest instance and view the flow of the BPEL component. The Receive activity will contain and display the dequeued message too.

4 . Troubleshooting

This sample demonstrates how to dequeue an XML JMS message using a BPEL process and no additional functionality. For example, it doesn’t contain any error handling. Therefore, any errors in the payload will result in exceptions being written to the log file or standard output. If you get any errors related to the payload, such as

Message handle error
...
ORABPEL-09500
...
XPath expression failed to execute.
An error occurs while processing the XPath expression; the expression is 
     /ns2:exampleElement.
...
etc.

check that the variable used in the Java embedding part of the process was entered correctly. Possibly follow the tip mentioned in previous section. If this doesn’t help, you can delete the Java embedding part and simply verify the message via the flow diagram in the Enterprise Manager. Or use a different method, such as writing it to a file via a file adapter.

This concludes this example. In the next post, we will begin with an AQ JMS example, which uses JMS to write to an Advanced Queue stored in the database.

Best regards
John-Brown Evans
Oracle Technology Proactive Support Delivery

Wednesday Nov 28, 2012

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 4 - How to Create an 11g BPEL Process Which Writes a Message Based on an XML Schema to a JMS Queue

This post continues the series of JMS articles which demonstrate how to use JMS queues in a SOA context. 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

In this example we will create a BPEL process which will write (enqueue) a message to a JMS queue using a JMS adapter. The JMS adapter will enqueue the full XML payload to the queue.

This sample will use the following WebLogic Server objects. The first two, the Connection Factory and JMS Queue, were created as part of the first blog post in this series, JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g. If you haven't created those objects yet, please see that post for details on how to do so.

The Connection Pool will be created as part of this example.

Object Name

Type

JNDI Name

TestConnectionFactory

Connection Factory

jms/TestConnectionFactory

TestJMSQueue

JMS Queue

jms/TestJMSQueue

eis/wls/TestQueue

Connection Pool

eis/wls/TestQueue

1. Verify Connection Factory and JMS Queue

As mentioned above, this example uses a WLS Connection Factory called TestConnectionFactory and a JMS queue TestJMSQueue. As these are prerequisites for this example, let us verify they exist.

Log in to the WebLogic Server Administration Console.

Select Services > JMS Modules > TestJMSModule

You should see the following objects:

If not, or if the TestJMSModule is missing, please see the abovementioned article and create these objects before continuing.

2. Create a JMS Adapter Connection Pool in WebLogic Server

The BPEL process we are about to create uses a JMS adapter to write to the JMS queue. The JMS adapter is deployed to the WebLogic server and needs to be configured to include a connection pool which references the connection factory associated with the JMS queue.

  1. In the WebLogic Server Console
  2. Go to Deployments > Next and select (click on) the JmsAdapter
  3. Select Configuration > Outbound Connection Pools and expand oracle.tip.adapter.jms.IJmsConnectionFactory. This will display the list of connections configured for this adapter. For example, eis/aqjms/Queue, eis/aqjms/Topic etc.
    These JNDI names are actually quite confusing. We are expecting to configure a connection pool here, but the names refer to queues and topics.


    One would expect these to be called *ConnectionPool or *_CF or similar, but to conform to this nomenclature, we will call our entry
    eis/wls/TestQueue . This JNDI name is also the name we will use later, when creating a BPEL process to access this JMS queue!
  4. Select New, check the oracle.tip.adapter.jms.IJmsConnectionFactory check box and Next.
  5. Enter JNDI Name: eis/wls/TestQueue
    for the connection instance, then press Finish.
  6. Expand oracle.tip.adapter.jms.IJmsConnectionFactory again and select (click on) eis/wls/TestQueue


  7. The ConnectionFactoryLocation must point to the JNDI name of the connection factory associated with the JMS queue you will be writing to. In our example, this is the connection factory called TestConnectionFactory, with the JNDI name jms/TestConnectionFactory.
    (
    As a reminder, this connection factory is contained in the JMS Module called TestJMSModule, under Services > Messaging > JMS Modules > TestJMSModule which we verified at the beginning of this document. )

    Enter
    jms/TestConnectionFactory  into the Property Value field for Connection Factory Location. After entering it, you must 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 as can be seen in the following screen shot:


  8. The next step is to 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


  9. 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 JMS queue.

To summarize: we have created a JMS adapter connection pool connector with the JNDI name jms/TestConnectionFactory. This is the JNDI name to be accessed by a process such as a BPEL process, when using the JMS adapter to access the previously created JMS queue with the JNDI name jms/TestJMSQueue.

In the following step, we will set up a BPEL process to use this JMS adapter to write to the JMS queue.

3. 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 use the connection name jbevans-lx-PS5, as that is the name of the connection pointing to my SOA PS5 installation.

When using a JMS adapter from within a BPEL process, there are various configuration options, such as the operation type (consume message, produce message etc.), delivery mode and message type. One of these options is the choice of the format of the JMS message payload. This can be structured around an existing XSD, in which case the full XML element and tags are passed, or it can be opaque, meaning that the payload is sent as-is to the JMS adapter. In the case of an XSD-based message, the payload can simply be copied to the input variable of the JMS adapter. In the case of an opaque message, the JMS adapter’s input variable is of type base64binary. So the payload needs to be converted to base64 binary first. I will go into this in more detail in a later blog entry.

This sample will pass a simple message to the adapter, based on the following simple XSD file, which consists of a single string element:

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 JmsAdapterWriteWithXsd 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 choose SOA Tier > SOA Project as its type. Name it JmsAdapterWriteSchema. When prompted for the composite type, choose Composite With BPEL Process.

When prompted for the BPEL Process, name it JmsAdapterWriteSchema too and choose Synchronous BPEL Process as the template.

This will create a composite with a BPEL process and an exposed SOAP service. Double-click the BPEL process to open and begin editing it. You should see a simple BPEL process with a Receive and Reply activity. As we created a default process without an XML schema, the input and output variables are simple strings.

Create an XSD File

An XSD file is required later to define the message format to be passed to the JMS adapter. In this step, we create a simple XSD file, containing a string variable and add it to the project.

First select the xsd item in the left-hand navigation tree to ensure that the XSD file is created under that item.

Select File > New > General > XML and choose XML Schema.

Call it stringPayload.xsd and when the editor opens, select the Source view.

then replace the contents with the contents of the stringPayload.xsd example above and save the file. You should see it under the xsd item in the navigation tree.

Create a JMS Adapter Partner Link

We will create the JMS adapter as a service at the composite level. If it is not already open, double-click the composite.xml file in the navigator to open it.

From the Component Palette, drag a JMS adapter over onto the right-hand swim lane, under External References.

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

Service Name: JmsAdapterWrite

Oracle Enterprise Messaging Service (OEMS): Oracle Weblogic JMS

AppServer Connection: Use an existing application server connection pointing to the WebLogic server on which the above JMS queue and connection factory were created. You can use the “+” button to create a connection directly from the wizard, if you do not already have one. This example uses a connection called jbevans-lx-PS5.

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

Operation Type: Produce Message
Operation Name:
Produce_message

Destination Name: Press the Browse button, select Destination Type: Queues, then press Search. Wait for the list to populate, then select the entry for TestJMSQueue , which is the queue created earlier.


JNDI Name:
The JNDI name to use for the JMS connection. This is probably the most important step in this exercise and the most common source of error. This is the JNDI name of the JMS adapter’s connection pool created in the WebLogic Server and which points to the connection factory. 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, which is very difficult to trace. In our example, this is the value eis/wls/TestQueue . (See the earlier step on how to create a JMS Adapter Connection Pool in WebLogic Server for details.)

Messages
URL:
We will use the XSD file we created earlier, stringPayload.xsd to define the message format for the JMS adapter. Press the magnifying glass icon to search for schema files. Expand Project Schema Files > stringPayload.xsd and select exampleElement: string.

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

Wire the BPEL Component to the JMS Adapter

In this step, we link the BPEL process/component to the JMS adapter. From the composite.xml editor, drag the right-arrow icon from the BPEL process to the JMS adapter’s in-arrow.

This completes the steps at the composite level.

4. Complete the BPEL Process Design

Invoke 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 JmsAdapterWriteSchema.bpel file. This will display the BPEL process in the design view. You should see the JmsAdapterWrite partner link under one of the two swim lanes. We want it in the right-hand swim lane. If JDeveloper displays it in the left-hand lane, right-click it and choose Display > Move To Opposite Swim Lane.

An Invoke activity is required in order to invoke the JMS adapter. Drag an Invoke activity between the Receive and Reply activities. Drag the right-hand arrow from the Invoke activity to the JMS adapter partner link. This will open the Invoke editor. The correct default values are entered automatically and are fine for our purposes. We only need to define the input variable to use for the JMS adapter. By pressing the green “+” symbol, a variable of the correct type can be auto-generated, for example with the name Invoke1_Produce_Message_InputVariable.

Press OK after creating the variable.

( For some reason, while I was testing this, the JMS Adapter moved back to the left-hand swim lane again after this step. There is no harm in leaving it there, but I find it easier to follow if it is in the right-hand lane, because I kind-of think of the message coming in on the left and being routed through the right. But you can follow your personal preference here.)

Assign Variables

Drag an Assign activity between the Receive and Invoke activities. We will simply copy the input variable to the JMS adapter and, for completion, so the process has an output to print, again to the process’s output variable.

Double-click the Assign activity and create two Copy rules:

for the first, drag Variables > inputVariable > payload > client:process > client:input_string to Invoke1_Produce_Message_InputVariable > body > ns2:exampleElement

for the second, drag the same input variable to outputVariable > payload > client:processResponse > client:result

This will create two copy rules, similar to the following:

Press OK.

This completes the BPEL and Composite design.

5. Compile and Deploy the Composite

We won’t go into too much detail on how to compile and deploy.

In JDeveloper, compile the process by pressing the Make or Rebuild icons or by right-clicking the project name in the navigator and selecting Make... or Rebuild...

If the compilation is successful, deploy it to the SOA server connection defined earlier. (Right-click the project name in the navigator, select Deploy to Application Server, choose the application server connection, choose the partition on the server (usually default) and press Finish. You should see the message

---- Deployment finished. ----


in the Deployment frame, if the deployment was successful.

6. Test the Composite

This is the exciting part.

Open two tabs in your browser and log in to the WebLogic Administration Console in one tab and the Enterprise Manager 11g Fusion Middleware Control (EM) for your SOA installation in the other. We will use the Console to monitor the messages being written to the queue and the EM to execute the composite.

In the Console, go to Services > Messaging > JMS Modules > TestJMSModule > TestJMSQueue > Monitoring. Note the number of messages under Messages Current.

In the EM, go to SOA > soa-infra (soa_server1) > default (or wherever you deployed your composite to) and click on JmsAdapterWriteSchema [1.0], then press the Test button.

Under Input Arguments, enter any string into the text input field for the payload, for example Test Message then press Test Web Service.

If the instance is successful you should see the same text in the Response message, “Test Message”.

In the Console, refresh the Monitoring screen to confirm a new message has been written to the queue.

Check the checkbox and press Show Messages. Click on the newest message and view its contents. They should include the full XML of the entered payload.

7. Troubleshooting

If you get an exception similar to the following at runtime

...
BINDING.JCA-12510
JCA Resource Adapter location error.
Unable to locate the JCA Resource Adapter via .jca binding file element 
The JCA Binding Component is unable to startup the Resource Adapter specified in the
  element:  location='eis/wls/QueueTest'.
The reason for this is most likely that either
1) the Resource Adapters RAR file has not been deployed successfully to the WebLogic 
 Application server or
2) the '' element in weblogic-ra.xml has not been set to eis/wls/QueueTest. 
 In the last case you will have to add a new WebLogic JCA connection factory 
  (deploy a RAR).
Please correct this and then restart the Application Server

       at oracle.integration.platform.blocks.adapter.fw.AdapterBindingException.
         createJndiLookupException(AdapterBindingException.java:130)
       at oracle.integration.platform.blocks.adapter.fw.jca.cci.
         JCAConnectionManager$JCAConnectionPool.createJCAConnectionFactory
         (JCAConnectionManager.java:1387)
       at oracle.integration.platform.blocks.adapter.fw.jca.cci.
         JCAConnectionManager$JCAConnectionPool.newPoolObject
         (JCAConnectionManager.java:1285)
...

then this is very likely due to an incorrect JNDI name entered for the JMS Connection in the JMS Adapter Wizard. Recheck those steps. The error message prints the name of the JNDI name used. In this example, it was incorrectly entered as eis/wls/QueueTest instead of eis/wls/TestQueue.

This concludes this example.

Best regards
John-Brown Evans
Oracle Technology Proactive Support Delivery

About

This is the official blog of the SOA Proactive Support Team. Here we will provide information on our activities, publications, product related information and more. Additionally we look forward to your feedback to improve what we do.

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today