This chapter describes the installation, starting and stopping, error handling, configuration and deployment of Oracle JCA Adapters that integrate with Oracle Fusion Middleware through the JCA Binding Component.
Oracle JCA Adapters are based on J2EE Connector Architecture (J2CA) 1.5 standards and deployed in the Oracle Containers for Java EE. The life cycle of Oracle JCA Adapters depend on Oracle Fusion Middleware. These adapters integrate with Oracle Fusion Middleware through the JCA Binding Component.
This chapter includes the following sections:
Configuring Message Header Properties for Oracle JCA Adapters
Creating an Application Server Connection for Oracle JCA Adapters
Manually Deploying an Adapter RAR File that Does Not Have a Jar File Associated With It
Handling the Deployment Plan When Working on a Remote Oracle SOA Server
Singleton (Active/Passive) Inbound Endpoint Lifecycle Support Within Adapters
Recommended Setting for Data Sources Used by Oracle JCA Adapters
Refer to guides in Related Documents for additional information and configurations.
This topic discusses the installation procedure for Oracle JCA Adapters.
Oracle Technology Adapters and Oracle Adapter for Oracle Applications are available as part of the Oracle Fusion Middleware install. These adapters support both Oracle Containers for Java EE and middle tier deployments.
With SOA Foundation profiles, Adapters are logically grouped into two groups. Tier1 and Tier2.
Tier 1 adapters include:
File
FTP
Database
JMS
AQ
MQ Series
UMS
Tier 2 adapters include:
Socket
LDAP
Coherence
MSMQ
JDE
SAP
AS400
Tier 1 adapters are enabled by default when you install this release. The rest of the adapters are in an installed state, however, they are not targeted to any managed servers. You must manually target them in order to use them.
Legacy adapters and packaged-application adapters are available as part of the Oracle Fusion Middleware Adapters and Connectors CD. These adapters support middle tier deployment only.
Note:
Before installing any adapter, consult the documentation related to “System Requirements and Specifications” and “Planning an Installation of Oracle Fusion Middleware” in Related Documents.
Oracle JCA Adapters are deployed as JCA 1.5 resource adapters. Therefore, to start or stop an adapter, every resource adapter must implement the start
(BootstrapContext)
and stop
methods as part of the SPI interface. Oracle JCA Adapters are started when an SOA composite using them starts a JCA outbound interaction. Adapters can also be started when an SOA composite is itself loaded for inbound interactions or when adapters publish events to the JCA binding component.
Once you have started an adapter, you can stop the adapter by shutting down the Oracle Containers for Java EE or by stopping the J2EE application within Oracle Fusion Middleware. In this release, the JCA Binding Component acts as a part of the JCA 1.5 container.
Note that you might see messages such as the following in server startup log files on a server before any composite is deployed. They are harmless warnings, and represent correct Adapter functioning.
<Warning> <J2EE> <slc01aec> <soa_server1> <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <<WLS Kernel>> <> <57ab8b08-803c-4edb-9da9-82791e12c429-00000004> <1372403795938> <BEA-160140> <Unresolved optional package references (in META-INF/MANIFEST.MF): [Extension-Name: oracle.adapter.ext, referenced from: /scratch/vaspatel/fmwhome12/soa/soa/connectors /FileAdapter.rar]. Ensure that the referenced optional package has been deployed as a library.> <Warning> <J2EE> <slc01aec> <soa_server1> <[ACTIVE] ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <<WLS Kernel>> <> <57ab8b08-803c-4edb-9da9-82791e12c429-00000004> <1372403796778> <BEA-160140> <Unresolved optional package references (in META-INF/MANIFEST.MF): [Extension-Name: oracle.adapter.ext, referenced from: /scratch/vaspatel/fmwhome12/soa/soa/ connectors/FtpAdapter.rar]. Ensure that the referenced optional package has been deployed as a library.>
You can define an adapter interface in the Adapter Configuration Wizard Adapter Interface page, as shown in Figure 2-1, by using either of the following methods:
Using a WSDL that is generated using the operation name and schema that you specify in the Adapter Configuration Wizard in the pages that appear after the Adapter Configuration Wizard Adapter Interface page.
Importing an existing WSDL.
Figure 2-1 The Adapter Configuration Wizard Adapter Interface Page
This section describes how to define an adapter interface by importing an existing WSDL. You can use this feature to create an adapter service or reference by using existing WSDLs. The option to choose an existing WSDL is supported for the following adapters only:
Oracle File Adapter
Oracle FTP Adapter
Oracle Socket Adapter
Oracle AQ Adapter
Oracle JMS Adapter
Oracle MQ Series Adapter
Oracle JCA Adapter for MSMQ
Oracle JCA Adapter for UMS
Oracle JCA Adapter for Oracle JD Edwards World
Oracle JCA Adapter for LDAP
Oracle JCA Adapter for Coherence
If you select the option of defining the adapter interface by importing an existing WSDL, then some functionalities on subsequent wizard pages are disabled. For example, because the WSDL defines the operation name and the message schema, the subsequent operation name and schema element fields are automatically filled in and you cannot modify it, as shown in Figure 2-2. However, if you do not choose to use an existing WSDL, then the adapter wizards behaves exactly as before.
Figure 2-2 Operation Page for Oracle AQ Adapter with Fields Automatically Populated
The Adapter Configuration Wizard for Oracle MQ Series Adapter, Oracle JMS Adapter, and the Oracle AQ Adapter appears different from the other adapters. These adapters have the additional option to select a callback including the port type and operation.
Subsequent options in the Adapter Configuration Wizard are enabled or disabled depending on the port types and operations you select.
For example, while using the Adapter Configuration Wizard for defining the Oracle MQ Series Adapter, if a callback is selected, only the Send Message to MQ and Get Reply/Reports and the Get Message from MQ and Send Reply/Reports Asynchronous options are enabled.
Note that if a callback is not selected, only the Put Message into MQ and Get Message from MQ options are enabled.
If a WSDL operation that has a synchronous reply is selected, only the Get Message from MQ and Send Reply/Reports Synchronous option are enabled. When you use an existing WSDL, the options to use CICS or IMS schemas are disabled.
Note:
The most common approach to importing an existing WSDL is to first create an Oracle BPEL process or a Mediator, and then define their WSDL files from schemas (or NXSD). After this is done, adapter services are created, and the WSDL file generated for the BPEL process or the Mediator component is imported as the existing WSDL file.
However, you must keep in mind that this feature works only for those messages which use schema element. Simple and complex types are not supported.
Oracle JCA Adapters expose the underlying back-end operation-specific properties as message header elements and enable the manipulation of these elements within a business process.
As the properties are exposed, you can add, delete, or revert Oracle JCA Adapters properties from the Fusion Middleware Control Console. However, depending on the type of property, you must redeploy your composite application to apply the property change.
Note:
You can modify jca properties using the SOA composite editor's property inspector. However, there is no validation of the properties you have changed if perform changes in this way.
Table 2-1 lists the types of message header properties you can configure and whether redeployment is required.
Table 2-1 Oracle JCA Adapters Property Types
Property Type | Description | Restrictions |
---|---|---|
Activation specification and interaction specification |
Activation specification properties operate as services and interaction specification properties operate as references in a SOA composite application. |
Do not add or remove these properties. You can only change their values. These properties require the adapter endpoint to be recycled. These types of properties are also dependent upon other properties. If you attempt to add properties, you have no way of knowing which dependent properties must also be added. |
Endpoint |
These are tuning-related properties that are not exposed through the activation or interaction specification properties, such as specifying time outs, thresholds, maximum intervals, and so on. |
There are no restrictions on adding, removing, or changing endpoint properties. The adapter is notified when these properties are added, removed, or changed, but it does not require redeployment. You cannot add or remove |
For more information, see Oracle File and FTP Adapters Properties
Oracle JCA Adapters are deployed as JCA 1.5 resource adapters in an Oracle Containers for Java EE container. Adapters are packaged as Resource Adapter Archive (RAR
) files using the Java Archive (JAR) format.
The physical deployment of adapters involves using the RAR
file to register the adapters as connectors with the underlying WebLogic Server or the middle tier platform.
Note:
It is important to restart servers and to update deployment after making changes to adapters; otherwise, changes you make do not go into effect. After saving configuration change into a configuration plan file, you must update the deployment to reflect the changes.
The update deployment action synchronizes the new plan file to the staging directory of each server instance. At that point, the new deployment plan is activated in the resource.
The RAR
file contains the ra.xml
file, which is the deployment descriptor XML file containing deployment-specific information about the resource adapter. In addition, the RAR
file contains declarative information about the contract between Oracle Containers for Java EE and the resource adapter.
In addition to the ra.xml
file in the.rar
file, adapters package the weblogic-ra.xml
template file. The weblogic-ra.xml
file is used to define resource adapter ConnectorFactory
objects (logical deployment). The weblogic-ra.xml
file is the Oracle Containers for EE-specific deployment descriptor for a resource adapter. It contains deployment configurations for deploying resource adapters to the WebLogic Server, which includes the back-end application connection information as specified in the deployment descriptor of the resource adapter, Java Naming and Directory Interface (JNDI) name to be used, connection pooling parameters, resource principal mapping mechanism, and configurations.
File | Contents |
---|---|
RAR file |
Contains deployment-specific information about resource adapter Contains declarative information about the contract between the Oracle Containers for Java EE and the resource adapters |
|
Defines resource adapter Contains deployment configurations for deploying resource adapters to the WebLogic Server Provides back-end application connection information as specified in the deployment descriptor of the resource adapter Provides the Java Naming and Directory Interface (JNDI) name to be used Provides the connection pooling parameters Provides a resource principal mapping mechanism Provides configuration information |
You must establish connectivity between the design-time environment and the server to which you want to deploy. To establish such connectivity, you must create an application server connection.
The following are the steps to create an application server connection:
You deploy an SOA composite application from JDeveloper.
JDeveloper requires the use of profiles for the SOA projects and applications to be deployed. This section describes how to create and deploy such profiles with JDeveloper.
This section specifically describes how you deploy an application profile for the SOA project and the application. To deploy the application, you must perform the following steps:
The JCA Adapter metadata captured during the JCA Adapter design time Configuration wizard screen is validated when it is deployed to the server.
For example. you have chosen the PhysicalDirectory value of "/in/valid/directory"; as the SOA server is trying to deploy the adapter with this metadata, the (File) Adapter looks at all the metadata and throw an exception if one or more pieces of metadata is faulty.
This causes the rollback of the deployment action in JDeveloper. The Adapter runtime validates that all referenced and JNDI-named JCA connection factories are available (that is, they can be looked up without error). Once the data source and connection factory are available, the deployment is validated and proceed.
If you have migrated a project from Releases in the 11xx-series of the Oracle SOA Platform, the deployment validation logic for that project is not enforced. This causes old composite applications not to break.
This section describes how to manually deploy any adapter RAR file that does not have a jar file associated with it.
If you deploy any adapter RAR file that only contains META-INF/ra.xml
and META-INF/weblogic-ra.xml
and also does not contain the jar file adapter required for creating JNDIs, then while deploying, you must change the deployment order to a higher value (say 500) so the Oracle WebLogic Server can deploy this RAR file after the jar file of this adapter is loaded.
For example, to deploy the DBAdapter_NewJndis.rar
file that contains only META-INF/ra.xml
and META-INF /weblogic-ra.xml
and does not contain the jar file adapter (DbAdapter.jar
) required while instantiating the new JNDIs, you can follow a specific procedure.
Note:
In this case, after deploying the DBAdapter_NewJndis.rar
file, you must change the deployment order to a higher value. This ensures that the Oracle WebLogic Server deploys the DBAdapter_NewJndi.rar
file correctly even if you restart the Oracle WebLogic Server.
Use the following steps to manually deploy an adapter RAR file that does not have a jar file associated with it:
If the Adminserver is running on computer A and the Oracle SOA server is running on computer B, you must copy the deployment plan file to computer B before you activate changes made on the Oracle SOA server.
If you try to activate changes without copying the deployment plan to the Oracle SOA Server computer, a NullPointerException
is thrown.
All the JCA files generated by the Adapter Configuration Wizard have a reference to the JNDI name. The reference is defined in the weblogic-ra.xml
file, which is the adapter's deployment descriptor.
The JNDI name is the key when you want to migrate from a development environment to a test environment to a production environment.
You must update the weblogic-ra.xml
file to have the same JNDI name in all three environments: development, testing, and production.
You should specify values for deployment time properties, such as retry interval and retry count, and then redeploy to testing environment or production environment.
The weblogic-ra.xml
identifies the end point as a development EIS or testing EIS or production EIS. For example, consider that when running through the Database Adapter Service Wizard, you specify eis/DB/custStore
as the JNDI name for the createCustomer
service.
After modeling the composite by using this adapter service, you should deploy it to the development, test, or production environments without making any changes. But before you deploy, ensure that you have a corresponding JNDI entry for eis/DB/custStore
in each of your various environments pointing to the right EIS instance.
To summarize:
All JCA files reference the JNDI name as defined in the weblogic-ra.xml
file
You must update the weblogic-ra.xml
file to have the same JNDI name in all your environments in which it is deployed.
Use the weblogic-ra.xml
deployment descriptor to specify values for deployment time properties, such as retry interval and retry count. This file also identifies the end point's environment.
Before deployment, ensure you have a corresponding JNDI entry for the correct environment.
This topic describes a process for making a one-way asynchronous BPEL process synchronous by adding an output message and a reply activity.
Message ordering can be achieved by making a BPEL process synchronous. When this is achieved, the resource adapter thread publishing a message to the BPEL engine is used for executing the entire BPEL instance.
For asynchronous BPEL processes, a pool of BPEL engine worker threads process received messages. Thus, it prevents a message ordering guarantee, as the duration of one BPEL instance is almost always be different from that of others.
Generally, a JCA resource adapter wizard only creates a one way (asynchronous) WSDLs, that is, WSDLs where the operation has only an input message. It is necessary to manually modify the wizard generated WSDLs, that is, changing it so that it becomes a request-response (synchronous) type WSDL with input and output messages.
<types> <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://acme.com/adapterService/"> <import namespace="http://TargetNamespace.com/adapterService/type" schemaLocation="adapterTypes.xsd" /> . . . <element name="empty"> <complexType/> </element>
<message name="ignoreMessage"> <part name="empty" element="tns:empty"/> </message>
<portType name="Receive_ptt"> <operation name="Receive"> <input message="tns:payloadMessage"/> <output message="tns:ignoreMessage"/> </operation> </porttype>
<binding name="Receive_binding" type="tns:Receive_ptt"> <pc:inbound_binding /> <operation name="Receive"> <jca:operation .../> <input/> <output/> </operation> </binding>
<variables> <variable name="ignore" messageType="ns1:ignoreMessage"/> . . . <sequence name="main"> <receive partnerLink="ReceivePL" portType="ns1:Receive_ptt" operation="Receive" variable="Receive_1_Read_InputVariable" createInstance="yes"/> . . . <!-- processing --> <invoke partnerLink="DB_Insert" portType="ns1:DB_Insert_ptt" operation="InsertCust" inputVariable="NewCust"/> <reply partnerLink="ReceivePL" portType="ns1:Receive_ptt" operation="Receive" variable="ignore"/> . . . <!-- optionally more processing --> </sequence>
If the resource adapter in the preceding example supports multi-threading inbound, configure / tune to only use one thread, because multiple threads break the message ordering guarantee due to their stochastic durations.
This section describes how adapters ensure that messages are not lost.
Transactional adapters allow the Enterprise Information System (EIS) to participate in one-phase or two-phase commits (local transactions or global/distributed transactions).
Non-transactional adapters implement their own schemes to ensure delivery, without the use of transactional semantics.
The goal of XA is to allow multiple resources (such as databases, application servers, message queues, transactional caches) to be accessed within the same transaction. XA uses a two-phase commit to ensure that all resources either commit or rollback any particular transaction consistently.
The XA specification describes what a resource manager must do to support transactional access. Resource managers that follow this specification are said to be XA-compliant.
XA transactions are part of the scenario you use when you want to work with multiple resources: for example, or two or more databases, or a database and a JMS connection, or all of these plus the adapter, all in a single transaction.
Transactional adapters enable XA transaction support, which, along with the inherent data processing, ensures that each modification has a clearly defined outcome, resulting in either success or failure, thus preventing potential corruption of data, It ensures execution independently from other changes, and, when completed, leaves underlying data in the same state until another transaction takes place.
XA is a two-phase commit protocol, more robust than a one-phase commit or emulated protocol. With a one-phase, or emulated, protocol, you can see message loss or other rollback/commit inconsistency.
An XA transaction is a transaction started by an application server's transaction manager. All XA resources must participate in any active global transaction, and only commit or rollback when provided a signal by the transaction manager. If a failure to commit occurs after the signal is received, a recovery mechanism must also exist to ensure the commit eventually happens.
A non-participating local resource can start and end a local transaction irrespective of an active global transaction. The commit can be done immediately and is not in response to a signal from the transaction manager. If the commit fails, the transaction is rolled back instead, with an exception thrown. No special recovery is required for that transaction because there is no other resource with which to synchronize its commit.
Adapters define the type of transaction support by specifying the transaction-support element in the ra.xml
deployment descriptor file.
Adapters support global transactions in the JCA 1.5 XA contracts that leverage the underlying application server transaction manager.
The types of adapters that leverage the underlying application transaction manager includes Oracle Adapter for Oracle Applications, Database, Advanced Queuing, JMS and MQSeries Adapters.
Non-transactional adapters, which do not leverage the underlying transaction manager, include Oracle File Adapter and Oracle FTP Adapter.
A global transaction can be marked rolled back by any parties that participate in the global transaction. Once a party marks the global transaction for rollback, other parties cannot revoke the rollback,
The fault type indicates if the errors are retryable. If retryable, the retries are governed by the JCA retry properties. Refer to the error handling section. If the error is deemed unretryable, the handling of such an error is governed by the fault policy, in which case the fault policy gets executed. This is the same for both inbound and outbound adapters.
Actions performed by a fault policy are in its local transaction and not in the global transaction.
Specifically, the fault policy, running in its own transaction, commits any existing JTA transaction before it starts executing a particular Reference (for example, in Oracle BPEL PM it is an Invoke activity). The pre-existing JTA transaction is not suspended and then committed.
Exercise care when using non-transactional adapters, including Oracle File Adapter and Oracle FTP Adapter, with transactional adapters, as retries can affect non-transactional data, including creating duplicate messages. The type of care you must exercise can include, for example, modelling business processes so message duplicates do not occur.
Inbound synchronous request response scenarios that have a dequeue and enqueue response to reply to a queue are not candidates for manual recovery. Consequently, they are marked as failed once retries are exhausted.
For additional information on topics related to retryability, see Handling Rejected Messages , and following sections.
Polling: All Oracle JCA Adapters and legacy adapters, support a pull, or polling, model for connecting to the back-end application for receiving events, that is, periodically querying the EIS endpoint for available messages and data.The exception to this is the Oracle Socket Adapter, which uses a different set of logistics, where the socket adapter can either connect to the EIS endpoint as the other adapters do using a client socket (polling), or, alternatively, create a server socket and then wait for incoming requests (push.) With polling, connection-related issues are recoverable and the inbound adapters keep retrying until the adapters are able to establish connection with the EIS. The adapter endpoints attempts to recover a lost connection for the duration of the active life of the composite. During this time they also update the log with diagnostics pinpointing the issue with connection
Local retry: These are typically transient connectivity errors. where retries can be tried again and data is not compromised by a retry. However, non-successive local retries can change transaction state. Examples of retryable errors include temporary permission errors or resource constraint errors, or both. If a transaction can be retried, this does not necessarily mean a rollback.
Global retry: A transaction that is rolled back to the beginning of the composite, for example, to a BPEL Receive where BPEL is part of the composite, which is at the beginning of the BPEL flow within a composite application. The transaction can be retried as indefinitely, or as many times as jca.count.retry
indicates. Prior to the retry, a rollback can occur. An example could be where there is a BPEL fault in a synchronous process, or where there is a partial update to a database with master and child records and a temporary database fault occurs, and the toplink mapping logic des a retry is acceptable. In other words, a global retry can occur if data is not tainted and it can be considered an explicit retry, where a rollback is required.
Not-retriable: A transaction that is not retried. With not-retriable conditions, there is no change to existing state. No-retry conditions derive from binding faults. Not-retriable situations typically occur where database integrity is an issue. Hence, not-retriable transactions are rolled back, when rejected; they are typically related to database constraint issues. Errors such as Data already exists
(for example, Primary Key Errors) are not retryable as are message correlation ID errors. A list of errors that are not retryable is provided later in this chapter.
Inbound transaction: A transaction initiated by an inbound adapter. For example, a transaction entering the SOA system from a JMS system.
Outbound transaction: A transaction outbound from the SOA system (and hence from an adapter). For example, a transaction that is made against a database outside the SOA system.
JTA transaction: Every step of a process is executed within the context of a JTA transaction. A JTA transaction ensures that one or more operations execute as an atomic unit of work. See the previous section on XA.
Asynchronous transaction: A composite transaction composed of sub-transactions. However, these sub-transactions are consecutive and serialized, that is, some sub-transactions may have been committed while others may be still executing or have not yet executed. Asynchronous transactions are guaranteed to be propagated once and only once. When an update at the source is committed, the transaction commits and expects that the update is propagated to the target appropriately.
Synchronous transaction: These are transactions that execute in one thread from one endpoint to another, without intermediate processes, and which are not serialized.
In the following sections, asynchronous and synchronous transactions are illustrated through a canonical combination set of adapters, JMS and DB, with BPEL technology intermediary. The example could employ other adapters, and other intermediaries, for example, the Mediator.
For an asynchronous service entry point, a transactional adapter initiates a global JTA transaction before sending an inbound message to the composite.
The example described next uses a test composite bound to the JMS adapter, which is bound to a composite bound in this example to BPEL which in turn is wired to a DB Adapter. BPEL dispatches messages to the DB adapter.
In this example, messages are read from JMS by the polling JMS Adapter and written to the BPEL process, where there the transaction commits. This is JTA1, the first XA transaction.
For any BPEL activity errors that, however, could not be retried or which exhausted their retry count, BPEL writes to its recovery table to store information. This information includes BPEL errors.
The second transaction, JTA2, begins with the DB Adapter reading from the BPEL dispatch table, obtaining the database insert argument. and writing an update message to the DB Adapter. This transaction, JTA 2, proceeds Outbound from the reference endpoint DB Adapter (that is, Outbound from SOA) to the Database itself. Retry situations from a duplicate data situation in the Database are retried either back from the DB Adapter to BPEL's table, or from the database back to the DB Adapter.
Global retries for any error handling are returned to the BPEL Receive activity instance, for example, or, more generally, to the point at which the transaction started. Such a retry could occur if there was an error such as a temporary database fault. The default retry count is by default indefinite, or specified in the jca.retry.count
property.
If any errors are caught as part of the second XA transaction, JTA2, a rollback occurs.
For a synchronous process, the global transaction initiated by the adapter spans both:
Message delivery
Composite execution
As with asynchronous transaction flow, the default retry count is indefinite, but can be specified through jca.count.retry
.
Synchronous transaction flow is similar to the asynchronous flow, with these differences:
Flow consists of request-response messages between the JMS Adapter and intermediary processing, for example, BPEL processing, and between, using the same example, BPEL and the Database Adapter, where messages requesting, for example, an insert are written. With a synchronous transaction, a retryable error is not caught by BPEL (the example intermediary) within the composite; the transaction returns all the way back to the JMS adapter for possible global retry.
The synchronous transaction is just one JTA transaction, rather than two.
The Adapter rejection table keeps a record of adapter rejections. Within the context of a synchronous transaction, local BPEL error handling is bypassed, and with a synchronous transaction, the private BPEL table does not contain relevant Adapter rejection data. The data is instead kept in the Adapter rejection table.
Local retries that exhaust the retry count are stored in the BPEL recovery table.
Using a similar example as that used in the synchronous example, and keeping in mind that an example synchronous message flow, parallel to the one used in the asynchronous example, consists of only one JTA transaction, JTA 1, throughout the transaction, processing is straightforward. The transaction starts with a polled message Inbound to the service endpoint, a JMS read message that then writes to the BPEL process.
Unlike the situation with the asynchronous transaction, with a synchronous transaction, the JTA transaction does not commit at this point.
Instead, the same JTA transaction proceeds Outbound from the reference endpoint DB Adapter to the Database itself. The message is then read from BPEL, and the DB Adapter is invoked with the insert argument from BPEL.At this point the JTA transaction commits.
Similar to asynchronous transactions, retries can be global and subject to a count indicated in the jca.retry.count
property. In this example, faults which are locally retryable are tried either from the database back to the BPEL process or from the Database back to the DB Adapter.
Inbound the adapter runs in an autonomous work thread; the adapter is in charge of connection recovery, and uses its own retry properties (for example, adapter.jms.retry.interval
).
A transactional adapter initiates a global JTA transaction before sending an inbound message to a composite.
For transactional adapters, retries can either be local retries (for example, a BPEL remote fault), global, or no retry (similar to a binding fault). Global retries are returned to the location where the transaction started. The default retry count is again, by default, indefinite, but are retriable only as the jca.retry.count
specifies.
When control returns to the adapter, the adapter commits the JTA transaction, and executes the following set of actions as an atomic unit of work.The adapter:
Commits the removal of the message from the inbound adapter endpoint (for example, table and queue).
Commits the execution of the composite instance.
If anything fails during this set of commit actions, that is, in removing the message and executing the composite instance, both actions are rolled back.
All outbound transaction composite activities, including Oracle JCA adapter invocations, are part of a global transaction, and if an error occurs the default behavior is that all activities are either committed or rolled back.
For example, a BPEL process can insert data into several tables (on different databases) through different Invoke activities (invoking the Database adapter).
When the BPEL instance is about to finish, the JTA transaction is committed.
Only at that point are the database insert operations be committed.
However, if errors occur during the BPEL instance execution, all activities (and thus database operations) are rolled back to the last BPEL dehydration point (the last time the BPEL instance was stored to a database.)
Whether an outbound transaction is retryable depends on the nature and scope of a specific interaction. Specifically:
Interactions that involve integrity, for example, database integrity, on the target side of the Outbound transaction, are not retried.
There can be local retries where a locally retriable condition exists, for example, a minor database issue with a single record.
If the retry situation is a more complicated database integrity scenario that could possibly be corrected, for example, an issue with updating both a Master Detail and a child record, the transaction might be rolled back to its beginning, back to a BPEL Receive (if BPEL were part of the scenario), and the transaction started again. The retry is again subject to jca.retry
but also could be subject to any BPEL fault handling retry parameters.
Connectivity issues outbound from an adapter are typically always retryable. For an outbound transaction, the adapter throws a retryable exception when it cannot get a connection, and then lets the appropriate JCA binding conduct retries (through jca.retry.count).
An example for a connectivity retryable error related to an outbound interaction is where a database listener might not have started and, accordingly, that state might be issuing connection errors.
Oracle WebLogic Server migration is used on WebLogic platform so that if a managed server fails, the server automatically restarts on the same or another physical system and inbound adapters specific to a composite on the failed server resume functioning.
Meanwhile, inbound adapters in other cluster members continue working servicing messages.
For more information, see:
Singleton (Active/Passive) Inbound Endpoint Lifecycle Support Within Adapters
File and FTP adapters: High Availability
Database adapter: High Availability
MQ adapter: High Availability
The JCA Binding Component supports active fail over of inbound Adapter Services.
To enable this fail over feature for a given inbound adapter endpoint, you must add the singleton
JCA service binding property in the composite.xml
within the <binding.jca>
element and set it to a value of true
as the code sample below shows.
To disable this feature, set the singleton
property to a value of false
(or remove the property from the <binding.jca>
element).
Example - singleton Property in composite.xml
<service name="JmsTopicSubscr" ui:wsdlLocation="JmsTopicSubscr.wsdl"> <interface.wsdl interface= "http://xmlns.oracle.com/ ...#wsdl.interface(Subscr_ptt)"/> <binding.jca config="JmsTopicSubscr_file.jca"> <property name="singleton">true</property> </binding.jca> </service>
In an Oracle WebLogic cluster, multiple activations of the same (for example, JMS) adapter (inbound) endpoint (for a specific composite service) are detected implicitly and automatically by all instances of the adapter framework active in that cluster.
However, only one activation is allowed to start the reading or publishing of messages.
The JCA Binding Component instances choose one among the activations, randomly the activation that assumes the Primary Activation responsibility.
The other activations (also called instances) in the Oracle WebLogic cluster initiate to a hot stand-by state, without invoking EndpointActivation
on the JCA resource adapter. These activations can be reassigned primary activation responsibility.
If a primary activation at some point becomes unresponsive, is deactivated manually, or crashes or exits, any of the remaining JCA Binding Component members of the Oracle WebLogic cluster immediately detect the deactivation, and reassign the primary activation responsibility to an activation agent that is in stand-by state.
For more information, see Composite Availability and Inbound Adapters.
You can use Native Correlation to correlate an inbound asynchronous message with a previous outbound message, by defining a callback interface (for a Reference) or by a mid-process BPEL Receive:
For example, the following composite defines such a correlation:
<reference name='Outbound'> <interface.wedl interface="http://xmlns.oracle.com/pcbpel/demo#wsdl.interface (JMSOutbound_PortType)" callbackinterface= "http://xmlns.oracle.com/pcbpel/demo#wsdl.interface (JMSCallback_PortType)"/> <binding.jca.operation="Consume" config="SampleOutbound_adapter.jca"/>
The jca
file must contain both JCA interaction and JCA activation.
The correlation between the request and the response is done transparently by the JCA binding runtime.
For a JMS use case, the third-party application must copy the JMS message ID from the request message to the JMS CorrelationID of the response message.
For the Oracle AQ Adapter and Oracle JMS Adapter use cases, if an external application copies the MessageId
from the request (Invoke) message to the CorrelationId
of the response (Receive) message, the adapter framework ensures that the BPEL correlation occurs.
However, when the CorrelationId
of the Receive message does not match any earlier Invoke message, the message is mapped to a BPEL conversation that does not actually exist.
In this case, although the message is persisted in the database, the SEVERE
log message can occur, as the code sample below shows:
Example - Log Error When CorrelationId of the Receive Does not Match any Earlier Invoke
SEVERE: JCABinding=> aqadapter aqadapterAdapter Service aqadapter was unable to perform delivery of inbound message to the composite ... due to: Cannot simply post callback message to the composite as there is no service element associated with the callback. Recommendation: add/set the JCA reference/binding property 'rejectUncorrelatedMessages' to true ... SEVERE: JCABinding=> aqadapter Unable to create/save Composite Instance Fault due to: null
You can explicitly alter the adapter framework behavior so that it rejects nonmatching native correlation IDs by adding the rejectUncorrelatedMessages
service binding property to the composite.xml
file as shown in code sample below.
Example - Setting the rejectUncorrelatedMessages Property
<reference name="ReqReply" ui:wsdlLocation= "ReqReply.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel /adapter/mq/MQAsyncSol_ReplyQ_ NonRelatedMsg/SOA_AsyncSol_ReplyQ_NonRelatedMsg/ ReqReply/#wsdl. interface(Enqueue_ptt)" callbackInterface="http://xmlns.oracle.com/ pcbpel/adapter/mq/ MQAsyncSol_ReplyQ_NonRelatedMsg/ SOA_AsyncSol_ReplyQ_NonRelatedMsg/ReqReply/ #wsdl.interface(Dequeue_ptt)"/> <binding.jca config="ReqReply_mq.jca"> <property name="rejectUncorrelatedMessages"> true</property> </binding.jca> </reference>
When rejectUncorrelatedMessages
is set to true
, uncorrelatable Receive messages are rejected by the adapter framework; that is, the messages are pushed back to the publishing JCA resource adapter.
By default, this property is set to false
.
For more information, see:
System resources are finite and have a threshold limit for processing. The Oracle SOA Suite, dependent on system resources, also has certain size limitations, largely due to the underlying resources beyond which the system cannot process incoming requests.
For example, Oracle JCA Adapters can process large payloads but the Oracle BPEL PM consumes huge memory when processing large payloads, which can cause OutOfMemory
conditions and affect the whole system.
You must set the payload threshold for Oracle JCA Adapters to avoid errors such as OutOfMemory
. Setting the payload threshold helps ensure that Oracle JCA Adapters process payloads that are less than the threshold limit and reject others that are not less than the threshold limit. This section provides information relative to your consideration of the relative size of payloads.
If the native size of the payload is available, then the pertinent adapters use the native size of the payload to limit the payload size below the threshold limit.
For example, with Oracle File Adapter, the native size of file polled) is available to the adapter, and if it is greater than the payload size threshold then the file is rejected.
If the native size of payload is not available, for example, as is the case for the Oracle Socket Adapter, the adapter must calculate the native size of the payload internally.
Native size can be determined internally if you use the native translation library to translate non-XML or parse serialized XMLs.
The Oracle Database Adapter does not rely on the translation framework but has a special built-in handling mechanism to calculate the size of native messages.
Caution:
In case of debatching with error recovery, payload size threshold must be used carefully. Payload size violations might lead to unwarranted rejections while skipping the stream in case of erroneous records.
You can set the payload threshold by using the knob exposed by Oracle JCA Adapters. The knob can be set in the composite.xml
file as a binding property for the adapter service, as shown in the following sample, where the 1000 value is in bytes.
<binding.jca config="getMsg_mq.jca"> <property name="payloadSizeThreshold" type="xs:string" many="false"override="may">1000</property> </binding.jca>
Where the native size of the payload is not available and if the specific adapter does not use the native translation library, you cannot enforce the payload size threshold limit. For example, in case of xml-debatching, where the Oracle File and FTP Adapters pass a chunk of file content and the actual native size is not known, payload size threshold limit cannot be used. Also, where there are serialized XML payloads and where XDK parser that lacks the feature to calculate native size is used for parsing instead of the native translation library, you cannot use payload size threshold limit.
XSD and Opaque translator scenarios can only be handled in adapters where the payload size is deterministic. For more information on the scenarios that are supported for specific Oracle JCA Adapters, refer to Table 2-2.
Table 2-2 Translation Scenarios Supported for Oracle JCA Adapters
Scenario | Oracle File and FTP Adapters | Oracle JMS Adapter | Oracle MQ Series Adapter | Oracle AQ Adapter | Oracle Database Adapter |
---|---|---|---|---|---|
NXSD |
Yes |
Yes |
Yes |
Yes |
Not applicable |
XSD |
Yes |
Yes |
Yes |
No |
Yes |
Opaque |
Yes |
Yes |
Yes |
No |
Not applicable |
DTD |
No |
No |
No |
No |
Not applicable |
Also, you can set the global property for capping payload size to change the default value of payloadSizeThreshold
(from indefinite) to a finite number. In this case, where you set the default value of payloadSizeThreshold
to a finite number, even if you do not explicitly configure a value for the payloadSizeThreshold
property for a particular inbound adapter endpoint, the global default takes effect. If you specify the global default along with the value in composite.xml
, then the value specified in composite.xml
overrides the global value.
You can modify this global property using the MBeans browser (Adapter Mbean) of the Fusion Middleware Control. This change takes immediate effect for all current and future endpoints
Oracle JCA Adapters support large payload processing for both inbound and outbound processing. However, only the following adapters support the streaming feature explicitly:
Oracle File Adapter
For more information, see Scalable DOM.
Oracle AQ Adapter
For more information, see Stream Payload Support.
Oracle JMS Adapter
For more information, see Streaming Large Payload.
Oracle Database Adapter
For more information, see Streaming Large Payload.
The other adapters do not have explicit support for both.
The batching and debatching functionality is supported for these adapters:
Oracle JCA Adapter for Files
Oracle JCA Adapter for FTP
Oracle JCA Adapter for Databases
Oracle JCA Adapter for File and Oracle JCA Adapter for FTP consist of a Reader
to debatch a single large file into several batches. You must specify the batch size during the design-time configuration. In addition, the adapter includes a Writer to batch a set of messages into a single file. For more information, see File Debatching.
Oracle JCA Adapter for Databases consists of a Publish component to poll a set of tables to detect events. This component can raise events to the BPEL process one record at a time or multiple records at a time. For more information, see Polling Strategies.
The logical deployment of adapters implies the creation of ConnectionFactory
objects in the weblogic-ra.xml
deployment descriptor file. The weblogic-ra.xml
file contains runtime connection parameters for an adapter.
To add the connection information and assign to a JNDI name, you must edit the corresponding weblogic-ra.xml
file of the resource adapter by either using Oracle WebLogic Server Administration Console or WLST scripts.
The following steps describe how to set up a Database connection factory in the Oracle WebLogic Server Administration Console.
This section includes the following topics:
To create a connection pool:
Navigate to http://
servername
:
portnumber
/console
.
Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.
The Home page of the Oracle WebLogic Server Administration Console is displayed.
Under Domain Structure, click Deployments.
The Summary of Deployments page is displayed.
Click the Database adapter name from the Deployments list.
The Settings for DbAdapter page is displayed.
Click Configuration tab, and then click Outbound Connection Pools tab.
The Outbound Connection Pool Configuration Table is displayed.
Click New.
Select javax.resource.cci.ConnectionFactory, and click Next.
The Create a New Outbound Connection page is displayed.
In the JNDI Name: field, enter eis/DB/soademoDatabase
.
Note:
The JNDI value that you enter in this step is different from the same value that you entered in Step 5 in Creating a Data Source. The JNDI name specified in this step must match the value you enter in your database connection you create when building your application later.
Click Finish.
The Settings for DbAdapter page appears, showing a table of Outbound Connection Pool groups and instances for this resource adapter is displayed.
The configuration changes that you made must be stored in a new deployment plan. You do this in the next step.
In the Path field, select or enter the path of a deployment plan file. The path must end with ".xml".
Note:
If the Adminserver is running on computer A and the Oracle SOA server is running on computer B, then you must copy the deployment plan file to computer B before you activate changes made on the Oracle SOA server.
If you try to activate changes without copying the deployment plan to the Oracle SOA Server computer, a NullPointerException
is thrown.
In the Properties field, enter the value for xADataSourceName
as jdbc/soademoDatabase
Click Save.
Note:
The properties do not get saved when you click Save as mentioned in this step. Instead, you must press Enter in the keyboard to save the changes you made.
Under Domain Structure, click Deployments.
The Summary of Deployments is displayed.
Perform the following steps:
Select the DbAdapter check box, and then select Update.
The Update Application Assistant page is displayed.
Select the Update this application in place with new deployment plan changes option.
Click Next, and then click Finish.
The Summary of Deployments page stating that the deployment you selected is updated is displayed.
Under Domain Structure, click Deployments, DbAdapter, Configuration, and then Outbound Connection Pools.
Notice that the value of the xADataSource
property that you entered in Step 11 is displayed in the Connection Factory Interface tab.
Note:
If you are adding a new value for the outbound connection pool, then you do not have to restart the Managed server or the Admin server. However, if you edit any property of an existing connection pool, you must restart the server.
You can add a new adapter connection factory or update an existing adapter connection factory.
If you add or update an adapter connection factory, you must perform any of the following procedures to ensure that the composite uses the new adapter connection factory properties.
Follow the steps:
Modify the JCA file of the deployed composite to point to the new JNDI. The composite takes the properties from the newly-created JNDI.
Create a new JNDI for a JCA adapter connection factory.
Create a Config plan for the composite.
To create a Config Plan, right-click composite.xml in the JDeveloper design area. From the menu that appears, click Generate Config Plan. The Config Plan is generated.
Specify a logical name for the JNDI in the JCA file.
For example, in the following sample, jndi-name
is the logical JNDI name:
<connection-factory location="jndi-name" adapterRef=""/>
Replace the logical name with the absolute value of the new JNDI in the Config plan.
For example, in the following sample, the logical JNDI name, jndi-name
is replaced by the absolute value, eis/MQ/MQSeriesAdapter7
:
<wsdlAndSchema name="DQ1.wsdl"> <searchReplace> <search>jndi-name</search> <replace>eis/MQ/MQSeriesAdapter7</replace> </searchReplace> </wsdlAndSchema>
When a composite uses new adapter connection factory properties, you must perform the following steps to avoid an Oracle Containers for Java EE restart:
Log into the Home page of the Oracle WebLogic Server Administration Console.
Select Deployments in the Domain Structure pane.
The Oracle WebLogic Server Administration Console Summary of Deployments page is displayed.
Select the adapter for which you added a new connection factory.
Click Update.
The Update Application Assistant page is displayed.
Select the Update this application in place with new deployment plan changes option.
Click Next, and then click Finish.
The Summary of Deployments page stating that the deployment you selected is updated is displayed. You can use this procedure to change adapter endpoints, for example, without having to perform a restart.
You can use the Web Logic Console to create connection factories for use with JMS. Refer to Creating a New Connection by Using the Oracle WebLogic Server Administration Console
This section describes the recommended setting for non-XA and XA data sources used by Oracle JCA Adapters.
The following are the recommended settings for multi-data sources:
test-frequency-seconds
should be 5
algorithm-type
should be Load-Balancing
data-source-list
should point to a list of comma-delimited child data sources. For example, (JDBC Data Source-0,JDBC Data Source-1)
If your endpoint property resides in an Oracle RAC database, use multi-data sources.
Table 2-3 lists the recommended setting for XA and non-XA data sources used by Oracle JCA Adapters.
Table 2-3 Recommended Setting For XA and Non-XA Data Sources
XA Data Sources | Non-XA Data Sources |
---|---|
The driver used is |
The driver used is |
The JDBC URL should be in the following format: jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=host-vip)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name)(INSTANCE_NAME=inst1))) |
Same as that of XA data source. |
You must set the following property <property> <name>oracle.net.CONNECT_TIMEOUT</name> <value>10000</value> </property> |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
Same as that of XA data source. |
The value of |
The value for |
The value of |
NA |
The value of |
NA |
The value of |
NA |
Note:
The settings mentioned in Table 2-3 are applicable to both types of database, single instance and an Oracle RAC database. In case of an Oracle RAC database, these settings must be used for constituent data sources for multi data sources created for endpoints. See the Oracle RAC Documentation at http://www.oracle.com/technetwork/database/options/clustering/documentation/index.html
In addition to applying the settings mentioned in Table 2-3, you must perform the steps documented in “Using Oracle Thin/XA Driver" in the Developing JTA Applications for Oracle WebLogic Server
These steps are required for data sources using XA driver. After performing the steps mentioned in the preceding link, you must run the following SQL statements to enable WLS JTA recovery to work:
grant select on sys.dba_pending_transactions to public GRANT FORCE ANY TRANSACTION TO public grant execute on sys.dbms_xa to public
The Oracle JCA Adapters provide error handling capabilities, as listed in the following sections. These rejection handlers are applicable in synchronous processes only. They do not apply to asynchronous or one-way processes.
This section includes the following topics:
The messages that error out before being posted to the service infrastructure are referred to as rejected messages. For example, the Oracle File Adapter selects a file having data in CSV format and tries to translate it to XML format (using NXSD). If there is any error in the translation, this message is rejected and are not be posted to the target composite.
Primarily, adapters and binding components are the generators of rejected messages.
Errors or faults that arise downstream in a synchronized flow are handled in the following manner by the inbound adapter:
Immediately rejected if the exception is non-retryable.
Retried indefinitely if the exception is retryable.
Retried several times equal to the value of jca.retry.count
(if configured) and then rejected when the retries are exhausted.
Adapters reject messages that create errors at the binding level; that is, they error out before entering the Service Infrastructure layer.
All rejected messages are stored in the database with the payload. The rejected messages can later be queried against.
Faults can be also categorized as binding or remote. Remote faults are typically attributed to transient failures such as database connection down and are retriable where as binding faults are attributed to non-transient failures and are marked as non-retriable. But depending on the situation, these non-transient failures can also be rectified.For example, faults such as an MQ series Adapter target queue being full or unique constraint violation in a database can be rectified.However, certain non-transient failures, such as validation failure due to translation/transformation, cannot be rectified without redeployment of the composite.Messages rejected due to both binding faults and remote faults are marked as recoverable (for manual recovery).Recovery success depends on the scenario; you should inspect the faulted instance and initiate action if the manual recovery fails.
This section includes the following topics:
For more information, see Correlation Support Within Adapters.
In the 10.x release, rejection handlers were defined in the deployment descriptor (bpel.xml
) of an Oracle BPEL process.
However, in the 11g release, you must define rejection handlers by using fault policies.
You can specify only one action handler for inbound rejection handlers.
You must create two files named fault-policies.xml
and fault-bindings.xml
, and copy them to the SOA project directory in JDeveloper, as described in the following steps:
Note:
If you do not configure rejection handlers as mentioned in Configuring Rejection Handlers, a default file-based rejection handler starts processing and the rejected messages is directed to <domain_home>/rejmsgs/<wls_server_name>/<composite_name>
.
Also, you can configure rejected messages with a Mediator Component in the same fault policy as that of Oracle BPEL Process Manager (Oracle BPEL PM).
Rejected messages are stored in the rejected_message
table.
You can check for rejected messages by using either of the following steps. You can obtain the messages and perform additional processing on them, according to your own implementation.
To check from the database, you must connect to the database as soainfra schema, and run the following SQL command:
select * from rejected_message
You can view the rejected messages in the Recent Faults and Rejected Messages section of the Dashboard tab or in the Faults and Rejected Messages tab.
For more information about using the Fusion Middleware Control Console for checking for rejected messages, see:
“Monitoring Recent Faults and Rejected Messages for an Inbound Adapter" in the Administering Oracle SOA Suite and Oracle Business Process Management Suite.
“Monitoring Faults and Rejected Messages for an Inbound Adapter" in the Administering Oracle SOA Suite and Oracle Business Process Management Suite
This section describes how to handle message errors through a sample scenario.
There are two composites, Composite 1 and Composite 2 each having an Oracle BPEL process and there is a mix of local and XA resources, as shown in Figure 2-10.
Figure 2-10 Sample Scenario: Handling Message Errors
When the message is successfully delivered to all the queues (Q1, Q2 and Q3), the transaction commits successfully.
If the message cannot be delivered to Q1 (or to any queue) but the message is delivered to queues Q2 and Q3, the transaction must roll back all the three messages because all are XA resources and there is an exception in an XA unit.
The rollback exception is thrown only for the second composite where Q1 failed, and the transactions commits Q2 and Q3 instead of rolling back the messages for all the three queues.
To have the transaction roll back all the queues even if only one fails, and for the other two have messages successfully delivered to them, you must make the change in the composite.xml
file of the called composite (Composite2) as the code sample below shows:
Example - Changes in composite.xml of Composite2
<component name="BPELProcess1"> <implementation.bpel src="BPELProcess1.bpel"/> <property name="bpel.config.transaction"> required</property> </component>
This sets the property bpel.config.transaction
to the value of required
, which causes the transaction to roll back all the queues even if only one fails.
If you set property bpel.config.transaction
to a value of required
, the Oracle BPEL engine effectively processes the synchronous request without creating a new transaction; rather, it uses the caller's transaction. Therefore, if at any point the transaction gets rolled back, nothing done in that transaction commits.
You can indicate the way inbound adapters should handle errors by specifying rejected message handlers.
You can create rejection handlers to handle message errors. Message errors include those that occur during translation, correlation ID mismatch and XML parsing after message reception.
Available Rejection Handlers for Message Errors
Before considering error handling in terms of retryability, it is important to understand the error handlers that are available.
The following are the system-defined error handlers, which you can configure through fault policies:.
A rejected message can be handled by calling a Web Service. If you choose to use a Web Service to handle these errors, you should implement a predefined WSDL interface implemented by the target service, SOAP bindings for the Web service invocation, and native payloads passed as WebService-attachments, as shown in the following example:
<Action id="ora-ws"> <invokeWS uri="WebServiceURI"/> <!-- format - <Absolute wsdl path>|service name|port name --> </Action>
The WSDL Interface for the Web Service handler must have one port type, only one input operation, and a schema for the input message. This is shown in the following example.
Example - WSDL Interface for Web Service Handler
<?xml version="1.0"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://xmlns.oracle.com/pcbpel/errorHandling" xmlns:tns="http://xmlns.oracle.com/pcbpel/errorHandling" elementFormDefault="qualified"> <element name="RejectedMessage" type="tns:RejectedMessageType"> <complexType name="RejectedMessageType"/> <sequence> <element name="MessageHeader" type="string"/> <!-- base64 encoded string --> <element name="MessagePayload" type="string"/> <!-- base64 encoded string --> <element name="RejectionReason" type="string"/> </sequence> <attribute name="RejectionId" type="string"/> </complexType> </schema>
Another option to handle errors is to create a predefined Java framework, an interface, that forwards errors. You can implement a Java interface by the target class, as shown in the following example.
<Action id="ora-custom"> <javaAction className="mypackage.myClass" defaultAction="ora-terminate"> <returnValue value="SUCCESS" ref="ora-file"/> <returnValue value="FAILED" ref="ora-ws"/> </javaAction> </Action>
The interface itself specifies a fault recovery class. See the following snippet for an example of the interface.
package oracle.integration.platform.faultpolicy; public interface IFaultRecoveryJavaClass { public void handleRetrySuccess ( IFaultRecoveryContext ctx); public String handleFault( IFaultRecoveryContext ctx);}
You cannot enqueue a rejected message to a JMS queue as a JMS message with the appropriate context and payload, however you can do this task with the AQ adapter as shown in the following two examples.
The first example uses a standalone database:
Example - Using a Standalone Database with the AQ Adapter to Enqueue a Rejected Message
<faultPolicies> <faultPolicy version="2.0.1" id="MQ_ServiceFaults_MED"> <Conditions> <faultName xmlns:rjm="http://schemas.oracle. com/sca/rejectedmessages" name="rjm:DQ"> <condition> <action ref="ora-enqueue"/> </condition> </faultName> </Conditions> <Actions> <Action id="ora-enqueue"> <enqueue uri="jdbc:oracle:thin: @//myhost.com:1521/orcl#scott/tiger#REJ_MSG_Q" /> </Action> </Actions> </faultPolicy> </faultPolicies>
The second example is used with an Oracle RAC database:
Example - Using an Oracle RAC Database with the AQ Adapter to Enqueue a Rejected Message
<Action id="ora-queue"> <enqueue uri="QueueURI"/> <!-- QueueURI format - jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=on)(ADDRESS_ LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=<host1>)(PORT=<port1>))( ADDRESS=(PROTOCOL=TCP)(HOST=<host2>)(PORT=<port2>)))(CONNECT_DATA=(SERVICE_ NAME=<service_name>)))#<un>/<pw>#queue --> </Action>
You create an error handler for messages by storing a rejected message in a file. You can store the payload with the proper context, as shown in the following example. The Payload file is created at the configured location.
<Action id="ora-file"> <fileAction> <location>FOLDER_LOCATION</location> <fileName>FILE_NAME</fileName> <!-- FILE_NAME will support %ID%(rejected message instance id) or %TIMESTAMP% wildcards --> </fileAction> </Action>
Error payload persistence in the Database is available by default. Only the File Adapter handler creates a metadata file that contains all the properties of the rejected message.
For example, for the Oracle File Adapter, this metadata file could include information such as the inbound direction and file name. The location of metadata file is same as the payload file and the naming pattern is <FILE_NAME>_metadata
.
For resubmitting rejected messages, payload persistence is imperative. Payloads are stored in the Database and a facility to view the payloads is available through the Fusion Middleware Control Console. The message/payload is provided in full to each configured error handler, in addition to providing the payload to the default error handler.
Inbound retryable errors are typically transient connectivity errors. Only retryable errors for a synchronous process thrown by the outbound binding is subject to retry by the inbound adapter (an indefinite number of times by default, which is limited by setting the jca.retry.count
property). Any JTA transaction is rolled back before a retry.
Examples of retryable errors thrown by outbound adapters include connection errors but include also temporary permission errors or resource constraint errors, or both.
Errors such as Data already exists
(for example, Primary Key Errors) are not retryable. In addition, message correlation ID errors are not retryable.
When a set number of retries have been exhausted, the rejection mechanism handles the error.
You can configure inbound adapters to handle inbound retryable errors. The following properties, which you can specify in the composite.xml
file, are supported for retryable exceptions for inbound interactions:
By default, there is unlimited retry for inbound errors; however, adapter retry is either at the level of the composite (local) application or at the global level.
Once you have configured properties in the composite, at the service level, the configuration of the properties has meaning. (For example, when you configure the number of retries before rejection, the value of the interval property takes its default value.)
Properties you can specify in the composite.xml file include:
jca.retry.count
Specifies the maximum number of retries before rejection. Again, specifying this value is a pre-requisite to specifying the other property values.
jca.retry.interval
Specifies the time interval between retries (measured in seconds.)
jca.retry.backoff
Specifies the retry interval growth factor (positive integer.)
jca.retry.maxInterval
Specifies the maximum value of retry interval, that is, a cap if backoff > 1
You can modify the composite application's xml descriptor to specify properties that apply to retries. The preceding list of properties are specified in the composite.xml file in JDeveloper, as shown in the following example:
<service name="Inbound"> <interface.wsdl interface="http:// xmlns...#wsdl.interface(Inbound_PortType)"/> <binding.jca config="Inbound_db.jca"> <property name="jca.retry.count">5</property> <property name="jca.retry.interval">1</property> <property name="jca.retry.backoff">2</property> <property name="jca.retry.maxInterval">6</property> </binding.jca> </service>
For retryable exceptions, you must set the value of jca.retry.count
to the number of times the retry is to be carried out.
For example, if you set the value of jca.retry.count
to 10, the retry occurs 10 times.
However, if you have not set any value for jca.retry.count
, the retry is carried out indefinitely, which is the default for retryable errors.
Note:
Infinite retries by inbound adapters for errors results in the creation of multiple composite instances, because for every retry a separate composite instance is created.
You can change the global property for capping retries to alter the default value of jca.retry.count
from an indefinite to a finite number.
In this case, where you set the default value of jca.retry.count
to a finite number, even if you do not explicitly configure a value for the jca.retry.count
property for a particular inbound adapter endpoint, the global default takes effect.
If you specify the global default along with the value in the composite.xml, the value specified in the composite.xml
overrides the global value.
You can modify the global property using the MBeans browser (Adapter Mbean) of the Fusion Middleware Control Console. Any change you do through the MBeans browser takes immediate effect for all current and future endpoints.
Typically non-retryable errors are a result of either transformation or message parsing.
Inbound adapters handle non-retryable errors thrown from the Enterprise Information System by rejecting the inbound messages. If the error is a non-retryable error, you must use the rejection handler to handle the non-retryable error.
Examples of non-retryable errors thrown from interaction with an Enterprise Information System include the following:
Primary key violation
Queue does not exist
Master record does not exist
Unable to serialize payload
Non-retryable errors are never retried because they are never expected to resolve themselves simply by being retried. For example, messages can be sent from a file to an inbound file adapter through a Mediator. The Mediator, in turn, has sequential routing to an outbound Database Adapter that inserts data to a database table. The DB adapter might encounter a unique constraint error as it is performing the insert operation. This unique constraint error is:
Considered by the outbound Database Adapter as a non-retryable error
Propagated back to the inbound Adapter
Considered by the inbound adapter as a non-retryable error as well, using a rejection handler. The adapter uses a fault policy if one is defined.
A mediator could have errors on a transformation. This type of error is a non-retryable error. The error returns to the inbound adapter where it is handled, depending on the signature of the WSDL.
Outbound Interaction errors occur with messages that have interactions outbound from an adapter.
This section addresses the retryability and non-retryability of these Outbound Interaction errors and provides a basis for understanding the related properties you can set.
Outbound retryable errors can be retried based on the value of jca.retry.count
in the composite.xml
file.
For retryable exceptions for outbound error handling, you must set the value of jca.retry.count
to the number of times the retry is to be carried out.
For example, if you set the value of jca.retry.count
to 10, the retry occurs 10 times.
However, if you have not set any value for jca.retry.count
, the retry is carried out by the fault policy, if you have included the fault policy as part of the composite.
The following code snippet is an example of how to set values in the composite.xml
file for retryable exceptions for outbound interactions.
The retry is set to 5 minutes with an interval of 1 minute, and the other properties are appropriately configured. As stated before, the additional properties have meaning when the jca.retry.count
property is specified.
<reference name="Outbound"> <interface.wsdl interface="http:// xmlns...#wsdl.interface(Outbound_PortType)"/> <binding.jca config="Outbound_jms.jca"> <property name="jca.retry.count">5</property> <property name="jca.retry.interval">1</property> <property name="jca.retry.backoff">2</property> <property name="jca.retry.maxInterval">6</property> <property name="jca.retry.maxPeriod">30</property> </binding.jca> </reference>
You can handle non-retryable exceptions for outbound interactions by defining the maximum number of reconnection attempts that can be made in the fault-policy.xml
file, which establishes the expected behavior for non-retryable errors.
In this fault policy file, you specify the parameters for reconnection attempts, as shown in the following example. This includes:
The number of reconnection retries (retryCount
)
Intervals between reconnection retries (retryInterval
)
An exponential backoff value for the connection retries (exponentialBackoff
)
All time measurements are specified in seconds.
Example - Specifying Parameters for Reconnection Attempts
<faultName xmlns:bplex="http://schemas.oracle.com/bpel/extension" name='bplex;bindingFault"> <condition> <action ref="ora-retry"/> </faultName> </condition> <Actions> <Action id="ora-retry"> <retry> <retryCount>10</retryCount> <retryInterval>2</retryInterval> <exponentialBackoff>2</exponentialBackoff> </retry> </Action> </Actions>
You must associate a fault policy with a reference end point of the composite in fault-bindings.xml
file, as shown in the following example, with the faultPolicy
ConnectionFaults
and the reference name writeMessageToQueue
.
Example - Associating a Fault Policy with a Reference End Point of the Composite
<?xml version="1.0" encoding="UTF-8"?> <faultPolicyBindings version="2.0.1" xmlns="http://schemas.oracle.com/bpel/faultpolicy" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <reference faultPolicy="ConnectionFaults"> <name>writeMessageToQueue</name> </reference> </faultPolicyBindings>
After the configured number of retries is reached without a positive result, the Service Infrastructure Invocation exception is thrown.
The propagation of the type of the Service Infrastructure Invocation exception is important to allow inbound adapters to respond to errors reported by outbound adapters.
Figure 2-13 shows the fault propagation when an adapter calls the service infrastructure synchronously, after which the Oracle BPEL Process Manager and Oracle Mediator calls a down-stream adapter.
In this figure, a Service Infrastructure Invocation exception propagates from the down-stream adapter, through Oracle BPEL Process Manager and Oracle Mediator, and to the caller adapter.
There are two cases where the fault policy mechanism does not work:
Outbound Adapters in XA Mode
Outbound Adapters in Mediator Sequential Routing
Outbound Adapters in XA Mode
The fault policy mechanism does not work for outbound adapters in XA mode.
For example, in XA mode, if you want the fault policy to retry when the outbound adapter fails, it does not retry and any outbound adapter that has been successful before this failure occurred does not rollback messages.
Outbound Adapter i n Mediator Sequential
Fault policies also do not work for the outbound adapter that is invoked in Mediator sequential routing, because the mediator fault policies are applicable to parallel routing rules only.
You can use Oracle Web Services Manager OWSM through JDeveloper and the Fusion Middleware Control to apply a PII (Personally Identifiable Information) policy to a payload in a scenario where an inbound adapter sends a message to a BPEL Process which feeds the message to an outbound Adapter.
Using OWSM in this manner, you can configure the Adapter payload to be encrypted and decrypted. An individual examining the BPEL Audit Trail does not see the data you specify to be encrypted.
You select any payload element from inbound to be encrypted; you must also select the same element to be decrypted for the corresponding endpoint.
In general, web services security includes several aspects: authentication, authorization (or Access Control), confidentiality and privacy, integrity, non repudiation.
The Adapter's use of this involves keeping information secret Personally Identifiable Information (PII).
To apply a PII policy to a payload, you provide JCA encryption and decryption on the JCA endpoints. The goal of PII encryption is to keep data safe while it is inside the system.
To do this, you supply a security credential with its own map name and key name for the data at the Endpoint. The security credential you supply for the Endpoint is uniquely identified by this map name and key name you supply.
Use the following steps to attach JCA encryption and decryption on the Service and Reference Endpoints. The sample shown is a file service.
You can run and test instances of deployed SOA composite applications from Oracle Enterprise Manager Grid Control Console. Running and testing your instances this way enables you to:
Manage a composite application
Initiate an instance of a composite
Track an instance of a composite
View detailed component instance audit trails
Fore more information about testing applications, see in Automating the Testing of SOA Composite ApplicationsAdministering Oracle SOA Suite and Oracle Business Process Management Suite guide.
Set the trace level for the following types of adapters as follows:
Oracle JCA Adapters and Oracle Adapter for Oracle Applications: set the log level to, for example, TRACE:32
in the logger oracle.soa.adapter
.
Packaged-application adapters: For outbound interactions, set the Loglevel
property for packaged-application adapters in the weblogic-ra.xml
file.
Legacy adapters: you can use Oracle Studio to set the trace level for Oracle Connect, and the mainframe server.
To set the trace level by using the Fusion Middleware Control Console:
For more information, see Viewing Adapter Logs.
You can view the logs for Oracle JCA Adapters as follows:
Oracle JCA Adapters and Oracle Adapter for Oracle Applications: These adapters implement the LogManager
interface of the JCA Binding Component, which redirects log files in the Oracle Diagnostic Logging (ODL) format. For both outbound and inbound interactions, the log files are redirected to the soa-diagnostic.log
file.
The log files for the Oracle SOA Suite that is deployed to the server-soa
managed server are located in:
MW_HOME/user_projects/domains/domain_name/servers/server-soa/logs/soa-diagnostic.log
Packaged-application adapters: These adapters do not implement the LogManager
interface because it is not part of the J2CA 1.5 standard. Therefore, for system components the log outputs are redirected to
ORACLE_INSTANCE
\diagnostics\logs\component_type\component_name
. For outbound interactions, the logs are directed to the same location. On the other hand, for inbound interactions, logs are redirected to soa-diagnostic.log
.
Legacy adapters: In addition to the J2CA resource adapter, legacy adapters consists of Oracle Connect, which consists of native adapters for communicating with the mainframe application and data stores. Oracle Connect logs can be viewed using Oracle Studio, which is the mainframe adapter design-time tool and Oracle Connect management tool. Oracle Connect generates various types of logs, such as the daemon log, workspace log, and server process log.
For more information, see Setting the Trace Level of Oracle JCA Adapters .
For information on Diagnosability Dumps, see Supported SOA Adapter Diagnosability Dumps in the SOA Administration Guide.
You can configure a Custom JCA Adapter wizard as a generic adapter wizard within the JDeveloper IDE that reads and displays its interaction/activation specs, properties and default values from a configuration file. The wizard enables you to select the specs, override the default property values, and add new properties. The Custom Adapter wizard has several purposes:
You can use the Custom Adapter Wizard on an “as-is" basis to support custom runtime adapters. Supply (or extend) the Custom Adapter configuration file, customAdapter-config.xml
to use the Custom Adapter.
You can modify or extend the Custom Adapter classes if you want to create a more specific adapter (for example, you can change the text to match your adapter
You can use the Custom Adapter wizard to see a simple example of how to develop a new adapter wizard by using the JCA Adapter framework and by hooking into the SCAEndpoint interface.
After the SOA JDeveloper extension is installed, the Custom Adapter java source files can be found in <JAVA_HOME> /jdeveloper/integration/adapters/samples/custom
The Custom Adapter does not appear by default in JDeveloper Components. The following is the recommended way to update the extension.xml
file so the Custom Adapter appears in the JDeveloper Components.
Open <jdev_home>\soa\plugins\jdeveloper\extensions\oracle.sca.ui.adapters.jar
with Archive Manager.
Find the META-INF/extension.xml
file, select it, and select Extract. You can save the file to the current file that the jar is in.
From the Linux command line, edit (using vi or emacs) the extracted extension.xml
file.
Uncomment the Custom Adapter entry and save the file.
In the Archive Manager, press the Add button (add files to archive).Select the extension.xml
file, and hit Add.
Restart JDeveloper.
The <JDEV_HOME>\jdeveloper\integration\seed\soa\configuration\ custom\Adapter-config.xml
file contains the detailed options for the Custom Adapter (connection-factory location, interaction-spec className, activation-spec className, and properties).
The properties within an activation-spec are properties that are specific to an inbound adapter. The properties within an interaction-spec are the properties specific to an outbound adapter. The property values are the default values shown by the Custom Adapter.
You can modify the contents of the customAdapter-config.xml
to match options required by your custom runtime adapter. For example, you can change all property names and their default values, add new properties, or add multiple activation or interaction specs.
The displayResourceKey
and resourceBundle
attributes are optional. If an activation-spec, interaction-spec, or property element has a displayResourceKey
, the attribute value is used as a key to retrieve displayable text from a resource bundle. If a resource bundle is not available or the key is not found in the bundle, the key itself is used as the displayable text (it is not required to have a resource bundle). The resource bundle you want to use can be specified by putting the resourceBundle
attribute on the connection-factory element.
Here is an example of a customAdapter-config.xml
that has been modified.
Example - Modified customAdapter-config.xml
<adapter-config xmlns="http://platform.integration.oracle/blocks/ adapter/fw/metadata"> <connection-factory location="eis/Custom/CustomAdapter" resourceBundle="oracle.tip.tools.ide.pm.modules. bizintegration.adapter.custom.resource. CustomStringResourceBundle"/> <endpoint-interaction > <interaction-spec className="oracle.tip.adapter. custom.outbound. CustomInteractionSpec" displayResourceKey= "CustomInteractionSpec" > <property name="PropX" value="x" displayResourceKey="SAMP_PROP_X" /> <property name="PropY" value="y" displayResourceKey="Sample Property Y"/> <property name="Append" value="false"/> <property name="NumberMessages" value="1"/> </interaction-spec> </endpoint-interaction> <endpoint-activation> <activation-spec className= "oracle.tip.adapter.custom.inbound.CustomActivationSpec" displayResourceKey="CustomActivationSpec"> <property name="UseHeaders" value="false"/> <property name="PhysicalDirectory" value="x"/> <property name="Recursive" value="true"/> <property name="DeleteFile" value="true"/> <property name="IncludeFiles" value="x"/> <property name="PollingFrequency" value="60"/> <property name="MinimumAge" value="0"/> </activation-spec> </endpoint-activation> </adapter-config>
When you drag-and-drop the Custom JCA Adapter icon to the Exposed Service or External Reference swimlane within JDeveloper, the IDE displays the Adapter Configuration Welcome Page. You can then select Next to begin the Custom Adapter Configuration Wizard workflow.
Figure 2-23 Adapter Configuration Wizard Welcome Screen
The next screen displays the service type and name, similar to the way it occurs with the Configuration Wizards of other adapters. This screen enables you to provide the name of a Service that makes sense in the Adapter you are configuring.
Figure 2-24 Adapter Configuration Wizard Service Name Screen
If the config.xml
file contains a <connection-factory>
entry (as required by the custom runtime adapter), the Wizard displays the Connection Information page displaying the default Connection Factory Location. If the config.xml
does not contain a <connection-factory>
entry (not required by the custom runtime adapter), the Wizard does not display this page.
Figure 2-25 Adapter Configuration Wizard Connection Information Screen
The next screen is the Adapter Interface Screen, which displays information in a similar manner to the configuration wizard for other Adapters. (Refer to the appropriate chapter on each Adapter for information on its configuration wizard.)This screen provides you a way to either define a new WSDL from an operation and schema you provide later, or import an existing WSDL, using the WSDL name, port type and operation.
Figure 2-26 Custom Adapter Wizard Adapter Interface Screen
The next screen enables the user to choose the type of interaction: Inbound or Outbound. If Outbound Interaction is selected, the Wizard provides a list of Interaction Class names (or translated display names as seen in this example) from which to choose. You earlier provided these names in the customAdapter-config.xml
file.
Figure 2-27 Custom Adapter Configuration Wizard Operation Screen (Inbound Choice)
The following screen enables you to specify the name and value of JCA properties. Depending on the Class Name chosen, the screen displays the properties associated with that class in the customAdapter-config.xm
l file. You can use this screen to change any of the default values and to add or delete properties.
Figure 2-28 Custom Adapter Configuration Wizard JCA Properties Screen
The next screen is the Custom Adapter Wizard Messages Screen, which behaves in a way similar to that of other Adapter Configuration Wizards, enabling you to define the message for the Read File operation, by either specifying a Schema or by declaring that the schema is opaque.
Figure 2-29 Customer Adapter Configuration Wizard Messages Screen
The next page is the Final screen for the Custom Adapter Configuration Wizard. The name of the WSDL files you created is displayed on the screen.
Figure 2-30 Custom Adapter Configuration Wizard Final Screen
Following are some frequently asked questions about adapters.
Why would composite applications are time out? Enough time has been provided for your composite applications to execute with adapters, but applications are still timing out.
A contributing factor is the WebLogic timeout value. The timeout value of the WebLogic Server JTA must be taken into account when you use adapters with your business processing.
For example, you have set the Timeout Seconds
value at 30 seconds. You should increase the value of the Oracle WebLogic JTA attribute Timeout Seconds
from its default of 30 to something greater, something that makes sense in the overall context of your business processing. You can use the WebLogic Server Console to change the JTA transaction timeout value by navigating in this fashion: WLS Console -> SOADomain -> Configuration -> JTA
Transactional Adapters, such as the Oracle JMS Adapter execute within a JTA transaction. A transaction ensures that one or more operations execute as an atomic unit of work.
If an operation within a transaction fails, all operations are rolled-back so that the application is returned to its prior state. Depending on whether the business process logic is defined as stateful or stateless, there may be one or more transactions in a given business process.
Non-transactional adapters implement their own schemes to ensure delivery, without the use of transactional semantics.
The Service Engine obtains a file from an inbound directory, processes the file, and sends the processed file to an output directory. The inbound adapter is limited to translation (if there is one configured) and publishing the translated content which is processed as a part of the business scenario. The business scenario can use the adapter to write to an output directory. However, during this process, if a failover occurs in as a response to a disaster, the file may be lost because of the nontransactional nature of the Oracle File Adapter. As a result, some files read by the inbound adapter might not be sent to the output directory. Of course, when you have a a single node cluster (or no cluster), failover is not an option.
The file adapter is not configured for high availability to avoid message loss, but rather to ensure consistent access to the file system and load balancing across cluster nodes. If you have a single node setup, you do not need a high availability setup for the File adapter, and it does not loose messages.
Consequently, because it is non-transactional, you must configure the Oracle File Adapter for high availability, to ensure that files are not duplicated during a failover. The file adapter never loses messages, but might duplicate some (during disaster recovery).
Additionally, if you have processing scenarios that include Transactional and Non-Transactional Adapters, you must ensure file integrity within the part of your processing that is Non-Transactional.
The JMS adapter can also function with just local transactions; that is, a transaction that begins and commits independently from and within the boundary of a (global) JTA transaction, that is. the local transaction only spans the actual invocation of the adapter.
Rejected messages are stored in the database (specifically, in the rejected_message
table) by default. A default rejected message handler, which stores them on the file system, participates if you have not defined any policy to handle the rejected messages explicitly. This handler stores the payload and properties of the message on the file system at a predefined location in WLS_HOME
. Currently, the Oracle SOA suite does not provide the capability to resubmit rejected messages; consequently it is your responsibility to take care of the resubmission.
SOA Suite 11g deployments can include the use of the technology adapters for various activities including integration with FTP, database, and files, and other activities. 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 using the execution context ID (), but you can lose the ECID correlation when the business transaction spans technologies such as FTP, database, and files.
A new feature in the Oracle adapter JCA framework enables the propagation of the. This feature is available in the SOA Suite 11.1.1.7 with back ports available for 11.1.1.4 and 11.1.1.5.
The basic concept of propagating the ECID is to identify a location in the payload of the message where the ECID can be stored.
Next, 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 provides the JCA framework enough information to either extract the ECID from, or add the ECID to, the message.
When you extract the ECID from the message, the ECID is used for the new component instance.
When determining where to store the ECID in the message, you 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, as trying to find an unused element proves difficult in most situations. The schema is holding the ECID value which looks something like the following:
11d1def534ea1be0:7ae4cac3:13b4455735c:-8000-00000000000002dc
Once you have identified where you want the ECID to be stored in the message, the JCA framework must have this information as well. The two pieces of information that the framework must relate to the message schema:
The namespace for the element in the message.
The XPath to the element in the message.
To better understand this, first look at an example for the following database table:
When the Database Adapter Configuration Wizard creates an Exposed Service in the composite, the following schema is created:
Figure 2-32 Schema Created when Exposed Service is Created
For this example, the two Binding Properties added to the ReadRow service in the composite are:
<!-- Properties for the binding to propagate the from the database table --> <property name="jca..nslist" type="xs:string" many="false"> xmlns:ns1="http://xmlns.oracle.com/pcbpel/adapter/db/top/ReadRow" </property> <property name="jca..xpath" type="xs:string" many="false"> /ns1:PropagationCollection/ns1:Propagation/ns1: </property>
The property called jca..nslist
contains the targetNamespace defined in the schema.
The property called jca..xpath
contains the XPath statement to the element.
The XPath statement also contains the appropriate namespace prefix (ns1) which is defined in the jca..nslist
property.
When the Database Adapter service reads a row from the database, it retrieves the ECID value from the payload and remove the ECID element from the payload. When the component instance is created, it is 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 such as the database, a file, or a queue.
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:
Figure 2-33 The Composite for the Example
The flow of this example occurs in the following order:
Invoke database insert using the insertwithbpelprocess_client_ep
Service.
The InsertWithBPELProcess
adds a row to the database using 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 from the message. The ECID element is removed from the message.
An instance of ReadRowBPLProcess
is created and it is associated with the retried ECID.
The ReadRowBPELProcess
now writes the record to the file system using 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 using the JMS Adapter. The JCA Framework adds the ECID to the message prior to enqueuing the message ECID
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 Fusion Middleware Control, you see all the instances correlated by the ECID:
Figure 2-34 All Instances Correlated by the ECID, as Seen in the Flow Trace