com.neeve.toa.opt

Interface DelayedAcknowledgmentController

public interface DelayedAcknowledgmentController

Provides the ability to delay acknowledgments for inbound messages for applications that do additional processing outside of a the messages handler.

To facilitate this functionality a DelayedAcknowledgmentController provides a delayAcknowledgment() method. When this method is called from within a message handler, it returns a DelayedAcknowledger. Acknowledgment of the AEP transaction in which the message was dispatched to the application is suspended until the the application calls DelayedAcknowledgmentController.DelayedAcknowledger.acknowledge().

A TopicOrientedApplication only creates a DelayedAcknowledgmentController when the configuration property nv.toa.enabledelayedackcontroller is set to true. When enabled, an additional executor bus is added to the application. Under the covers delayed acknowledgment is done by sending a DelayedAckMessage over the executor bus and attaching the returned DelayedAcknowledger to the message. The inbound message is acknowledged when both the application calls DelayedAcknowledger.acknowledged() and the underlying executor bus processes the DelayedAckMessage. In this way acks are delayed in an ordered fashion with respect to other messsages in the transacton flow -- namely on outbound send stability.

Delayed acknowledgments are only supported on engines that are not configured with a store. This restriction exists because the processing done by a non message handler thread can't be reliably performed from an HA standpoint on a backup instance or during recovery. Applications needing to do HA reliable work in a thread other the engine thread should use an executor bus which provides asynchrononus acknowledgment capabilities and and the ability to resume such work across failover and recovery.

The DelayedAcknowledgmentController is classified as an experimental feature provided mainly as a convenience to developers doing stateless work. Applications that need more flexibility or have HA needs are encouraged to use an executor bus directly.

Example Code

Delaying Acknowledgment

 @AppHAPolicy(HAPolicy.EventSourcing)
 public class MyApp extends TopicOrientedApplication {
   ExecutorService executor = Executors.newSingleThreadExecutor();
  
   @EventHandler
   public void onMessage(MyMessage message) {
     final DelayedAcknowledger delayedAck = getDelayedAcknowledgmentController().delayAcknowledgment();
     
     //Do some potentially blocking work in a background thread:
     executor.execute(new Runnable() {
       public void run() {
          EmailAlertUtil.sendEmail("I got a message!");
          delayedAck.acknowledge();
       }
     });
   }
 }
 

Using the inbound message in a separate thread

Per the AepEngine contract, you should copy or acquire the message if you plan to use it outside of a handler. The example below shows such a scenario:

 @AppHAPolicy(HAPolicy.EventSourcing)
 public class MyApp extends TopicOrientedApplication {
 
   ExecutorService executor = Executors.newSingleThreadExecutor();
  
   @EventHandler
   public void onMessage(MyMessage message) {
     final DelayedAcknowledger delayedAck = getDelayedAcknowledgmentController().delayAcknowledgment();
     
     final MyMessage messageCopy = message.copy();
     
     //Schedule some work to do on a copy of the message
     //in a background thread:
     executor.execute(new Runnable() {
       public void run() {
          byte [] messageCopy.serializeToByteArray()
          //TODO do something with the message
          messageCopy.dispose();
          
          //If the application fails before above processing
          //is complete the message will not have been
          //acknowledged and can be reprocessed on application
          //restart.
          delayedAck.acknowledge();
       }
     });
   }
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	DelayedAcknowledgmentController.DelayedAcknowledger A delayed acknowledger handle.

Method Summary

Modifier and Type	Method and Description
DelayedAcknowledgmentController.DelayedAcknowledger	delayAcknowledgment() Creates a delayed acknowledger.

Method Detail

delayAcknowledgment

DelayedAcknowledgmentController.DelayedAcknowledger delayAcknowledgment()

Creates a delayed acknowledger.

When called from message handler this method delays completion of the AEP transaction in which the message is being processed until the returned DelayedAcknowledgmentController.DelayedAcknowledger's acknowledge() method is called.

Returns:

A DelayedAcknowledgmentController.DelayedAcknowledger.

Throws:

IllegalStateException - If called from outside of a message handler thread.

UnsupportedOperationException - If called from an engine that is configured in a manner in which delayed acknowledgments are not supported.