Transient Error Handling for Transacted JMS Triggers

When building a transacted JMS trigger, you can specify what action Integration Server takes when a transient error causes a trigger service or a web service operation to fail and the entire transaction is rolled back.

A transient error is an error that arises from a temporary condition that might be resolved or corrected quickly, such as the unavailability of a resource due to network issues or failure to connect to a database. A transient error is caused by a run-time exception. A run-time exception (specifically, an ISRuntimeException) occurs in the following situations.

The trigger service catches and wraps a transient error and then re-throws it as an ISRuntimeException.
The web service operation that processes the message received by a SOAP-JMS trigger catches and wraps a transient error and then re-throws it as an ISRuntimeException.
Note: For a service handler invoked by a SOAP-JMS trigger, Integration Server treats all errors as fatal. Service handlers invoked by SOAP-JMS triggers cannot be retried.
The pub.jms:send, pub.jms:sendAndWait, or pub.jms:reply service fails because a resource (such as the JNDI provider or JMS provider) is not available.
If the JMS provider is not available, and the settings for the pub.jms* service indicate that Integration Server should write messages to the client side queue, Integration Server does not throw an ISRuntimeException.
A transient error occurs on the back-end resource for an adapter service. Adapter services built on Integration Server 6.0 or later, and based on the ART framework, detect and propagate exceptions that signal a retry automatically if a transient error is detected on their back-end resource.

Note: A web service connector that sends a JMS message can throw an ISRUntimeException, such as when the JMS provider is not available. However, Integration Server automatically places the ISRuntimeException in the fault document returned by the web service connector. If you want the parent flow service to catch the transient error and re-throw it as an ISRuntimeException, you must code the parent flow service to check the fault document for an ISRuntimeException and then throw an ISRuntimeException explicitly.

You can specify one of the following transient error handling options for a transacted JMS trigger:

Recover only. After a transaction is rolled back, Integration Server receives the message from the JMS provider almost immediately. This is the default.
Suspend and recover. After a transaction is rolled back, Integration Server suspends the JMS trigger and receives the message from the JMS provider at a later time.

You can also configure Integration Server and/or a JMS trigger to handle transient errors that occur during trigger preprocessing. The trigger preprocessing phase encompasses the time from when a trigger first receives a message from it’s local queue on Integration Server b to the time the trigger service executes.

For more information about transient error handling for trigger preprocessing, see Transient Error Handling During Trigger Preprocessing.

Overview of Recover Only for Transaction Rollback

The following table provides an overview of how Integration Server handles transaction rollback when the Recover Only option is selected for a transacted JMS trigger.

Step	Description
1	The trigger service web service operation fails because of an ISRuntimeException.
2	Integration Server rolls back the entire transaction. When the transaction is rolled back, Integration Server recovers the message back to the JMS provider automatically. The JMS provider marks the message as redelivered and increments the delivery count (`JMSXDeliveryCount` field in the JMS message). At this point, a JMS provider typically makes the message available for immediate redelivery.
3	Integration Server receives the same message from the JMS provider and processes the message. Because Integration Server receives the message almost immediately after transaction roll back, it is likely that the temporary condition that caused the ISRuntimeException has not resolved and the trigger service will end with a transient error again. Consequently, setting On transaction rollback to Recover only could result in wasted processing. Note: Integration Server enforces a maximum delivery count, which determines the maximum number of time the JMS provider can deliver the message to the JMS trigger. If the maximum delivery count has been met, the JMS provider will not deliver the message to the JMS trigger. Instead, the JMS provider will acknowledge and remove the message. The maximum delivery count is controlled by the watt.server.jms.trigger.maxDeliveryCount property.

Step

Description

The trigger service web service operation fails because of an ISRuntimeException.

Integration Server rolls back the entire transaction.

When the transaction is rolled back, Integration Server recovers the message back to the JMS provider automatically. The JMS provider marks the message as redelivered and increments the delivery count (JMSXDeliveryCount field in the JMS message).

At this point, a JMS provider typically makes the message available for immediate redelivery.

Integration Server receives the same message from the JMS provider and processes the message.

Because Integration Server receives the message almost immediately after transaction roll back, it is likely that the temporary condition that caused the ISRuntimeException has not resolved and the trigger service will end with a transient error again. Consequently, setting On transaction rollback to Recover only could result in wasted processing.

Note: Integration Server enforces a maximum delivery count, which determines the maximum number of time the JMS provider can deliver the message to the JMS trigger. If the maximum delivery count has been met, the JMS provider will not deliver the message to the JMS trigger. Instead, the JMS provider will acknowledge and remove the message. The maximum delivery count is controlled by the watt.server.jms.trigger.maxDeliveryCount property.

Overview of Suspend and Recover for Transaction Rollback

The following table provides an overview of how Integration Server handles transaction rollback when the Suspend and recover option is selected for a transacted JMS trigger.

Step	Description
1	The trigger service or web service operation fails because of an ISRuntimeException.
2	Integration Server rolls back the entire transaction. When the transaction is rolled back, Integration Server recovers the message back to the JMS provider automatically. The JMS provider marks the message as redelivered and increments the delivery count (`JMSXDeliveryCount` field in the JMS message).
3	Integration Server suspends the JMS trigger temporarily. The JMS trigger is suspended on this Integration Server only. If the Integration Server is part of a cluster, other servers in the cluster can retrieve and process messages for the trigger. Important: If you disable or suspend a SOAP-JMS trigger that acts as a listener for one or more provider web service descriptors, Integration Server will not retrieve any messages for those web service descriptors until the SOAP-JMS trigger is enabled. Note: The change to the trigger state is temporary. Message processing will resume for the trigger if Integration Server restarts, the trigger is enabled or disabled, or the package containing the trigger reloads. You can also enable triggers manually using Integration Server Administrator or by invoking the pub.trigger:enableJMSTriggers service.
4	Optionally, Integration Server schedules and executes a resource monitoring service. A resource monitoring service is a service that you create to determine whether the resources associated with a trigger service are available. A resource monitoring service returns a single output parameter named `isAvailable`.
5	If the resource monitoring service indicates that the resources are available (that is, the value of `isAvailable` is true), Integration Server enables the trigger. Message processing and message retrieval resume for the JMS trigger. If the resource monitoring service indicates that the resources are not available (that is, the value of `isAvailable` is false), Integration Server waits a short time interval (by default, 60 seconds) and then re-executes the resource monitoring service. Integration Server continues executing the resource monitoring service periodically until the service indicates the resources are available. Tip: You can change the frequency at which the resource monitoring service executes by modifying the value of the watt.server.jms.trigger.monitoringInterval property.
6	After Integration Server resumes the JMS trigger, Integration Server receives the message from the JMS provider and processes the message. Note: If the maximum delivery count has been met, the JMS provider will not deliver the message to the JMS trigger. The maximum delivery count determines the maximum number of time the JMS provider can deliver the message to the JMS trigger. It is controlled by the watt.server.jms.trigger.maxDeliveryCount property.

Configuring Transient Error Handling for Transacted JMS Triggers

About this task

The transient error handling and transaction rollback behavior that you specify for a transacted JMS trigger determines how Integration Server handles transaction rollback caused by transient errors during trigger service execution. The selected behavior also determines how Integration Server handles transient errors that occur during trigger preprocessing.

For more information about transient error handling for trigger preprocessing, see Transient Error Handling During Trigger Preprocessing.

Use the following procedure to configure how Integration Server responds when a transaction is rolled back due to a transient error that occurs during processing of a transacted JMS trigger.

To configure transient error handling for a transacted JMS trigger

Procedure

In the Package Navigator view of Designer, open the trigger for which you want to configure transient error handling.

In the Properties view, under Transient error handling, in the On transaction rollback property, select one of the following:

Select...	To...
Recover only	Specify that Integration Server recovers the message after a transaction is rolled back due to a transient error. This is the default.
Suspend and recover	Specify that Integration Server does the following after a transaction is rolled back due to a transient error: Suspends the JMS trigger Recovers the message after a resource monitoring service indicates that the resources needed by the trigger service are available.

If you selected Suspend and recover, in the Resource monitoring service property, specify the service that Integration Server should execute to determine the availability of resources associated with the trigger service or web service operation. Multiple triggers can use the same resource monitoring service.
Click File > Save.