Red Hat SummitChapter 10. Enabling APIs Declaratively
10.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.
10.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"/> </local-cache>
By default invocation batching is disabled; in addition, a transaction manager is not required to use batching.
10.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"/>
</distributed-cache>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" />
</groups>
</distributed-cache>10.4. Externalizable API
10.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.
10.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
<infinispan>
<cache-container>
<serialization>
<advanced-externalizer class="Book$BookExternalizer" />
</serialization>
</cache-container>
</infinispan>
-
Add the
serializationelement to thecache-containerelement. -
Add the
advanced-externalizerelement, defining the custom Externalizer with theclassattribute. Replace theBook$BookExternalizervalues as required.
10.4.3. Custom Externalizer ID Values
10.4.3.1. 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:
| ID Range | Reserved For |
|---|---|
| 1000-1099 | The Infinispan Tree Module |
| 1100-1199 | Red Hat JBoss Data Grid Server modules |
| 1200-1299 | Hibernate Infinispan Second Level Cache |
| 1300-1399 | JBoss Data Grid Lucene Directory |
| 1400-1499 | Hibernate OGM |
| 1500-1599 | Hibernate Search |
| 1600-1699 | Infinispan Query Module |
| 1700-1799 | Infinispan Remote Query Module |
| 1800-1849 | JBoss Data Grid Scripting Module |
| 1850-1899 | JBoss Data Grid Server Event Logger Module |
| 1900-1999 | JBoss Data Grid Remote Store |
10.4.3.2. Customize the Externalizer ID (Declaratively)
Customize the advanced externalizer ID declaratively (via XML) as follows:
Customizing the Externalizer ID (Declaratively)
<infinispan>
<cache-container>
<serialization>
<advanced-externalizer id="123"
class="Book$BookExternalizer"/>
</serialization>
</cache-container>
</infinispan>
-
Add the
serializationelement to thecache-containerelement. -
Add the
advanced-externalizerelement to add information about the new advanced externalizer. -
Define the externalizer ID using the
idattribute. Ensure that the selected ID is not from the range of IDs reserved for other modules. -
Define the externalizer class using the
classattribute. Replace theBook$BookExternalizervalues as required.
