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.
