Chapter 9. Enabling APIs Declaratively

9.1. Enabling APIs Declaratively

The various APIs that JBoss Data Grid provides are fully documented in the JBoss Data Grid Developer Guide ; however, Administrators can enable these declaratively by adding elements to the configuration file. The following sections discuss methods on implementing the various APIs.

9.2. Batching API

Batching allows atomicity and some characteristics of a transaction, but does not allow full-blown JTA or XA capabilities. Batching is typically lighter and cheaper than a full-blown transaction, and should be used whenever the only participant in the transaction is the JBoss Data Grid cluster. If the transaction involves multiple systems then JTA Transactions should be used. For example, consider a transaction which transfers money from one bank account to another. If both accounts are stored within the JBoss Data Grid cluster then batching could be used; however, if only one account is inside the cluster, with the second being in an external database, then distributed transactions are required.


Transaction batching is only available in JBoss Data Grid’s Library Mode.

Enabling the Batching API

Batching may be enabled on a per-cache basis by defining a transaction mode of BATCH. The following example demonstrates this:

<local-cache name="batchingCache">
   <transaction mode="BATCH"/>

By default invocation batching is disabled; in addition, a transaction manager is not required to use batching.

9.3. Grouping API

The grouping API allows a group of entries to be co-located on the same node, instead of the default behavior of having each entry being stored on a node corresponding to a calculated hash code of the entry. By default JBoss Data Grid will take a hash code of each key when it is stored and map that key to a hash segment; this allows an algorithm to be used to determine the node that contains the key, allowing each node in the cluster to know which node contains the key without distributing ownership information. This behavior reduces overhead and improves redundancy as the ownership information does not need to be replicated should a node fail.

By enabling the grouping API the hash of the key is ignored when deciding which node to store the entry on. Instead, a hash of the group is obtained and used in its place, while the hash of the key is used internally to prevent performance degradation. When the group API is in use every node can still determine the owners of the key, and due to this reason the group may not be manually specified. A group may either be intrinsic to the entry, generated by the key class, or extrinsic to the entry, generated by an external function.

Enabling the Grouping API

The grouping API may be enabled on a per-cache basis by adding the groups element as seen in the following example:

<distributed-cache name="groupingCache">
    <groups enabled="true"/>

Defining an Extrinsic Group

Assuming a custom Grouper exists it may be defined by passing in the classname as seen below:

<distributed-cache name="groupingCache">
    <groups enabled="true">
        <grouper class="com.acme.KXGrouper" />

9.4. Externalizable API

9.4.1. The Externalizable API

An Externalizer is a class that can:

  • Marshall a given object type to a byte array.
  • Unmarshall the contents of a byte array into an instance of the object type.

Externalizers are used by Red Hat JBoss Data Grid and allow users to specify how their object types are serialized. The marshalling infrastructure used in Red Hat JBoss Data Grid builds upon JBoss Marshalling and provides efficient payload delivery and allows the stream to be cached. The stream caching allows data to be accessed multiple times, whereas normally a stream can only be read once.

The Externalizable interface uses and extends serialization. This interface is used to control serialization and deserialization in Red Hat JBoss Data Grid.

9.4.2. Register the Advanced Externalizer (Declaratively)

After the advanced externalizer is set up, register it for use with Red Hat JBoss Data Grid. This registration is done declaratively (via XML) as follows:

Register the Advanced Externalizer

            <advanced-externalizer class="Book$BookExternalizer" />

  1. Add the serialization element to the cache-container element.
  2. Add the advanced-externalizer element, defining the custom Externalizer with the class attribute. Replace the Book$BookExternalizer values as required.

9.4.3. Configuring the Deserialization Whitelist

For security reasons, the Red Hat JBoss Data Grid server does not deserialize objects of an arbitrary class. JBoss Data Grid allows deserialization only for strings and primitives. If you want JBoss Data Grid to deserialize objects for other Java class instances, you must configure a deserialization whitelist.

Add the following system properties to the JVM at start up:

  • -Dinfinispan.deserialization.whitelist.classes Specifies the fully qualified names of one or more Java classes. JBoss Data Grid deserializes objects that belong to those classes.
  • -Dinfinispan.deserialization.whitelist.regexps Specifies one or more regular expressions. JBoss Data Grid deserializes objects that belong to any class that matches those expressions.

Both system properties are optional. You can specify a combination of both properties or specify either property by itself.

For example, the following system properties enable deserialization for the and classes as well as for any classes that match the .*SpotPrice.* expression:,

If you want to configure the whitelist so that JBoss Data Grid allows deserialization for any Java class, specify the following:


For information on configuring clients to restrict deserialization to specific Java classes, see Restricting Deserialization to Specific Java Classes in the Developer Guide.

9.4.4. Custom Externalizer ID Values Custom Externalizer ID Values

Advanced externalizers can be assigned custom IDs if desired. Some ID ranges are reserved for other modules or frameworks and must be avoided:

Table 9.1. Reserved Externalizer ID Ranges

ID RangeReserved For


The Infinispan Tree Module


Red Hat JBoss Data Grid Server modules


Hibernate Infinispan Second Level Cache


JBoss Data Grid Lucene Directory


Hibernate OGM


Hibernate Search


Infinispan Query Module


Infinispan Remote Query Module


JBoss Data Grid Scripting Module


JBoss Data Grid Server Event Logger Module


JBoss Data Grid Remote Store Customize the Externalizer ID (Declaratively)

Customize the advanced externalizer ID declaratively (via XML) as follows:

Customizing the Externalizer ID (Declaratively)

            <advanced-externalizer id="123"

  1. Add the serialization element to the cache-container element.
  2. Add the advanced-externalizer element to add information about the new advanced externalizer.
  3. Define the externalizer ID using the id attribute. Ensure that the selected ID is not from the range of IDs reserved for other modules.
  4. Define the externalizer class using the class attribute. Replace the Book$BookExternalizer values as required.