Chapter 4. The Batching API

4.1. The Batching API

The Batching API is used when the Red Hat JBoss Data Grid cluster is the sole participant in a transaction. However, Java Transaction API (JTA) transactions (which use the Transaction Manager) are used when multiple systems are participants in the transaction.

Note

The Batching API may only be used in Red Hat JBoss Data Grid’s Library Mode.

4.2. About Java Transaction API

Red Hat JBoss Data Grid supports configuring, use of, and participation in Java Transaction API (JTA) compliant transactions.

JBoss Data Grid does the following for each cache operation:

  1. First, it retrieves the transactions currently associated with the thread.
  2. If not already done, it registers an XAResource with the transaction manager to receive notifications when a transaction is committed or rolled back.

4.3. Batching and the Java Transaction API (JTA)

In Red Hat JBoss Data Grid, the batching functionality initiates a JTA transaction in the back end, causing all invocations within the scope to be associated with it. For this purpose, the batching functionality uses a simple Transaction Manager implementation at the back end. As a result, the following behavior is observed:

  1. Locks acquired during an invocation are retained until the transaction commits or rolls back.
  2. All changes are replicated in a batch on all nodes in the cluster as part of the transaction commit process. Ensuring that multiple changes occur within the single transaction, the replication traffic remains lower and improves performance.
  3. When using synchronous replication or invalidation, a replication or invalidation failure causes the transaction to roll back.
  4. When a cache is transactional and a cache loader is present, the cache loader is not enlisted in the cache’s transaction. This results in potential inconsistencies at the cache loader level when the transaction applies the in-memory state but (partially) fails to apply the changes to the store.
  5. All configurations related to a transaction apply for batching as well.

4.4. Using the Batching API

4.4.1. Configure the Batching API

To use the Batching API, enable invocation batching in the cache configuration, as seen in the following example: 

Configuration c = new ConfigurationBuilder().transaction().transactionMode(TransactionMode.TRANSACTIONAL).invocationBatching().enable().build();

In Red Hat JBoss Data Grid, invocation batching is disabled by default and batching can be used without a defined Transaction Manager.

4.4.2. Use the Batching API

After the cache is configured to use batching, call startBatch() and endBatch() on the cache as follows to use batching: 

Cache cache = cacheManager.getCache();

Without Using Batch

cache.put("key", "value");

When the cache.put(key, value); line executes, the values are replaced immediately.

Using Batch

cache.startBatch();
cache.put("k1", "value");
cache.put("k2", "value");
cache.put("k3", "value");
cache.endBatch(true);
cache.startBatch();
cache.put("k1", "value");
cache.put("k2", "value");
cache.put("k3", "value");
cache.endBatch(false);

When the line cache.endBatch(true); executes, all modifications made since the batch started are applied.

When the line cache.endBatch(false); executes, changes made in the batch are discarded.