...
| Excerpt |
|---|
An AEPEngine handles processing of each inbound message it receives in an atomic fashion - the acknowledgement acknowledgment of message receipt, application changes to state and outbound messages constitute an atomic unit of work. Each such atomic unique of work is considered an AEP transaction. Transactions are, for the most part, handled, transparently from an application's standpoint. Application developers simply write message handlers with the assurance the processing done therein will be atomic. |
Adaptive Batching
By default, an AEPEngine handles processing of each inbound message it receives as a single transaction. It is possible to configure an AEPEngine AepEngine to attempt to batch up the processing of several inbound messages into a single transaction via a feature called adaptive batching. This feature can improve throughput at the cost of increased latency of outbound messages (the outbound messages for the first message processed in a batch won't be sent until the last message in the batch has been stabilized. The batching behavior is adaptive in nature because the engine commits a batch automatically when either a configured adapative adaptive batch ceiling is reached or the engine detects there are no more messages immediately available to process.
...
The adaptiveCommitBatchCeiling for the app is set to 0 by default which disables adaptive batching. When the platform is optimized for throughput via the nv.optimizefor=throughput runtime property, the adaptive batch ceiling is set to 64 unless otherwise explicitly configured by the application.
...
- The application creates a savepoint at the beginning of its handler
- It then updates the count of orders received for a customer and possibly sends out a promotional message.
- Later, if the handler determines that there isn't enough inventory to satisfy the order it rolls back to the initial savepoint which:
- Resets the customer's ordersReceivedCount to its previous value
- Cancels the possible promotional message for the customer.
- After the rollback, the handler then sends an order rejected message and increments a rejection count for the customer.
- The net result of processing is thus an incremented orderRejectedCount for the customer and an order rejected message.
...
The current savepoint for an AepEngine can be retrieve retrieved via the AepEngine.getTransactionSavepoint() method.
...
In addition to the restrictions outlined below an attempt to rollback roll back to a savepoint less than 0 or greater than the current savepoint will result in an IllegalStateException.
...
An EAepRollbackError thrown from this method indicates that therd was an internal or runtime error performing the rollback. In this case, application event handlers must allow the error to be thrown back for the platform to handle as the application state may be in a corrupt state. If the AepEngine can recover by rolling back the entire transaction, the error will be handled according to the AppExceptionHandlingPolicy. Otherwise, otherwise the engine will stop with the EAepRollbackError.
...
Outbound messages that are rolled back cannot be reused - the transfer of ownership to the AepEngine is preserved. Additionally, it should be noted that rollback does not rollback changes made to outbound messages' fields. When the engine is configured to dispose on send the engine may dispose of such messages during rollback, so applications should not rely on messages tranfered transferred to the engine being valid post rollback.
...
When the engine is configured for adapative adaptive batching, multiple inbound messages are grouped into a single store transaction. Savepoints don't span multiple inbound messages. Instead, the processing effect effects of previous messages are fenced off from subsequent savepoints. Effectively, under the covers, the engine creates an internal savepoint for fully processed inbound messages and resets the application visible savepoint to 0 for subequent subsequent messages.
Multiple event handlers
...
- the engine is configured with savepoints enabled
AepEngineDescriptor#getEnableTransactionSavepoints()== true - the engine is backed by a store (e.g.
getStore()!= null - Only called from within application message handlers called from event handlers -- only the engine's message processing thread may work with savepoints.
isDispatchThread()&& # - the engine is not configured for parallel cluster replication
AepEngineDescriptor.getReplicateInParallel()== false
...
Usage of savepoints when operating with an HAPolicy of EventSourcing is currently classified as an expiremental experimental feature. Because application state is not managed by the platform for EventSourcing, only an applications outbound messages are rolled back by this method.
When using EventSourcing, message handlers are invoked on a Backup instance or an instance recovering from a transaction log. It is crucial that a backup or recovering instance's behavior or it will lead to divergence in the application's outbound messages. This means that application logic on a backup must create the same savepoints as a primary and rollback based on the same criteria. For this reason, it is often preferable for an EventSourcing app that encounters an error to simply throw an exception from its event handler and let the inbound message's fate be governed by the AppExceptionHandlingPolicy.
See Also
Aep AEP Engine Trace - for details on enabling AEP transaction trace.