Fault Policies Introduction to Oracle Mediator Error Handling

21-4 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite test containsfault.PART_NAMEcustid, 1011 test -- xpath condition based on fault payload -- action ref=ora-retry condition faultName When a reference service returns a business fault, the fault can be handled in the Oracle Mediator service component. The returned fault can be forwarded to another component, redirected to an adapter service such as a file adapter, or an event can be raised. However, if both a fault policy and fault handler are defined for a business fault, then the fault policy takes precedence over the fault handler. In such a case, the fault handlers in the Oracle Mediator service component are ignored, if the fault policy is successfully executed. ■ Adapter-specific fault The errors or faults generated by an adapter can be captured by using the format shown in Example 21–5 : Example 21–5 Capturing Errors or Faults Generated by an Adapter faultName xmlns:medns=http:schemas.oracle.commediatorfaults name=medns:mediatorFault condition testfault.faultCode = 1test -- unique constraint violation in DB adapter-- action ref=ora-retry condition faultName

21.1.1.2 Actions

Actions specify the tasks to perform when an error occurs. Oracle Mediator provides a list of actions that you can use in a fault policy. These predefined actions are described in the following list: ■ Retry: Retry actions such as enqueueing a message to a JMS queue that is stopped, inserting a record with a unique key constraint error, and so on, enable you to retry a task that caused the error. A new thread is started with every retry action. Therefore, with every retry action, a new transaction starts. Table 21–1 describes the options available with the retry action. Table 21–1 Retry Action Options Option Description Retry Count Retry N times. Retry Interval Delay in seconds for a retry. Exponential Backoff Retry interval increase with an exponential backoff. Retry Failure Action Chain to this action if a retry N times fails. Retry Success Action Chain to this action if a retry succeeds. Using Oracle Mediator Error Handling 21-5 Example 21–6 shows how to specify the retry action: Example 21–6 Retry Action Action id=ora-retry retry retryCount3retryCount retryInterval2retryInterval exponentialBackoff retryFailureAction ref=ora-java retrySuccessAction ref=ora-java retry Action If you set the retry Interval in the fault policy to a duration of less than 30 seconds, then the retry may not happen within the specified intervals. This is because the default value of the org.quartz.scheduler.idleWaitTime property is 30 seconds, and the scheduler waits for 30 seconds before retrying for available triggers, when the scheduler is otherwise idle. If the retry interval is set to a value of less than 30 seconds, then latency is expected. If you want the system to use a retry interval that is less than 30 seconds, add the following property under the section property name=quartzProperties in the fabric-config-core.xml file: org.quartz.scheduler.idleWaitTime=value ■ Human intervention: You can specify this action in the following way: Action id=ora-human-interventionhumanInterventionAction ■ Abort: This action enables you to abort the flow. You can specify this action in the following way: Action id=ora-terminateabortAction ■ Java code: This action enables you to call a customized Java class that implements the oracle.integration.platform.faultpolicy.IFaultRecoveryJavaCla ss interface. You can specify this action as shown in Example 21–7 : Example 21–7 Customized Java Class Calling Action id=ora-java javaAction className=mypackage.myClass defaultAction=ora-terminate returnValue value=ABORT ref=ora-terminate returnValue value=RETRY ref=ora-retry Note: Exponential backoff indicates that the next retry attempt is scheduled at 2 x the delay, where delay is the current retry interval. For example, if the current retry interval is 2 seconds, the next retry attempt is scheduled at 4, the next at 8, and the next at 16 seconds until the retryCount value is reached. Note: The implemented Java class must implement a method that returns a string. The policy can be chained to a new action based on the returned string. 21-6 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite returnValue value=MANUAL ref=ora-human-intervention javaAction Action For more information, see Example 21–8 and Example 21–9 . Example 21–8 oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass Interface oracle.integration.platform.faultpolicy.IFaultRecoveryJavaClass { public void handleRetrySuccessIFaultRecoveryContext ctx; public String handleFaultIFaultRecoveryContext ctx; } Example 21–9 oracle.integration.platform.faultpolicy.IFaultRecoveryContext Interface public interface IFaultRecoveryContext { Gets implementation type of the fault. return public String getType; return Get property set of the fault policy action being executed. public Map getProperties; return Get fault policy id of the fault policy being executed. public String getPolicyId; return Name of the faulted reference. public String getReferenceName; return Port type of the faulted reference link. public QName getPortType; } Oracle Mediator Service Engine Implementation Example 21–10 shows the Oracle Mediator service engine implementation of the IFaultRecoveryContext interface. Example 21–10 IFaultRecoveryContext Interface Implementation package oracle.tip.mediator.common.error.recovery; public class MediatorRecoveryContext implements IFaultRecoveryContext{ ... } You can use the methods shown in Example 21–11 to retrieve additional Oracle Mediator-specific data available with the MediatorRecoveryContext class: Using Oracle Mediator Error Handling 21-7 Example 21–11 Methods for Retrieving Data public Fault getFault public CalloutMediatorMessage getMediatorMessage Example 21–12 shows how to retrieve data using the CalloutMediatorMessage interface: Example 21–12 Data Retrieval Using the CalloutMediatorMessage Interface Accessing Mediator Message properties by providing the property name param propertyName return throws MediatorException public Object getPropertyString propertyName; Accessing Mediator Message properties return throws MediatorException public Map getProperties; Accessing instance id of the mediator message This will be the mediator instance id created for that particular message object return throws MediatorException public String getId throws MediatorException; Accessing payload of the mediator message object return throws MediatorException public Map getPayload; Accessing header of the mediator message object return throws MediatorException public ListElement getHeaders; Accessing componentDN for mediator component return throws MediatorException public String getComponentDN Setting payload to the mediator message return throws MediatorCalloutException 21-8 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite public void addPayloadString partName,Object payload throws MediatorCalloutException; Adding property to the mediator message return throws MediatorCalloutException public void addPropertyString name,Object value throws MediatorCalloutException; Adding header to the mediator message return throws MediatorCalloutException public void addHeaderObject header throws MediatorCalloutException;

21.1.2 Fault Bindings

Fault bindings associate fault policies with composites or components, and are defined in the fault-bindings.xml file. Create the fault-bindings.xml file based on the XML schema defined in Section 21.4.2, Schema Definition File for fault-bindings.xml. Fault policies can be created at the following levels: ■ Composite: You can define one fault policy for all Oracle Mediator components in a composite. You can specify this level in the following way: composite faultPolicy=ConnectionFaults ■ Component: You can define a fault policy exclusively for an Oracle Mediator service component. A component-level fault policy overrides the composite-level fault policy. You can specify this level as shown in Example 21–13 . Example 21–13 Definition of a Fault Policy for an Oracle Mediator component faultPolicy=ConnectionFaults nameComponent1name nameComponent2name component ■ Reference: You can define a fault policy for the references of an Oracle Mediator component. You can specify this level as shown in Example 21–14 . Example 21–14 Definition of a Fault Policy for a Reference reference faultPolicy=policy1 nameDBAdapter3name reference A sample fault binding file is shown in Example 21–15 . Note: Human intervention is the default action for errors that do not have a fault policy defined. Using Oracle Mediator Error Handling 21-9 Example 21–15 Sample Fault Binding File ?xml version=1.0 encoding=UTF-8? faultPolicyBindings version=2.0.1 xmlns=http:schemas.oracle.combpelfaultpolicy xmlns:xsi=http:www.w3.org2001XMLSchema-instance composite faultPolicy=ConnectionFaults faultPolicyBindings

21.1.3 Error Groups in Oracle Mediator

You can specify an action for an error type or error group while defining the conditions in a fault policy. In the previous examples, medns:mediatorFault indicates that the error is an Oracle Mediator error, whereas medns:TYPE_FATAL_ MESH refers to an error group. An error group consists of one or more child error types. TYPE_ALL is an error group that contains all Oracle Mediator errors. The following list describes various error groups contained in the TYPE_ALL error group: ■ TYPE_DATA: Contains errors related to data handling. – TYPE_DATA_ASSIGN: Contains errors related to data assignment. – TYPE_DATA_FILTERING: Contains errors related to data filtering. – TYPE_DATA_TRANSFORMATION: Contains errors that occur during a transformation. – TYPE_DATA_VALIDATION: Contains errors that occur during payload validation. ■ TYPE_METADATA: Contains errors related to Oracle Mediator metadata. – TYPE_METADATA_FILTERING: Contains errors that occur while processing the filtering conditions. – TYPE_METADATA_TRANSFORMATION: Contains errors that occur while getting the metadata for a transformation. – TYPE_METADATA_VALIDATION: Contains errors that occur during validation of metadata for Oracle Mediator .mplan file. – TYPE_METADATA_COMMON: Contains other errors that occur during the handling of metadata. ■ TYPE_FATAL: Contains fatal errors that are not easily recoverable. – TYPE_FATAL_DB: Contains database-related fatal errors, such as a Datasource not found error. – TYPE_FATAL_CACHE: Contains Oracle Mediator cache-related fatal errors. – TYPE_FATAL_ERRORHANDLING: Contains fatal errors that occur during error handling such as Resubmission queues not available. – TYPE_FATAL_MESH: Contains fatal errors from the Service Infrastructure such as Invoke service not available. – TYPE_FATAL_MESSAGING: Contains fatal messaging errors arising from the Service Infrastructure. – TYPE_FATAL_TRANSACTION: Contains fatal errors related to transactions such as Commit cant be called on a transaction which is marked for rollback. 21-10 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite – TYPE_FATAL_TRANSFORMATION: Contains fatal transformation errors such as an error occurring because of the XPath functions used in a transformation. ■ TYPE_TRANSIENT: Contains transient errors that can be recovered on a retry. – TYPE_TRANSIENT_MESH: Contains errors related to the Service Infrastructure. – TYPE_TRANSIENT_MESSAGING: Contains errors related to JMS such as enqueuing and dequeuing. ■ TYPE_INTERNAL: Contains internal errors.

21.2 Using Error Handling with Oracle Mediator

You can enable error handling for an Oracle Mediator by using the fault-policies.xml and fault-bindings.xml files.

21.2.1 How to Use Error Handling for an Oracle Mediator Service Component

To use error handling for an Oracle Mediator service component: 1. Create a fault-policies.xml file based on the schema defined in Section 21.4.1, Schema Definition File for fault-policies.xml. 2. Create a fault-bindings.xml file based on the schema defined in Section 21.4.2, Schema Definition File for fault-bindings.xml. 3. Copy the fault-policies.xml and the fault-bindings.xml file to your SOA composite application project directory. 4. Deploy the SOA composite application project.

21.2.2 What Happens at Runtime

All the fault policies for a composite are loaded when the first error occurs. At runtime, Oracle Mediator checks whether there is any policy defined for the current error. If a fault policy is defined, then Oracle Mediator performs the action according to the configuration in the fault policies file. If there is no fault policy defined, then the default action of human intervention is performed.

21.3 Fault Recovery Using Oracle Enterprise Manager Fusion Middleware Control

Apart from policy-based recovery using the fault policy file, you can also perform fault recovery actions on Oracle Mediator faults identified as recoverable in Oracle Enterprise Manager Fusion Middleware Control. This can be performed in the following ways: ■ Manual recovery by modifying the payload using Oracle Enterprise Manager Fusion Middleware Control ■ Bulk recovery without modifying the payload using Oracle Enterprise Manager Fusion Middleware Control ■ Aborting a faulted instance using Oracle Enterprise Manager Fusion Middleware Control, if you do not want to do any more processing on the instance. Using Oracle Mediator Error Handling 21-11 For more information about fault recovery using Oracle Enterprise Manager Fusion Middleware Control, see Oracle Fusion Middleware Administrators Guide for Oracle SOA Suite and Oracle BPM Suite.

21.4 Error Handling XML Schema Definition Files

This section describes the schema files for the fault-policies.xml and fault-bindings.xml files.

21.4.1 Schema Definition File for fault-policies.xml

The fault-policies.xml file should be based on the XSD file shown in Example 21–16 . Example 21–16 XSD File for fault-policies.xml ?xml version=1.0 encoding=UTF-8? xs:schema targetNamespace=http:schemas.oracle.combpelfaultpolicy xmlns:tns=http:schemas.oracle.combpelfaultpolicy xmlns:xs=http:www.w3.org2001XMLSchema elementFormDefault=qualified -- Conditions contain a list of fault names -- xs:element name=Conditions xs:complexType xs:sequence xs:element name=faultName type=tns:faultNameType maxOccurs=unbounded xs:sequence xs:complexType xs:element -- action Ref must exist in the same file -- xs:complexType name=actionRefType xs:attribute name=ref type=xs:string use=required xs:complexType -- one condition has a test and action, if test is missing, this is the catch all condition -- xs:complexType name=conditionType xs:all xs:element name=test type=tns:idType minOccurs=0 xs:element name=action type=tns:actionRefType xs:all xs:complexType -- One fault name match contains several conditions -- xs:complexType name=faultNameType xs:sequence xs:element name=condition type=tns:conditionType maxOccurs=unbounded xs:sequence xs:attribute name=name type=xs:QName xs:complexType xs:complexType name=ActionType xs:choice xs:element name=retry type=tns:RetryType xs:element ref=tns:rethrowFault xs:element ref=tns:humanIntervention xs:element ref=tns:abort xs:element ref=tns:replayScope xs:element name=javaAction type=tns:JavaActionType xs:key name=UniqueReturnValue xs:selector xpath=tns:returnValue