Overview
Many SOA Suite 11g deployments include the use of
the technology adapters for various activities including integration
with FTP, database, and files to name a few. Although the
integrations with these adapters are easy and feature rich, there can
be some challenges from the operations perspective. One of these
challenges is how to correlate a logical business transaction across
SOA component instances. This correlation is typically accomplished
via the execution context ID (ECID), but we lose the ECID correlation
when the business transaction spans technologies like FTP, database,
and files.
A new feature has been introduced in the Oracle
adapter JCA
framework to allow the propagation of the ECID. This
feature is available in the forthcoming SOA Suite 11.1.1.7 (PS6). The basic concept of
propagating the ECID is to identify somewhere in the payload of the
message where the ECID can be stored. Then two Binding Properties,
relating to the location of the ECID in the message, are added to
either the Exposed Service (left-hand side of composite) or External
Reference (right-hand side of composite). This will give the JCA
framework enough information to either extract the ECID from or add
the ECID to the message. In the scenario of extracting the ECID from
the message, the ECID will be used for the new component instance.
Where to Put the ECID
When trying to determine where to store the ECID
in the message, you basically have two options:
Add
a new optional element to your message schema.
Leverage an existing element that is not used
in your schema.
The best scenario is that you are able to add the
optional element to your message since trying to find an unused
element will prove difficult in most situations. The schema will be
holding the ECID value which looks something like the following:
11d1def534ea1be0:7ae4cac3:13b4455735c:-8000-00000000000002dc
Configuring Composite Services/References
Now that you have identified where you want the
ECID to be stored in the message, the JCA
framework needs to have
this information as well. The two pieces of information that the
framework needs relates to the message schema:
The namespace for the element in the message.
The XPath to the element in the message.
To better understand this, let's look at an
example for the following database table:
When an Exposed Service is created via the
Database Adapter Wizard in the composite, the following schema is
created:
For this example, the two Binding Properties we
add to the ReadRow service in the composite are:
<!-- Properties for the binding to propagate the ECID from the database table -->
<property name="jca.ecid.nslist" type="xs:string" many="false"> xmlns:ns1="http://xmlns.oracle.com/pcbpel/adapter/db/top/ReadRow"</property>
<property name="jca.ecid.xpath" type="xs:string" many="false"> /ns1:EcidPropagationCollection/ns1:EcidPropagation/ns1:ecid</property>
Notice that the property called jca.ecid.nslist
contains the targetNamespace
defined in the schema and the property called jca.ecid.xpath
contains the XPath statement to the element. The XPath statement also
contains the appropriate namespace prefix (ns1)
which is defined in the jca.ecid.nslist
property.
When the Database Adapter service reads a row from
the database, it will retrieve the ECID value from the payload and
remove the element from the payload. When the component instance is
created, it will be associated with the retrieved ECID and the
payload contains everything except the ECID element/value. The only
time the ECID is visible is when it is stored safely in the resource
technology like the database, a file, or a queue.
Simple Database/File/JMS Example
This section contains a simplified example of how
the ECID can propagate through a database table, a file, and JMS
queue. The composite for the example looks like the following:
The flow of this example is as follows:
Invoke
database insert using the insertwithecidbpelprocess_client_ep
Service.
The
InsertWithECIDBPELProcess
adds a row to the database via the Database Adapter. The JCA
Framework adds the ECID to the message prior to inserting.
The ReadRow
Service retrieves the record and the JCA
Framework extracts the ECID
from the message. The ECID element is removed from the message.
An instance of ReadRowBPELProcess
is created and it is associated with the retried ECID.
The
ReadRowBPELProcess
now writes the record to the file system via the File Adapter. The
JCA
Framework adds the ECID to the message prior to writing the
message to file.
The
ReadFile Service retrieves the record from the file system and the
JCA
Framework extracts the ECID from the message. The ECID element
is removed from the message.
An
instance of ReadFileBPELProcess
is created and it is associated with the retried ECID.
The
ReadFileBPELProcess
now enqueues the message via the JMS Adapter. The JCA
Framework adds
the ECID to the message prior to enqueuing the message.
The DequeueMessage
Service retrieves the record and the JCA
Framework extracts the ECID
from the message. The ECID element is removed from the message.
An
instance of DequeueMessageBPELProcess
is created and it is associated with the retried ECID.
The logical flow ends.
When viewing the Flow Trace in the Enterprise
Manger, you will now see all the instances correlated via ECID:
Please check back here when SOA Suite 11.1.1.7 is
released for this example. With the example you can run it yourself and
reinforce what has been shared in this blog via a hands-on
experience. One final note: the contents of this blog may be
included in the official SOA Suite 11.1.1.7 documentation, but you will still need
to come here to get the example.
