Thursday Dec 13, 2012

RDA Health Checks for SOA

What is a health check in RDA?

A health check evaluates something in your environment to determine whether a change needs to be considered in order to avoid a problem or optimize fuctionality. Examples of what this 'something' might be are:
  • Configuration Parameters
  • JVM Options
  • Runtime Statistics

What have we done for SOA?

In the latest release of RDA, 4.30, we have added a Rule Set for SOA called 'Oracle SOA 11g (11.1.1) Post Installation (Generic)'. This Rule Set contains 14 SOA related health checks.

These checks were all derived from common issues / solutions we see in support of the SOA product. Many of the recommendations come from the product documentation while others are covered in the SOA Knowledge Base. Our goal is that you will be able to easily identify the areas of concern and understand the guidance available from the output of the Rule Set.

Running the health checks for SOA

The rules that the checks use are installed with RDA and bundled by product or functional area into what are called 'Rule Sets'. To view the available Rule Sets simply run the command from the RDA home location:

rda.cmd (or .sh) -dT hcve

This will bring up a list of the available HCVE (Health Check / Verification Engine) Rule Sets. Each Rule Set contains a group of related rules that are used for evalutation and display of results. A rule can be considered synonymous with a single health check and they are assigned an ID, Name and Description that can be seen when they are executed. The Rule Set for SOA is option number 11 and you just enter this selection at the prompt. The Rule Set will then execute to completion. After running an HCVE Rule Set the tool will write the output to the RDA_HOME/output folder. The simplest way to view the output is to drag the .htm file to a browser but of course it can also be uploaded to a Service Request for evaluation by Oracle Support.

Many of the Rule Sets will prompt you for information before they can execute their rules but the SOA Rule Set will identify the SOA domains configured in your RDA setup.cfg file. This means that you don't need to answer all of the questions again about where stuff is but it also means that you must have configured RDA for SOA. To run the Rule Set:
  • Download the latest version of RDA from MOS Doc ID 314422.1
  • Configure RDA for your SOA domains. Detailed steps can be found here In it's simplest form the command is 'rda.cmd (.sh) -S SOA'
  • Go to the RDA home location and enter the command 'rda.cmd (or .sh) -dT hcve'
  • Select the option for 'Oracle SOA 11g (11.1.1) Post Installation (Generic)'


It should be noted that this our first release of a SOA Rule Set so there will probably be some things we need to clean up or fix. None of these rules will actually modify anything on your system as they are read only and do the evaluations internally. Please let us know if you have any issues with the rules or ideas for new ones so we can make them as useful as possible.

The Checks

Here is a list of the SOA health checks by ID, Name and Description.
ID Name Description
A00100 SOA Domain Homes Lists the SOA domains that were indentified from the RDA setup.cfg file
A00200 Coherence Protocol Conflict Checks to see if you have both Unicast and Multicast configured in the same domain. Checks both the setDomainEnv and config.xml entries (if it exists). We recommend Unicast with fully qualified host names or IP addresses.
A00210 Coherence Fully Qualified Host Checks that the host names are fully qualified or that IP addresses are used. Will fail if unqualified host names are detected.
A00220 Unicast Local Host Checks that the Coherence localhost is specified for use with Unicast
A00300 JTA Timeout Checks that the JTA timeout is configured for the domain and lists the value. The bundled rule will only list the current values of the JTA timeout for each SOA Domain. In the future the rule with fail with a warning if the value is 300 seconds or lower. It is recommended that timeouts follow the pattern 'syncMaxWaitTime' < EJB Timeouts < JTA Timeout. The 300 second value is important because the EJB Timeouts default to 300 seconds. Additional information can be found in MOS Doc ID 880313.1.
A00310 XA Max Time Checks that the JTA Maximum XA call time is set for the domain. Fails if it is not explicitly set or if the value is less than or equal to 12000 ms.

Note: In the current release this rule mistakenly assumes the default value to be 12000 instead of the true default value of 120000
A00320 XA Timeout Checks that the XA timeout is enabled and that the value is '0' for the SOA Data Source (SOADataSource-jdbc.xml)
A00330 JDBC Statement Timeout Checks that the Statement Timeout is set for all SOA Data Sources. Fails if the value is not set or if it is set to the default of -1.
A00400 XA Driver Checks that the SOA Data Source is configured to use an XA driver. Fails if it is not.
A00410 JDBC Capacity Settings Checks that the minimum and maximum capacity are equal for all SOA Data Sources. Fails if they are not and lists specifically which data sources failed.
A00500 SOA Roles Checks that the default SOA roles 'SOAAdmin' and 'SOAOperator' are configured for the soa-infra application in the file sytem-jazn-data.xml. Fails if they are not.
A00700 SOA-INFRA Deployment Checks that the soa-infra application is deployed to either a cluster, all members of a cluster or a stand alone server.
A00710 SOA Deployments Checks that the SOA related applications are deployed to the same domain members as soa-infra.
A00720 SOA Library Deployments Checks that the SOA related libraries are deployed to the same domain members as soa-infra.
A00730 Data Source Deployments Checks that the SOA Data Sources are all targeted to the same domain members as soa-infra

Wednesday Dec 12, 2012

JMS Step 6 - How to Set Up an AQ JMS (Advanced Queueing JMS) for SOA Purposes

JMS Step 6 - How to Set Up an AQ JMS (Advanced Queueing JMS) for SOA Purposes

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

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

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

Wednesday Nov 21, 2012

JMS Step 3 - Using the QueueReceive.java Sample Program to Read a Message from a JMS Queue

JMS Step 3 - Using the QueueReceive.java Sample Program to Read a Message from a JMS Queue

This post continues the series of JMS articles which demonstrate how to use JMS queues in a SOA context.

In the first post,
JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g
we looked at how to create a JMS queue and its dependent objects in WebLogic Server.

In the previous post,
JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue
I showed how to write a message to that JMS queue using the QueueSend.java sample program.

In this article, we will use a similar sample, the QueueReceive.java program to read the message from that queue. Please review the previous posts if you have not already done so, as they contain prerequisites for executing the sample in this article.

1. Source code

The following java code will be used to read the message(s) from the JMS queue. As with the previous example, it is based on a sample program shipped with the WebLogic Server installation. The sample is not installed by default, but needs to be installed manually using the WebLogic Server Custom Installation option, together with many, other useful samples. You can either copy-paste the following code into your editor, or install all the samples.

The knowledge base article in My Oracle Support:

How To Install WebLogic Server and JMS Samples in WLS 10.3.x (Doc ID 1499719.1)

describes how to install the samples.

QueueReceive.java

package examples.jms.queue;

import java.util.Hashtable;
import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

/**
* This example shows how to establish a connection to
* and receive messages from a JMS queue. The classes in this
* package operate on the same JMS queue. Run the classes together to
* witness messages being sent and received, and to browse the queue
* for messages.  This class is used to receive and remove messages
* from the queue.
*
* @author Copyright (c) 1999-2005 by BEA Systems, Inc. All Rights Reserved.
*/
public class QueueReceive implements MessageListener
{
 // Defines the JNDI context factory.
 public final static String JNDI_FACTORY="weblogic.jndi.WLInitialContextFactory";

 // Defines the JMS connection factory for the queue.
 public final static String JMS_FACTORY="jms/TestConnectionFactory";

 // Defines the queue.
 public final static String QUEUE="jms/TestJMSQueue";

 private QueueConnectionFactory qconFactory;
 private QueueConnection qcon;
 private QueueSession qsession;
 private QueueReceiver qreceiver;
 private Queue queue;
 private boolean quit = false;

/**
 * Message listener interface.
 * @param msg  message
 */
 public void onMessage(Message msg)
 {
    try {
     String msgText;
     if (msg instanceof TextMessage) {
       msgText = ((TextMessage)msg).getText();
     } else {
       msgText = msg.toString();
     }

     System.out.println("Message Received: "+ msgText );

     if (msgText.equalsIgnoreCase("quit")) {
       synchronized(this) {
         quit = true;
         this.notifyAll(); // Notify main thread to quit
       }
     }
    } catch (JMSException jmse) {
     System.err.println("An exception occurred: "+jmse.getMessage());
    }
 }

 /**
  * Creates all the necessary objects for receiving
  * messages from a JMS queue.
  *
  * @param   ctx    JNDI initial context
  * @param    queueName    name of queue
  * @exception NamingException if operation cannot be performed
  * @exception JMSException if JMS fails to initialize due to internal error
  */
 public void init(Context ctx, String queueName)
    throws NamingException, JMSException
 {
    qconFactory = (QueueConnectionFactory) ctx.lookup(JMS_FACTORY);
    qcon = qconFactory.createQueueConnection();
    qsession = qcon.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
    queue = (Queue) ctx.lookup(queueName);
    qreceiver = qsession.createReceiver(queue);
    qreceiver.setMessageListener(this);
    qcon.start();
 }

 /**
  * Closes JMS objects.
  * @exception JMSException if JMS fails to close objects due to internal error
  */
 public void close()throws JMSException
 {
    qreceiver.close();
    qsession.close();
    qcon.close();
 }
/**
 * main() method.
 *
 * @param args  WebLogic Server URL
 * @exception  Exception if execution fails
 */

 public static void main(String[] args) throws Exception {
    if (args.length != 1) {
     System.out.println("Usage: java examples.jms.queue.QueueReceive WebLogicURL");
     return;
    }
    InitialContext ic = getInitialContext(args[0]);
    QueueReceive qr = new QueueReceive();
    qr.init(ic, QUEUE);

    System.out.println(
        "JMS Ready To Receive Messages (To quit, send a \"quit\" message).");

    // Wait until a "quit" message has been received.
    synchronized(qr) {
     while (! qr.quit) {
       try {
         qr.wait();
       } catch (InterruptedException ie) {}
     }
    }
    qr.close();
 }

 private static InitialContext getInitialContext(String url)
    throws NamingException
 {
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, JNDI_FACTORY);
    env.put(Context.PROVIDER_URL, url);
    return new InitialContext(env);
 }
}

2. How to Use This Class

2.1 From the file system on Linux

This section describes how to use the class from the file system of a WebLogic Server installation.

Log in to a machine with a WebLogic Server installation and create a directory to contain the source and code matching the package name, e.g. span>$HOME/examples/jms/queue. Copy the above QueueReceive.java file to this directory.

  1. Set the CLASSPATH and environment to match the WebLogic server environment.
    Go to
    $MIDDLEWARE_HOME/user_projects/domains/base_domain/bin  and execute

    . ./setDomainEnv.sh
  2. Collect the following information required to run the script:
  1. The JNDI name of the JMS queue to use
    In the WebLogic server console > Services > Messaging > JMS Modules > Module name, (e.g.
    TestJMSModule) > JMS queue name, (e.g. TestJMSQueue)
    select the queue and note its JNDI name,
    e.g.
    jms/TestJMSQueue
  2. The JNDI name of the connection factory to use to connect to the queue
    Follow the same path as above to get the connection factory for the above queue, e.g. TestConnectionFactory and its JNDI name
    e.g.
    jms/TestConnectionFactory
  3. The URL and port of the WebLogic server running the above queue
    Check the JMS server for the above queue and the managed server it is targeted to, for example soa_server1. Now find the port this managed server is listening on, by looking at its entry under Environment > Servers in the WLS console,
    e.g. 8001
    The URL for the server to be passed to the QueueReceive program will therefore be t3://host.domain:8001
    e.g.
    t3://jbevans-lx.de.oracle.com:8001
  1. Edit Queue Receive .java and enter the above queue name and connection factory respectively under

...
public final static String  JMS_FACTORY="jms/TestConnectionFactory";
...
public final static String QUEUE="jms/TestJMSQueue";
...

  1. Compile Queue Receive .java using

    javac Queue Receive .java
  2. Go to the source’s top-level directory and execute it using

    java examples.jms.queue.Queue Receive   t3://jbevans-lx.de.oracle.com:8001
  3. This will print a message that it is ready to receive messages or to send a “quit” message to end.
  4. The program will read all messages in the queue and print them to the standard output until it receives a message with the payload “quit”.

2.2 From JDeveloper

The steps from JDeveloper are the same as those used for the previous program QueueSend.java, which is used to send a message to the queue. So we won't repeat them here. Please see the previous blog post at
JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue
and apply the same steps in that example to the QueueReceive.java program.

This concludes the example. In the following post we will create a BPEL process which writes a message based on an XML schema to the queue.

Wednesday Nov 14, 2012

JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue

JMS Step 2 - Using the QueueSend.java Sample Program to Send a Message to a JMS Queue

This post is the second in a series of JMS articles which demonstrate how to use JMS queues in a SOA context.

In the previous post
JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g
I showed you how to create a JMS queue and its dependent objects in WebLogic Server. In this article, we will use a sample program to write a message to that queue. Please review the previous post if you have not created those objects yet, as they will be required later in this example. The previous post also includes useful background information and links to the Oracle documentation for addional research.

The following post in this series will show how to read the message from the queue again.

1. Source code

The following java code will be used to write a message to the JMS queue. It is based on a sample program provided with the WebLogic Server installation. The sample is not installed by default, but needs to be installed manually using the WebLogic Server Custom Installation option, together with many, other useful samples. You can either copy-paste the following code into your editor, or install all the samples.

The knowledge base article in My Oracle Support:

How To Install WebLogic Server and JMS Samples in WLS 10.3.x (Doc ID 1499719.1)

describes how to install the samples.

QueueSend.java

package examples.jms.queue;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.util.Hashtable;
import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

/** This example shows how to establish a connection
* and send messages to the JMS queue. The classes in this
* package operate on the same JMS queue. Run the classes together to
* witness messages being sent and received, and to browse the queue
* for messages. The class is used to send messages to the queue.
*
* @author Copyright (c) 1999-2005 by BEA Systems, Inc. All Rights Reserved.
*/
public class QueueSend
{
 // Defines the JNDI context factory.
 public final static String JNDI_FACTORY="weblogic.jndi.WLInitialContextFactory";

 // Defines the JMS context factory.
 public final static String JMS_FACTORY="jms/TestConnectionFactory";

 // Defines the queue.
 public final static String QUEUE="jms/TestJMSQueue";

 private QueueConnectionFactory qconFactory;
 private QueueConnection qcon;
 private QueueSession qsession;
 private QueueSender qsender;
 private Queue queue;
 private TextMessage msg;

 /**
  * Creates all the necessary objects for sending
  * messages to a JMS queue.
  *
  * @param ctx JNDI initial context
  * @param queueName name of queue
  * @exception NamingException if operation cannot be performed
  * @exception JMSException if JMS fails to initialize due to internal error
  */
 public void init(Context ctx, String queueName)
    throws NamingException, JMSException
 {
    qconFactory = (QueueConnectionFactory) ctx.lookup(JMS_FACTORY);
    qcon = qconFactory.createQueueConnection();
    qsession = qcon.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
    queue = (Queue) ctx.lookup(queueName);
    qsender = qsession.createSender(queue);
    msg = qsession.createTextMessage();
    qcon.start();
 }

 /**
  * Sends a message to a JMS queue.
  *
  * @param message  message to be sent
  * @exception JMSException if JMS fails to send message due to internal error
  */
 public void send(String message) throws JMSException {
    msg.setText(message);
    qsender.send(msg);
 }

 /**
  * Closes JMS objects.
  * @exception JMSException if JMS fails to close objects due to internal error
  */
 public void close() throws JMSException {
    qsender.close();
    qsession.close();
    qcon.close();
 }
/** main() method.
 *
 * @param args WebLogic Server URL
 * @exception Exception if operation fails
 */
 public static void main(String[] args) throws Exception {
    if (args.length != 1) {
     System.out.println("Usage: java examples.jms.queue.QueueSend WebLogicURL");
     return;
    }
    InitialContext ic = getInitialContext(args[0]);
    QueueSend qs = new QueueSend();
    qs.init(ic, QUEUE);
    readAndSend(qs);
    qs.close();
 }

 private static void readAndSend(QueueSend qs)
    throws IOException, JMSException
 {
    BufferedReader msgStream = new BufferedReader(new InputStreamReader(System.in));
    String line=null;
    boolean quitNow = false;
    do {
     System.out.print("Enter message (\"quit\" to quit): \n");
     line = msgStream.readLine();
     if (line != null && line.trim().length() != 0) {
       qs.send(line);
       System.out.println("JMS Message Sent: "+line+"\n");
       quitNow = line.equalsIgnoreCase("quit");
     }
    } while (! quitNow);

 }

 private static InitialContext getInitialContext(String url)
    throws NamingException
 {
    Hashtable env = new Hashtable();
    env.put(Context.INITIAL_CONTEXT_FACTORY, JNDI_FACTORY);
    env.put(Context.PROVIDER_URL, url);
    return new InitialContext(env);
 }
}

2. How to Use This Class

2.1 From the file system on UNIX/Linux

Log in to a machine with a WebLogic installation and create a directory to contain the source and code matching the package name, e.g. $HOME/examples/jms/queue. Copy the above QueueSend.java file to this directory.

  1. Set the CLASSPATH and environment to match the WebLogic server environment.
    Go to
    $MIDDLEWARE_HOME/user_projects/domains/base_domain/bin  and execute

    . ./setDomainEnv.sh
  2. Collect the following information required to run the script:
  1. The JNDI name of a JMS queue to use

    In the Weblogic server console > Services > Messaging > JMS Modules > (Module name, e.g.
    TestJMSModule) > (JMS queue name, e.g. TestJMSQueue)
    Select the queue and note its JNDI name,
    e.g.
    jms/TestJMSQueue
  2. The JNDI name of a connection factory to connect to the queue

    Follow the same path as above to get the connection factory for the above queue, e.g.
    TestConnectionFactory and its JNDI name
    e.g.
    jms/TestConnectionFactory
  3. The URL and port of the WebLogic server running the above queue
    Check the JMS server for the above queue and the managed server it is targeted to, for example soa_server1. Now find the port this managed server is listening on, by looking at its entry under Environment > Servers in the WLS console,
    e.g. 8001
    The URL for the server to be given to the QueueSend program in this example will therefore be t3://host.domain:8001
    e.g.
    t3://jbevans-lx.de.oracle.com:8001
  1. Edit QueueSend.java and enter the above queue name and connection factory respectively under

...
public final static String  JMS_FACTORY="
jms/TestConnectionFactory ";

...
public final static String QUEUE="
jms/TestJMSQueue ";

...

  1. Compile QueueSend.java using

    javac QueueSend.java
  2. Go to the source’s top-level directory and execute it using

    java examples.jms.queue.QueueSend t3://jbevans-lx.de.oracle.com:8001
  3. This will prompt for a text input or “quit” to end.
  4. In the WLS console, go to the queue and select Monitoring to confirm that a new message was written to the queue.

2.2 From JDeveloper

  1. Create a new application in JDeveloper, called, for example JMSTests.
  2. When prompted for a project name, enter QueueSend and select Java as the technology


  3. Default Package = examples.jms.queue (but you can enter anything here as you will overwrite it in the code later).
    Leave the other values at their defaults.



  4. Press Finish
  5. Create a new Java class called QueueSend and use the default values



    This will create a file called QueueSend.java.
  6. Open QueueSend.java, if it is not already open and replace all its contents with the QueueSend java code listed above


  7. Some lines might have warnings due to unfound objects.
    These are due to missing libraries in the JDeveloper project.



  8. Add the following libraries to the JDeveloper project:
  1. right-click the QueueSend  project in the navigation menu and select Libraries and Classpath , then Add JAR/Directory
  2.  Go to the folder containing the JDeveloper installation and find/choose the file javax.jms_1.1.1.jar , e.g. at D:\oracle\jdev11116\modules\javax.jms_1.1.1.jar



    Do the same for the weblogic.jar file located, for example in D:\oracle\jdev11116\wlserver_10.3\server\lib\weblogic.jar



  1. Now you should be able to compile the project, for example by selecting the Make or Rebuild icons


     
  2. If you try to execute the project, you will get a usage message, as it requires a parameter pointing to the WLS installation containing the JMS queue, for example t3://jbevans-lx.de.oracle.com:8001 . You can automatically pass this parameter to the program from JDeveloper by editing the project’s Run/Debug/Profile.
    Select the project properties, select Run/Debug/Profile and edit the Default run configuration



    and add the connection parameter to the Program Arguments field



    If you execute it again, you will see that it has passed the parameter to the start command


  3. If you get a ClassNotFoundException for the class weblogic.jndi.WLInitialContextFactory , then check that the weblogic.jar file was correctly added to the project in one of the earlier steps above.

Set the values of JMS_FACTORY and QUEUE the same way as described above in the description of how to use this from a Linux file system, i.e.

...
public final static String  JMS_FACTORY="
jms/TestConnectionFactory ";

...
public final static String QUEUE="
jms/TestJMSQueue ";

...

  1. You need to make one more change to the project. If you execute it now, it will prompt for the payload for the JMS message, but you won’t be able to enter it by default in JDeveloper. You need to enable program input for the project first.

    Select the project’s properties, then Tool Settings, then check the Allow Program Input checkbox at the bottom and Save.


  2. Now when you execute the project, you will get a text entry field at the bottom into which you can enter the payload. You can enter multiple messages until you enter “quit”, which will cause the program to stop.



The following screen shot shows the TestJMSQueue’s Monitoring page, after a message was sent to the queue:


This concludes the sample. In the following post I will show you how to read the message from the queue again.

Wednesday Nov 07, 2012

JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g

JMS Step 1 - How to Create a Simple JMS Queue in Weblogic Server 11g

This example shows the steps to create a simple JMS queue in WebLogic Server 11g for testing purposes. For example, to use with the two sample programs QueueSend.java and QueueReceive.java which will be shown in later examples.

Additional, detailed information on JMS 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
http://docs.oracle.com/cd/E23943_01/web.1111/e13738/toc.htm

1. Introduction and Definitions

A JMS queue in Weblogic Server is associated with a number of additional resources:

JMS Server

A JMS server acts as a management container for resources within JMS modules. Some of its responsibilities include the maintenance of persistence and state of messages and subscribers. A JMS server is required in order to create a JMS module.

JMS Module

A JMS module is a definition which contains JMS resources such as queues and topics. A JMS module is required in order to create a JMS queue.

Subdeployment

JMS modules are targeted to one or more WLS instances or a cluster. Resources within a JMS module, such as queues and topics are also targeted to a JMS server or WLS server instances. A subdeployment is a grouping of targets. It is also known as advanced targeting.

Connection Factory

A connection factory is a resource that enables JMS clients to create connections to JMS destinations.

JMS Queue

A JMS queue (as opposed to a JMS topic) is a point-to-point destination type. A message is written to a specific queue or received from a specific queue.

The objects used in this example are:

Object Name

Type

JNDI Name

TestJMSServer

JMS Server

TestJMSModule

JMS Module

TestSubDeployment

Subdeployment

TestConnectionFactory

Connection Factory

jms/TestConnectionFactory

TestJMSQueue

JMS Queue

jms/TestJMSQueue

2. Configuration Steps

The following steps are done in the WebLogic Server Console, beginning with the left-hand navigation menu.

2.1 Create a JMS Server

  1. Services > Messaging > JMS Servers

  2. Select New
  3. Name: TestJMSServer
    Persistent Store: (none)
  4. Target: soa_server1  (or choose an available server)
  5. Finish

The JMS server should now be visible in the list with Health OK.

2.2 Create a JMS Module

  1. Services > Messaging > JMS Modules
  2. Select New
  3. Name: TestJMSModule
    Leave the other options empty
  4. Targets: soa_server1  (or choose the same one as the JMS server)
    Press
    Next
  5. Leave “Would you like to add resources to this JMS system module” unchecked and  press Finish .

2.3 Create a SubDeployment

A subdeployment is not necessary for the JMS queue to work, but it allows you to easily target subcomponents of the JMS module to a single target or group of targets. We will use the subdeployment in this example to target the following connection factory and JMS queue to the JMS server we created earlier.

  1. Services > Messaging > JMS Modules
  2. Select TestJMSModule
  3. Select the Subdeployments  tab and New
  4. Subdeployment Name: TestSubdeployment
  5. Press Next
  6. Here you can select the target(s) for the subdeployment. You can choose either Servers (i.e. WebLogic managed servers, such as the soa_server1) or JMS Servers such as the JMS Server created earlier. As the purpose of our subdeployment in this example is to target a specific JMS server, we will choose the JMS Server option.
    Select the
    TestJMSServer created earlier
  7. Press Finish

2.4  Create a Connection Factory

  1. Services > Messaging > JMS Modules
  2. Select TestJMSModule  and press New
  3. Select Connection Factory  and Next
  4. Name: TestConnectionFactory
    JNDI Name:
    jms/TestConnectionFactory
    Leave the other values at default
  5. On the Targets page, select the Advanced Targeting  button and select TestSubdeployment
  6. Press Finish

The connection factory should be listed on the following page with TestSubdeployment and TestJMSServer as the target.

2.5 Create a JMS Queue

  1. Services > Messaging > JMS Modules
  2. Select TestJMSModule  and press New
  3. Select Queue and Next
  4. Name: TestJMSQueue
    JNDI Name: jms/TestJMSQueue
    Template: None
    Press
    Next
  5. Subdeployments: TestSubdeployment
  6. Finish

The TestJMSQueue should be listed on the following page with TestSubdeployment and TestJMSServer.

Confirm the resources for the TestJMSModule. Using the Domain Structure tree, navigate to soa_domain > Services > Messaging > JMS Modules then select TestJMSModule

You should see the following resources

The JMS queue is now complete and can be accessed using the JNDI names

jms/TestConnectionFactory and
j
ms/TestJMSQueue.

In the following blog post in this series, I will show you how to write a message to this queue, using the WebLogic sample Java program QueueSend.java.

Wednesday Oct 31, 2012

Announcing Upcoming SOA and JMS Introductory Blog Posts

Announcing Upcoming SOA and JMS Introductory Blog Posts

Beginning next week, SOA Proactive Support will begin posting a series of introductory blogs here on working with JMS in a SOA context. The posts will begin with how to set up JMS in WebLogic server, lead you through reading and writing to a JMS queue from the WLS Java samples, continue with how to access it from a SOA composite and, finally, describe how to set up and access AQ JMS (Advanced Queuing JMS) from a SOA/BPEL process.

The posts will be of a tutorial nature and include step-by-step examples. Your questions and feedback are encouraged.

The following topics are planned:

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

Monday Oct 22, 2012

SOA PS5 Bundle Patch 4 and OSB PS5 Bundle Patch 1

Announcing the Availability of SOA Suite 11g PS5 Bundled Patch 4 and OSB PS5 Bundle Patch 1

These Bundled Patches contain a number of high impact fixes for PS5 and are recommended for anyone currently using this release. Please review the list of included fixes in the readmes and if you are running with any SOA or OSB patches not included in the Bundled Patches please request for Support to create a one-off on top of the appropriate Bundled Patch.

The patches can be downloaded from My Oracle Support. 'Patches & Updates' -> Enter '14406487' (SOA) or '14389126' (OSB) and click 'Search'.

Further information on specific included fixes can also be found in the following documents on MOS:
SOA 11g: Bundle Patch Reference, Doc ID 1485949.1
OSB 11g: Bundle Patch Reference, Doc ID 1499170.1


Friday Sep 14, 2012

Upcoming Customer WebCast: Adapters and JCA Transport in Oracle Service Bus 11g

There is an upcoming webcast planned for September 19th that will show how to implement services using a JCA adapter in Oracle Service Bus 11g. The session will help to utilize existing resources like samples and information centers for adapters in the context of Oracle Service Bus.

Topics covered in the webcast are:
  • JCA Transport Overview / Inbound and Outbound scenarios using JCA adapters
  • Implementation of an end-to-end use case using an inbound file adapter and and an outbound database adapter in Oracle Service Bus
  • It will show how to find information on supported adapters in a certain version of OSB 11g
  • Available adapter samples for OSB and SOA
  • How to use SOA adapter samples for Oracle Service Bus
  • A live demo of an adapter sample implementation in Oracle Service Bus
  • Information Centers for adapters and Oracle Service Bus information

The presentation recording can by found here after the webcast. Select "Oracle Fusion Middleware" as product.
(https://support.oracle.com/rs?type=doc&id=740966.1)

The schedule for future webcasts can be found in the above mentioned document as well.

Tuesday Sep 04, 2012

Introduction to Human Workflow 11g

Human Workflow is a component of SOA Suite just like BPEL, Mediator, Business Rules, etc. The Human Workflow component allows you to incorporate human intervention in a business process.

You can use Human Workflow to create a business process that requires a manager to approve purchase orders greater than $10,000; or a business process that handles article reviews in which a group of reviewers need to vote/approve an article before it gets published. Human Workflow can handle the task assignment and routing as well as the generation of notifications to the participants.

There are three common patterns or usages of Human Workflow:

1) Approval Scenarios: manage documents and other transactional data through approval chains . For example: approve expense report, vacation approval, hiring approval, etc.

2) Reviews by multiple users or groups: group collaboration and review of documents or proposals. For example, processing a sales quote which is subject to review by multiple people.

3) Case Management: workflows around work management or case management. For example, processing a service request. This could be routed to various people who all need to modify the task. It may also incorporate ad hoc routing which is unknown at design time.

SOA 11g Human Workflow includes the following features:

  • Assignment and routing of tasks to the correct users or groups.
  • Deadlines, escalations, notifications, and other features required for ensuring the timely performance of a task.
  • Presentation of tasks to end users through a variety of mechanisms, including a Worklist application.
  • Organization, filtering, prioritization and other features required for end users to productively perform their tasks.
  • Reports, reassignments, load balancing and other features required by supervisors and business owners to manage the performance of tasks.

Human Workflow Architecture

The Human Workflow component is divided into 3 modules: the service interface, the task definition and the client interface module. The Service Interface handles the interaction with BPEL and other components. The Client Interface handles the presentation of task data through clients like the Worklist application, portals and notification channels. The task definition module is in charge of managing the lifecycle of a task. Who should get the task assigned? What should happen next with the task? When must the task be completed? Should the task be escalated?, etc


Stages and Participants

When you create a Human Task you need to specify how the task is assigned and routed. The first step is to define the stages and participants. A stage is just a logical group. A participant can be a user, a group of users or an application role. The participants indicate the type of assignment and routing that will be performed.

Stages can be sequential or in parallel. You can combine them to create any usage you require. See diagram below:


Assignment and Routing

There are different ways a task can be assigned and routed:

  • Single Approver: task is assigned to a single user, group or role. For example, a vacation request is assigned to a manager. If the manager approves or rejects the request, the employee is notified with the decision. If the task is assigned to a group then once one of managers acts on it, the task is completed.
  • Parallel : task is assigned to a set of people that must work in parallel. This is commonly used for voting. For example, a task gets approved once 50% of the participants approve it. You can also set it up to be a unanimous vote.
  • Serial : participants must work in sequence. The most common scenario for this is management chain escalation.
  • FYI (For Your Information) : task is assigned to participants who can view it, add comments and attachments, but can not modify or complete the task.

Task Actions

The following is the list of actions that can be performed on a task:

  • Claim : if a task is assigned to a group or multiple users, then the task must be claimed first to be able to act on it.
  • Escalate : if the participant is not able to complete a task, he/she can escalate it. The task is reassigned to his/her manager (up one level in a hierarchy).
  • Pushback : the task is sent back to the previous assignee.
  • Reassign :if the participant is a manager, he/she can delegate a task to his/her reports.
  • Release : if a task is assigned to a group or multiple users, it can be released if the user who claimed the task cannot complete the task. Any of the other assignees can claim and complete the task.
  • Request Information and Submit Information : use when the participant needs to supply more information or to request more information from the task creator or any of the previous assignees.
  • Suspend and Resume :if a task is not relevant, it can be suspended. A suspension is indefinite. It does not expire until Resume is used to resume working on the task.
  • Withdraw : if the creator of a task does not want to continue with it, for example, he wants to cancel a vacation request, he can withdraw the task. The business process determines what happens next.
  • Renew : if a task is about to expire, the participant can renew it. The task expiration date is extended one week.

Notifications

Human Workflow provides a mechanism for sending notifications to participants to alert them of changes on a task. Notifications can be sent via email, telephone voice message, instant messaging (IM) or short message service (SMS).

Notifications can be sent when the task status changes to any of the following:

  • Assigned/renewed/delegated/reassigned/escalated
  • Completed
  • Error
  • Expired
  • Request Info
  • Resume
  • Suspended
  • Added/Updated comments and/or attachments
  • Updated Outcome
  • Withdraw
  • Other Actions (e.g. acquiring a task)

Here is an example of an email notification:


Worklist Application

Oracle BPM Worklist application is the default user interface included in SOA Suite. It allows users to access and act on tasks that have been assigned to them. For example, from the Worklist application, a loan agent can review loan applications or a manager can approve employee vacation requests.

Through the Worklist Application users can:

  • Perform authorized actions on tasks, acquire and check out shared tasks, define personal to-do tasks and define subtasks.
  • Filter tasks view based on various criteria.
  • Work with standard work queues, such as high priority tasks, tasks due soon and so on. Work queues allow users to create a custom view to group a subset of tasks in the worklist, for example, high priority tasks, tasks due in 24 hours, expense approval tasks and more.
  • Define custom work queues.
  • Gain proxy access to part of another user's tasks.
  • Define custom vacation rules and delegation rules.
  • Enable group owners to define task dispatching rules for shared tasks.
  • Collect a complete workflow history and audit trail.
  • Use digital signatures for tasks.
  • Run reports like Unattended tasks, Tasks productivity, etc.

Here is a screenshoot of what the Worklist Application looks like. On the right hand side you can see the tasks that have been assigned to the user and the task's detail.


References

Introduction to SOA Suite 11g Human Workflow Webcast

Note 1452937.2 Human Workflow Information Center

Using the Human Workflow Service Component 11.1.1.6

Human Workflow Samples

Human Workflow APIs Java Docs

Tuesday Jul 31, 2012

How to run a RDA collection for SOA without providing a password at runtime?

One of my previous blog posts shows in detail how to collect information for a SOA domain using RDA (Remote Diagnostic Agent):
Diagnose SOA Suite 11g Issues Using RDA (Remote Diagnostic Agent).

However, a complete RDA collection for a SOA Suite domain including database artifacts takes some time. Also specific requirements may make it necessary to run the actual RDA collection at times of low system load. Or via a cron job. Usually, during an RDA collection, which connects to the WebLogic Server or to the database, passwords need to be provided.

In newer versions of RDA, functionality has been added so that passwords may be stored in the setup.cfg file in encrypted format. This can be accomplished by using the -A parameter of RDA.

RDA can collect data for one or more domains. RDA can either figure out the name of the administration user to connect to WebLogic Server, or it will ask for it during the setup phase. After the setup is done, a setup.cfg file is created that contains all information necessary to run a collection. Except passwords needed.

To add password information in order to run a RDA collection in silent mode, run the following commands:
  • For every domain (1..n), add the password for the administration user:
    • rda.[cmd|sh] -A WLS_USER_SOA_DOMi
    Use the number of the domain instead of i, like WLS_USER_SOA_DOM1, ..., WLS_USER_SOA_DOMn
  • For every domain (1..n), add the password for the SOAINFRA database schema user:
    • rda.[cmd|sh] -A YourPrefix_SOAINFRA@myhost.mydomain:1521::oracle_sid


After all passwords are stored in setup.cfg, collections can run in silent mode. They can be scheduled via a cron job or run by scripts.

Wednesday Jul 25, 2012

SOA Suite 11g PS5 Bundled Patch 3 (11.1.1.6.3)

Announcing the Availability of SOA Suite 11g PS5 Bundled Patch 3

This Bundled Patch contains a number of high impact fixes for PS5 and is recommended for anyone currently using this release. Please review the list of included fixes in the readme and if you are running with any SOA patches not included in the Bundled Patch please request for Support to create a one-off on top of the Bundled Patch.

Patch can be downloaded from My Oracle Support. 'Patches & Updates' -> Enter '14082705' and click 'Search'. The patch is 606MB.


Tuesday Jul 24, 2012

Follow Up to Proactive Support Presentation at the Fusion Middleware Summer Camp in Munich

On July 18th, I had the oportunity to present the SOA Proactive Support projects at the Oracle Fusion Middleware Summer Camp in Munich. This post is a follow up in order to provide the material that was covered for your reference.

Thanks to everyone who listened to the sessions and for the interesting discussions around RDA and Selective Tracing and other diagnostic tools.

The link to the event can be found here.

Material

SOA Proactive Support Overview
SOA Diagnostic Tools Overview
Using Selective Tracing with Oracle SOA Suite 11g

Tuesday Jun 12, 2012

Overview of SOA Diagnostics in 11.1.1.6

What tools are available for diagnosing SOA Suite issues?
There are a variety of tools available to help you and Support diagnose SOA Suite issues in 11g but it can be confusing as to which tool is appropriate for a particular situation and what their relationships are. This blog post will introduce the various tools and attempt to clarify what each is for and how they are related. Let's first list the tools we'll be addressing:


This overview is not mean to be a comprehensive guide on using all of these tools, however, extensive reference materials are included that will provide many more details on their execution. Another point to note is that all of these tools are applicable for Fusion Middleware as a whole but specific products may or may not have implemented features to leverage them.

A couple of the tools have a WebLogic Scripting Tool or 'WLST' interface. WLST is a command interface for executing pre-built functions and custom scripts against a domain. A detailed WLST tutorial is beyond the scope of this post but you can find general information here. There are more specific resources in the below sections.

In this post when we refer to 'Enterprise Manager' or 'EM' we are referring to Enterprise Manager Fusion Middleware Control.


RDA (Remote Diagnostic Agent)

RDA is a standalone tool that is used to collect both static configuration and dynamic runtime information from the SOA environment. RDA is generally run manually from the command line against a domain or single server. When opening a new Service Request, including an RDA collection can dramatically decrease the back and forth required to collect logs and configuration information for Support.

After installing RDA you configure it to use the SOA Suite module as decribed in the referenced resources. The SOA module includes the Oracle WebLogic Server (WLS) module by default in order to include all of the relevant information for the environment. In addition to this basic configuration there is also an advanced mode where you can set the number of thread dumps for the collections, log files, Incidents, etc.

When would you use it?
When creating a Service Request or otherwise working with Oracle resources on an issue, capturing environment snapshots to baseline your configuration or to diagnose an issue on your own.

How is it related to the other tools?
RDA is related to DFW in that it collects the last 10 Incidents from the server by default. In a similar manner, RDA is related to ODL through its collection of the diagnostic logs and these may contain information from Selective Tracing sessions.

Examples of what it currently collects: (for details please see the links in the Resources section)
  • Diagnostic Logs (ODL)
  • Diagnostic Framework Incidents (DFW)
  • SOA MDS Deployment Descriptors
  • SOA Repository Summary Statistics
  • Thread Dumps
  • Complete Domain Configuration

RDA Resources: top


DFW (Diagnostic Framework)

DFW provides the ability to collect specific information for a particular problem when that problem occurs. DFW is included with your SOA Suite installation and deployed to the domain. Let's define the components of DFW.
  • Diagnostic Dumps: Specific diagnostic collections that are defined at either the 'system' or product level. Examples would be diagnostic logs or thread dumps.
  • Incident: A collection of Diagnostic Dumps associated with a particular problem
  • Log Conditions: An Oracle Diagnostic Logging event that DFW is configured to listen for. If the event is identified then an Incident will be created.
  • WLDF Watch: The WebLogic Diagnostic Framework or 'WLDF' is not a component of DFW, however, it can be a source of DFW Incident creation through the use of a 'Watch'.
  • WLDF Notification: A Notification is a component of WLDF and is the link between the Watch and DFW. You can configure multiple Notification types in WLDF and associate them with your Watches. 'FMWDFW-notification' is available to you out of the box to allow for DFW notification of Watch execution.
  • Rule: Defines a WLDF Watch or Log Condition for which we want to associate a set of Diagnostic Dumps. When triggered the specified dumps will be collected and added to the Incident
  • Rule Action: Defines the specific Diagnostic Dumps to collect for a particular rule
  • ADR: Automatic Diagnostics Repository; Defined for every server in a domain. This is where Incidents are stored

Now let's walk through a simple flow:
  1. Oracle Web Services error message OWS-04086 (SOAP Fault) is generated on managed server 1
  2. DFW Log Condition for OWS-04086 evaluates to TRUE
  3. DFW creates a new Incident in the ADR for managed server 1
  4. DFW executes the specified Diagnostic Dumps and adds the output to the Incident
  5. In this case we'll grab the diagnostic log and thread dump. We might also want to collect the WSDL binding information and SOA audit trail

When would you use it?
When you want to automatically collect Diagnostic Dumps at a particular time using a trigger or when you want to manually collect the information. In either case it can be readily uploaded to Oracle Support through the Service Request.

How is it related to the other tools?
DFW generates Incidents which are collections of Diagnostic Dumps. One of the system level Diagonstic Dumps collects the current server diagnostic log which is generated by ODL and can contain information from Selective Tracing sessions. Incidents are included in RDA collections by default and ADRCI is a tool that is used to package an Incident for upload to Oracle Support. In addition, both ODL and DMS can be used to trigger Incident creation through DFW.

The conditions and rules for generating Incidents can become quite complicated and the below resources go into more detail. A simpler approach to leveraging at least the Diagnostic Dumps is through WLST (WebLogic Scripting Tool) where there are commands to do the following:
  • Create an Incident
  • Execute a single Diagnostic Dump
  • Describe a Diagnostic Dump
  • List the available Diagnostic Dumps
The WLST option offers greater control in what is generated and when. It can be a great help when collecting information for Support. There are overlaps with RDA, however, DFW is geared towards collecting specific runtime information when an issue occurs while existing Incidents are collected by RDA.

There are 3 WLDF Watches configured by default in a SOA Suite 11g domain: Stuck Threads, Unchecked Exception and Deadlock. These Watches are enabled by default and will generate Incidents in ADR. They are configured to reset automatically after 30 seconds so they have the potential to create multiple Incidents if these conditions are consistent. The Incidents generated by these Watches will only contain System level Diagnostic Dumps. These same System level Diagnostic Dumps will be included in any application scoped Incident as well.

Starting in 11.1.1.6, SOA Suite is including its own set of application scoped Diagnostic Dumps that can be executed from WLST or through a WLDF Watch or Log Condition. These Diagnostic Dumps can be added to an Incident such as in the earlier example using the error code OWS-04086.
  • soa.config: MDS configuration files and deployed-composites.xml
  • soa.composite: All artifacts related to the deployed composite
  • soa.wsdl: Summary of endpoints configured for the composite
  • soa.edn: EDN configuration summary if applicable
  • soa.db: Summary DB information for the SOA repository
  • soa.env: Coherence cluster configuration summary
  • soa.composite.trail: Partial audit trail information for the running composite
The current release of RDA has the option to collect the soa.wsdl and soa.composite Diagnostic Dumps. More Diagnostic Dumps for SOA Suite products are planned for future releases along with enhancements to DFW itself.

DFW Resources: top


Selective Tracing

Selective Tracing is a facility available starting in version 11.1.1.4 that allows you to increase the logging level for specific loggers and for a specific context. What this means is that you have greater capability to collect needed diagnostic log information in a production environment with reduced overhead. For example, a Selective Tracing session can be executed that only increases the log level for one composite, only one logger, limited to one server in the cluster and for a preset period of time. In an environment where dozens of composites are deployed this can dramatically reduce the volume and overhead of the logging without sacrificing relevance.

Selective Tracing can be administered either from Enterprise Manager or through WLST. WLST provides a bit more flexibility in terms of exactly where the tracing is run.

When would you use it?
When there is an issue in production or another environment that lends itself to filtering by an available context criteria and increasing the log level globally results in too much overhead or irrelevant information. The information is written to the server diagnostic log and is exportable from Enterprise Manager

How is it related to the other tools?
Selective Tracing output is written to the server diagnostic log. This log can be collected by a system level Diagnostic Dump using DFW or through a default RDA collection. Selective Tracing also heavily leverages ODL fields to determine what to trace and to tag information that is part of a particular tracing session.

Available Context Criteria:
  • Application Name
  • Client Address
  • Client Host
  • Composite Name
  • User Name
  • Web Service Name
  • Web Service Port

Selective Tracing Resources: top


DMS (Dynamic Monitoring Service)

DMS exposes runtime information for monitoring. This information can be monitored in two ways:
  1. Through the DMS servlet
  2. As exposed MBeans
The servlet is deployed by default and can be accessed through http://<host>:<port>/dms/Spy (use administrative credentials to access). The landing page of the servlet shows identical columns of what are known as Noun Types. If you select a Noun Type you will see a table in the right frame that shows the attributes (Sensors) for the Noun Type and the available instances. SOA Suite has several exposed Noun Types that are available for viewing through the Spy servlet. Screenshots of the Spy servlet are available in the Knowledge Base article How to Monitor Runtime SOA Performance With the Dynamic Monitoring Service (DMS).

Every Noun instance in the runtime is exposed as an MBean instance. As such they are generally available through an MBean browser and available for monitoring through WLDF. You can configure a WLDF Watch to monitor a particular attribute and fire a notification when the threshold is exceeded. A WLDF Watch can use the out of the box DFW notification type to notify DFW to create an Incident.

When would you use it?
When you want to monitor a metric or set of metrics either manually or through an automated system. When you want to trigger a WLDF Watch based on a metric exposed through DMS.

How is it related to the other tools?
DMS metrics can be monitored with WLDF Watches which can in turn notify DFW to create an Incident.

DMS Resources: top


ODL (Oracle Diagnostic Logging)

ODL is the primary facility for most Fusion Middleware applications to log what they are doing. Whenever you change a logging level through Enterprise Manager it is ultimately exposed through ODL and written to the server diagnostic log. A notable exception to this is WebLogic Server which uses its own log format / file.

ODL logs entries in a consistent, structured way using predefined fields and name/value pairs. Here's an example of a SOA Suite entry:

[2012-04-25T12:49:28.083-06:00] [AdminServer] [ERROR] [] [oracle.soa.bpel.engine] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: ] [ecid: 0963fdde7e77631c:-31a6431d:136eaa46cda:-8000-00000000000000b4,0] [errid: 41] [WEBSERVICE_PORT.name: BPELProcess2_pt] [APP: soa-infra] [composite_name: TestProject2] [J2EE_MODULE.name: fabric] [WEBSERVICE.name: bpelprocess1_client_ep] [J2EE_APP.name: soa-infra] Error occured while handling a post operation[[

When would you use it?
You'll use ODL almost every time you want to identify and diagnose a problem in the environment. The entries are written to the server diagnostic log.

How is it related to the other tools?
The server diagnostic logs are collected by DFW and RDA. Selective Tracing writes its information to the diagnostic log as well. Additionally, DFW log conditions are triggered by ODL log events.

ODL Resources: top


ADR (Automatic Diagnostics Repository)

ADR is not a tool in and of itself but is where DFW stores the Incidents it creates. Every server in the domain has an ADR location which can be found under <SERVER_HOME>/adr. This is referred to the as the ADR 'Base' location. ADR also has what are known as 'Home' locations. Example:
  • You have a domain called 'myDomain' and an associated managed server called 'myServer'. Your admin server is called 'AdminServer'.
  • Your domain home directory is called 'myDomain' and it contains a 'servers' directory.
  • The 'servers' directory contains a directory for the managed server called 'myServer' and here is where you'll find the 'adr' directory which is the ADR 'Base' location for myServer.
  • To get to the ADR 'Home' locations we drill through a few levels: diag/ofm/myDomain/
  • In an 11.1.1.6 SOA Suite domain you will see 2 directories here, 'myServer' and 'soa-infra'. These are the ADR 'Home' locations.
  • 'myServer' is the 'system' ADR home and contains system level Incidents.
  • 'soa-infra' is the name that SOA Suite used to register with DFW and this ADR home contains SOA Suite related Incidents
  • Each ADR home location contains a series of directories, one of which is called 'incident'. This is where your Incidents are stored.

When would you use it?
It's a good idea to check on these locations from time to time to see whether a lot of Incidents are being generated. They can be cleaned out by deleting the Incident directories or through the ADRCI tool. If you know that an Incident is of particular interest for an issue you're working with Oracle you can simply zip it up and provide it.

How does it relate to the other tools?
ADR is obviously very important for DFW since it's where the Incidents are stored. Incidents contain Diagnostic Dumps that may relate to diagnostic logs (ODL) and DMS metrics. The most recent 10 Incident directories are collected by RDA by default and ADRCI relies on the ADR locations to help manage the contents.
top


ADRCI (Automatic Diagnostics Repository Command Interpreter)

ADRCI is a command line tool for packaging and managing Incidents.

When would you use it?
When purging Incidents from an ADR Home location or when you want to package an Incident along with an offline RDA collection for upload to Oracle Support.

How does it relate to the other tools?
ADRCI contains a tool called the Incident Packaging System or IPS. This is used to package an Incident for upload to Oracle Support through a Service Request. Starting in 11.1.1.6 IPS will attempt to collect an offline RDA collection and include it with the Incident package. This will only work if Perl is available on the path, otherwise it will give a warning and package only the Incident files.

ADRCI Resources: top


WLDF (WebLogic Diagnostic Framework)

WLDF is functionality available in WebLogic Server since version 9. Starting with FMw 11g a link has been added between WLDF and the pre-existing DFW, the WLDF Watch Notification. Let's take a closer look at the flow:
  1. There is a need to monitor the performance of your SOA Suite message processing
  2. A WLDF Watch is created in the WLS console that will trigger if the average message processing time exceeds 2 seconds. This metric is monitored through a DMS MBean instance.
  3. The out of the box DFW Notification (the Notification is called FMWDFW-notification) is added to the Watch. Under the covers this notification is of type JMX.
  4. The Watch is triggered when the threshold is exceeded and fires the Notification.
  5. DFW has a listener that picks up the Notification and evaluates it according to its rules, etc
When it comes to automatic Incident creation, WLDF is a key component with capabilities that will grow over time.

When would you use it?
When you want to monitor the WLS server log or an MBean metric for some condition and fire a notification when the Watch is triggered.

How does it relate to the other tools?
WLDF is used to automatically trigger Incident creation through DFW using the DFW Notification.

WLDF Resources: top
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