JCA Error Handling Part 2 in SOA 11g

In this JCA Error Handling Part 2 we will see about Inbound Interaction Error Handling and configuring Inbound Adapters to Handle Retryable Errors.

Inbound Interaction Error Handling

Message errors include those that occur during translation, correlation ID mismatch and XML parsing after message reception.

Before considering error handling in terms of retryability, it is important to understand the error handlers that are available.

Following are the system-defined error handlers, which you can configure through fault policies:.

• Web Service Handler
• Custom Java Handler 
• JMS Queue
• File

1      Web Service Handler

A rejected message can be handled by calling a predefined Web Service. The WSDL Interface for the Web Service handler must have one port type, only one input operation, and a schema for the input message.

<?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>

1     Custom Java Handler

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);

} 

JMS Queue

You can enqueue a rejected message to a JMS queue as a JMS message with the appropriate context and payload

<Action id="ora-queue">

<enqueue uri="QueueURI"/> <!-- QueueURI format -

jdbc:oracle:thin:@<host>:<port>:<sid>#<un>/<pw>#queue -->

</Action>

The second example is used with an Oracle RAC database:

<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> 

File

You create an error handler for messages by storing a rejected message in a file. You can store the payload with the proper context

<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>

NOTE: Error payload persistence in the Database is available by default. Only the FileAdapter handler creates a metadata file(like inbound direction and file name) that contains all the properties of the rejected message. The location of metadata file is same as the payload file and the naming pattern is <FILE_NAME>_metadata

 

Inbound Retryable Errors

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. Any JTA transaction is rolled back before a retry.

Examples of retryable errors thrown by outbound adapters include connection errors but include also termporary 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.

Configuring Inbound Adapters to Handle Retryable Errors

You can configure inbound adapters to handle inbound retryable errors at composite (local) application level or at the global level.

<service name="Inbound">

<interface.wsdl interface="http://xmlns...#wsdl.interface(Inbound_PortType)"/>

<binding.jca config="Inbound_db.jca">

<!-- Specifies the maximum number of retries before rejection-- >

<property name="jca.retry.count">5</property>

<!-- Specifies the time interval between retries (measured in seconds.) -- >

<property name="jca.retry.interval">1</property>

<!--Specifies the retry interval growth factor (positive integer.)-- >

<property name="jca.retry.backoff">2</property>

<!-- Specifies the maximum value of retry interval, that is, a cap if backoff > 1 -- >

<property name="jca.retry.maxInterval">6</property>

</binding.jca>

</service>

Note: if you have not set any value for jca.retry.count, the retry is carried out indefinitely, which is the default for retryable errors. 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.

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

Oracle Enterprise Manager. Any change you do through the MBeans browser takes immediate effect for all current and future endpoints.

1.      Navigate to http://servername:portnumber/em 
2.       Right-click soa-infra 
3.       From the SOA Infrastructure menu, select Administration, and then System Mbean Browser 
4.       Select oracle.as.soainfra.config, Server, AdapterConfig, and then adapter 
5.       Modify the GlobalInboundJcaRetryCount attribute (as an example of a Global Property)

Inbound Non-Retryable Errors

Typically non-retryable errors are a result of either transformation or message parsing.

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