Introduction

Generally speaking, one should use batching API whenever the only participant in the transaction is an Infinispan cluster. On the other hand, JTA transactions (involving TransactionManager) should be used whenever the transactions involves multiple systems. E.g. considering the "Hello world!" of transactions: transferring money from one bank account to the other. If both accounts are stored within Infinispan, then batching can be used. If one account is in a database and the other is Infinispan, then distributed transactions are required.

Configuring batching

To use batching, you need to enable invocation batching in your cache configuration, either on the Configuration object:

Configuration.setInvocationBatchingEnabled(true);

or in your XML file:

<invocationBatching enabled="true" />

By default, invocation batching is disabled.

Note that you do not have to have a transaction manager defined to use batching.

Batching API

Once you have configured your cache to use batching, you use it by calling startBatch() and endBatch() on Cache. E.g.,

Cache cache = cacheManager.getCache();
// not using a batch
cache.put("key", "value"); // will replicate immediately

// using a batch
cache.startBatch();
cache.put("k1", "value");
cache.put("k2", "value");
cache.put("k2", "value");
cache.endBatch(true); // This will now replicate the modifications since the batch was started.
cache.startBatch();
cache.put("k1", "value");
cache.put("k2", "value");
cache.put("k3", "value");
cache.endBatch(false); // This will "discard" changes made in the batch

Advanced: batching and JTA

Behinds the scene, the batching functionality starts a JTA transactions, and all the invocations in that scope are associated with it. For this it uses a very simple (e.g. no recovery) TransactionManager implementation behind the scene. From this you get all sorts of nice behaviour, including:

1. Locks you acquire during an invocation are held until the transaction commits or rolls back.

2. Changes are all replicated around the cluster in a batch as part of the transaction commit process. Reduces replication chatter if multiple changes occur during the transaction.

3. If synchronous replication or invalidation are used, a failure in replication/invalidation will cause the transaction to roll back.

4. If a CacheLoader is used, and that cache loader works with a JTA resource (e.g. a JTA DataSource), the JTA resource can also participate in the transaction.

5. All the transaction related configurations apply for batching as well:

<transaction
    syncRollbackPhase="false" syncCommitPhase="false"
    useEagerLocking="true" eagerLockSingleNode="true" />