Administration and Configuration Guide

Eviction types define the maximum limit for entries in the cache.

Storage types define how JBoss Data Grid stores entries in the cache.

The <memory> element controls how Red Hat JBoss Data Grid stores entries in memory.

For example, as a starting point to configure eviction for a standalone cache, add the <memory> element as follows:

<local-cache ...>
  <memory>
  </memory>
</local-cache>

Define the storage type as a child element under <memory>, as follows:

Include the eviction attribute with the value set to COUNT or MEMORY.

Include the size attribute with a value set to a number greater than zero.

Include the address-count attribute when using OFFHEAP storage to prevent collisions that might decrease performance. This attribute specifies the number of pointers that are available in the hash map.

Set the value of the address-count attribute to a number that is greater than the number of cache entries. By default address-count is 2^20, or 1048576. The parameter is always rounded up to a power of 2.

<memory>
  <offheap eviction="MEMORY" size="10000000000" address-count="1048576"/>
</memory>

Eviction strategies control how Red Hat JBoss Data Grid performs eviction. You set eviction strategies with the strategy attribute.

The default strategy is NONE, which disables eviction unless you explicitly configure it. For example, here are two configurations that have the same effect:

<memory/>

<memory>
  <object strategy="NONE"/>
</memory>

When you configure eviction, you implicitly use the REMOVE strategy. For example, the following two configurations have the same effect:

<memory>
  <object/>
</memory>

<memory>
  <object strategy="REMOVE"/>
</memory>

Passivation configures Red Hat JBoss Data Grid to write entries to a persistent cache store when it removes those entries from memory. In this way, passivation ensures that only a single copy of an entry is maintained, either in-memory or in a cache store but not both.

For more information, see Setting Up Passivation.

Expiration parameters configure the amount of time entries can remain in the cache.

Configure Red Hat JBoss Data Grid to perform expiration for a cache as follows:

Red Hat JBoss Data Grid cannot always expire entries immediately when they reach the time limit. Instead, JBoss Data Grid marks entries as expired and removes them when:

This behavior might indicate that JBoss Data Grid is not performing expiration as expected. However it is the case that the entries are marked as expired but not yet removed from either the memory or the cache store.

To ensure that users cannot receive expired entries, JBoss Data Grid returns null values for entries that are marked as expired but not yet removed.

Red Hat JBoss LogManager supports the following logging frameworks:

JBoss Logging is the application logging framework that is included in JBoss Enterprise Application Platform 7. As a result of this inclusion, Red Hat JBoss Data Grid 7 also uses JBoss Logging.

JBoss Logging provides an easy way to add logging to an application. Add code to the application that uses the framework to send log messages in a defined format. When the application is deployed to an application server, these messages can be captured by the server and displayed and/or written to file according to the server’s configuration.

JBossLogging includes the following features:

The boot log is the record of events that occur while the server is starting up (or booting). Red Hat JBoss Data Grid also includes a server log, which includes log entries generated after the server concludes the boot process.

Edit the logging.properties file to configure the boot log. This file is a standard Java properties file and can be edited in a text editor. Each line in the file has the format of property=value.

In Red Hat JBoss Data Grid, the logging.properties file is available in the $JDG_HOME/standalone/configuration folder.

The following table provides a list of log files in Red Hat JBoss Data Grid and their locations:

Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message. The level of a given log message is specified by the developer using the appropriate methods of their chosen logging framework to send the message.

Red Hat JBoss Data Grid supports all the log levels used by the supported application logging frameworks. The six most commonly used log levels are (ordered by lowest to highest severity):

Log levels are used by log categories and handlers to limit the messages they are responsible for. Each log level has an assigned numeric value which indicates its order relative to other log levels. Log categories and handlers are assigned a log level and they only process log messages of that numeric value or higher. For example a log handler with the level of WARN will only record messages of the levels WARN, ERROR and FATAL.

The following table lists log levels that are supported in Red Hat JBoss Data Grid. Each entry includes the log level, its value and description. The log level values indicate each log level’s relative value to other log levels. Additionally, log levels in different frameworks may be named differently, but have a log value consistent to the provided list.

Log categories define a set of log messages to capture and one or more log handlers which will process the messages.

The log messages to capture are defined by their Java package of origin and log level. Messages from classes in that package and of that log level or higher (with greater or equal numeric value) are captured by the log category and sent to the specified log handlers. As an example, the WARNING log level results in log values of 900, 1000 and 1100 are captured.

Log categories can optionally use the log handlers of the root logger instead of their own handlers.

The root logger captures all log messages sent to the server (of a specified level) that are not captured by a log category. These messages are then sent to one or more log handlers.

By default the root logger is configured to use a console and a periodic log handler. The periodic log handler is configured to write to the file server.log . This file is sometimes referred to as the server log.

Log handlers define how captured log messages are recorded by Red Hat JBoss Data Grid. The six types of log handlers configurable in JBoss Data Grid are:

Log handlers direct specified log objects to a variety of outputs (including the console or specified log files). Some log handlers used in JBoss Data Grid are wrapper log handlers, used to direct other log handlers' behavior.

Log handlers are used to direct log outputs to specific files for easier sorting or to write logs for specific intervals of time. They are primarily useful to specify the kind of logs required and where they are stored or displayed or the logging behavior in JBoss Data Grid.

The following table lists the different types of log handlers available in Red Hat JBoss Data Grid:

The following are the most common uses for each of the log handler types available for Red Hat JBoss Data Grid:

A log formatter is the configuration property of a log handler. The log formatter defines the appearance of log messages that originate from the relevant log handler. The log formatter is a string that uses the same syntax as the java.util.Formatter class.

See http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html for more information.

All of the sample configurations presented in this section should be placed inside the server’s configuration file, typically either standalone.xml or clustered.xml for standalone instances, or domain.xml for managed domain instances.

The following procedure demonstrates a sample configuration for the root logger.

The following procedure demonstrates a sample configuration for a log category.

<subsystem xmlns="urn:jboss:domain:logging:3.0">
   <logger category="com.company.accounts.rec" use-parent-handlers="true">
      <level name="WARN"/>
      <handlers>
         <handler name="accounts-rec"/>
      </handlers>
   </logger>
</subsystem>

The following procedure demonstrates a sample configuration for a console log handler.

<subsystem xmlns="urn:jboss:domain:logging:3.0">
   <console-handler name="CONSOLE" autoflush="true">
      <level name="INFO"/>
      <encoding value="UTF-8"/>
      <target name="System.out"/>
      <filter-spec value="not(match(&quot;JBAS.*&quot;))"/>
      <formatter>
         <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
      </formatter>
   </console-handler>
</subsystem>

The following procedure demonstrates a sample configuration for a file log handler.

<file-handler name="accounts-rec-trail" autoflush="true">
    <level name="INFO"/>
    <encoding value="UTF-8"/>
    <file relative-to="jboss.server.log.dir" path="accounts-rec-trail.log"/>
    <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
    <append value="true"/>
</file-handler>

The following procedure demonstrates a sample configuration for a periodic log handler.

<periodic-rotating-file-handler name="FILE" autoflush="true">
   <level name="INFO"/>
   <encoding value="UTF-8"/>
   <formatter>
      <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
   </formatter>
   <file relative-to="jboss.server.log.dir" path="server.log"/>
   <suffix value=".yyyy-MM-dd"/>
   <append value="true"/>
</periodic-rotating-file-handler>

The following procedure demonstrates a sample configuration for a size log handler.

<size-rotating-file-handler name="accounts_debug" autoflush="false">
   <level name="DEBUG"/>
   <encoding value="UTF-8"/>
   <file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
   <rotate-size value="500k"/>
   <max-backup-index value="5"/>
   <formatter>
        <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
    </formatter>
   <append value="true"/>
</size-rotating-file-handler>

The following procedure demonstrates a sample configuration for an async log handler

<async-handler name="Async_NFS_handlers">
   <level name="INFO"/>
   <queue-length value="512"/>
   <overflow-action value="block"/>
   <subhandlers>
      <handler name="FILE"/>
      <handler name="accounts-record"/>
   </subhandlers>
</async-handler>

Using Red Hat JBoss Data Grid’s local mode instead of a map provides a number of benefits.

Caches offer features that are unmatched by simple maps, such as:

JBoss Data Grid is built around a high performance, read-based data container that uses techniques such as optimistic and pessimistic locking to manage lock acquisitions.

JBoss Data Grid also uses compare-and-swap and other lock-free algorithms, resulting in high throughput multi-CPU or multi-core environments. Additionally, JBoss Data Grid’s Cache API extends the JDK's ConcurrentMap, resulting in a simple migration process from a map to JBoss Data Grid.

A local cache can be added to any cache container in both Library Mode and Remote Client-Server Mode. The following example demonstrates how to add the local-cache element.

<cache-container name="local"
                 default-cache="default"
                 statistics="true">
    <local-cache name="default"
        statistics="true">
        <!-- Additional configuration information here -->
    </local-cache>
</cache-container>

The local-cache element specifies information about the local cache used with the cache container using the following parameters: . The name parameter specifies the name of the local cache to use. . If statistics are enabled at the container level, per-cache statistics can be selectively disabled for caches that do not require monitoring by setting the statistics attribute to false.

Local and clustered caches are able to coexist in the same cache container, however where the container is without a <transport/> it can only contain local caches. The container used in the example can only contain local caches as it does not have a <transport/>.

The cache interface extends the ConcurrentMap and is compatible with multiple cache systems.

Red Hat JBoss Data Grid offers the following clustered modes:

The clustered modes can be further configured to use synchronous or asynchronous transport for network communications.

When a clustered mode (such as invalidation, replication or distribution) is used, data is propagated to other nodes in either a synchronous or asynchronous manner.

If synchronous mode is used, the sender waits for responses from receivers before allowing the thread to continue, whereas asynchronous mode transmits data but does not wait for responses from other nodes in the cluster to continue operations.

JBoss Data Grid clusters are configured to use synchronous operations by default.

Asynchronous mode prioritizes speed over consistency, which is ideal for use cases such as HTTP session replications with sticky sessions enabled. Such a session (or data for other use cases) is always accessed on the same cluster node, unless this node fails. If data consistency is required for your use case, you should use synchronous operations.

Additionally, it is not possible for JBoss Data Grid nodes to determine if asynchronous operations succeed because receiving nodes do not send status for operations back to the originating nodes.

In JBoss Data Grid, distributed and replicated caches are represented by the distributed-cache and replicated-cache elements.

Each of these elements contains a mode property, the value of which can be set to SYNC for synchronous, which is the default, or ASYNC for asynchronous communications.

<replicated-cache name="default"
                  statistics="true"
                  mode="ASYNC">
                 <!-- Additional configuration information here -->
</replicated-cache>

Replication mode can be synchronous or asynchronous depending on the problem being addressed.

In some instances, a cache configured for asynchronous replication or distribution may wait for responses, which is synchronous behavior. This occurs because caches behave synchronously when both state transfers and asynchronous modes are configured. This synchronous behavior is a prerequisite for state transfer to operate as expected.

Use one of the following to remedy this problem:

In replication mode, Red Hat JBoss Data Grid uses a replication queue to replicate changes across nodes based on the following:

The replication queue ensures that during replication, cache operations are transmitted in batches instead of individually. As a result, a lower number of replication messages are transmitted and fewer envelopes are used, resulting in improved JBoss Data Grid performance.

A disadvantage of using the replication queue is that the queue is periodically flushed based on the time or the queue size. Such flushing operations delay the realization of replication, distribution, or invalidation operations across cluster nodes. When the replication queue is disabled, the data is directly transmitted and therefore the data arrives at the cluster nodes faster.

A replication queue is used in conjunction with asynchronous mode.

When using the replication queue, do one of the following:

To implement either of these solutions, the replication queue must be in use in asynchronous mode. Asynchronous mode can be set by defining mode="ASYNC", as seen in the following example:

<replicated-cache name="asyncCache"
                  mode="ASYNC"
                  statistics="true"
              <!-- Additional configuration information here -->
</replicated-cache>

The replication queue allows requests to return to the client faster, therefore using the replication queue together with asynchronous marshalling does not present any significant advantages.

An Externalizer is a class that can:

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.

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:

<infinispan>
    <cache-container>
        <serialization>
            <advanced-externalizer class="Book$BookExternalizer" />
        </serialization>
    </cache-container>
</infinispan>

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:

For example, the following system properties enable deserialization for the com.foo.bar.spotprice.Price and com.foo.bar.spotprice.Currency classes as well as for any classes that match the .*SpotPrice.* expression:

-Dinfinispan.deserialization.whitelist.classes=com.foo.bar.spotprice.Price,com.foo.bar.spotprice.Currency
-Dinfinispan.deserialization.whitelist.regexps=.*SpotPrice.*

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

-Dinfinispan.deserialization.whitelist.regexps=.*

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

To use the JBoss Data Grid Infinispan Query via Maven, add the following dependencies:

<dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-embedded-query</artifactId>
    <version>${infinispan.version}</version>
</dependency>

Non-Maven users must install all of the infinispan-embedded-query.jar and infinispan-embedded.jar files from the JBoss Data Grid distribution.

The following directory providers are supported in Infinispan Query:

Storing the global index locally in Red Hat JBoss Data Grid’s Query Module allows each node to

The following example demonstrates an in-memory, RAM-based index store:

<local-cache name="indexesInMemory">
    <indexing index="LOCAL">
        <property name="default.directory_provider">ram</property>
    </indexing>
</local-cache>

To configure the storage of indexes, set the appropriate properties when enabling indexing in the JBoss Data Grid configuration.

This example shows a disk-based index store:

<local-cache name="indexesInInfinispan">
    <indexing index="ALL">
        <property name="default.directory_provider">filesystem</property>
        <property name="default.indexBase">/tmp/ispn_index</property>
    </indexing>
</local-cache>

In addition to the Lucene directory implementations, Red Hat JBoss Data Grid also ships with an infinispan-directory module.

The infinispan-directory allows Lucene to store indexes within the distributed data grid. This allows the indexes to be distributed, stored in-memory, and optionally written to disk using the cache store for durability.

Sharing the same index instance using the Infinispan Directory Provider introduces a write contention point, as only one instance can write on the same index at the same time.

InfinispanIndexManager provides a default back end that sends all updates to master node which later applies the updates to the index. In case of master node failure, the update can be lost, therefore keeping the cache and index non-synchronized. Non-default back ends are not supported.

<local-cache name="indexesInInfinispan">
    <indexing index="ALL">
        <property name="default.directory_provider">infinispan</property>
        <property name="default.indexmanager">org.infinispan.query.indexmanager.InfinispanIndexManager</property>
    </indexing>
</local-cache>

When using an indexed, clustered cache ensure that the caches containing the index data are also clustered, as described in Tuning Infinispan Directory.

In Remote Client-Server Mode, index configuration depends on the provider and its configuration. The indexing mode depends on the provider and whether or not it is local or distributed.

The following indexing modes are supported:

Index configuration in Remote Client-Server Mode is as follows:

<indexing index="LOCAL">
    <property name="default.directory_provider">ram</property>
    <!-- Additional configuration information here -->
</indexing>

<cache-container name="clustered" default-cache="repltestcache">
    [...]
    <replicated-cache name="LuceneIndexesMetadata" />
    <distributed-cache name="LuceneIndexesData" />
    <replicated-cache name="LuceneIndexesLocking" />
    [...]
</cache-container>

These caches are discussed in further detail at in the Red Hat JBoss Data Grid Developer Guide .

You can use the auto-config attribute to automatically configure indexing based on the cache type.

The following XML snippet shows a local cache configuration with the auto-config attribute:

<local-cache name="default">
   <indexing index="LOCAL" auto-config="true">
   </indexing>
</local-cache>

The auto-config attribute adds properties to the cache. You can tune the indexing behavior by re-defining the properties or adding new properties.

You can manually rebuild the Lucene index if required. However, you do not usually need to rebuild the index manually because JBoss Data Grid maintains the index during normal operation.

Rebuilding the index actually reconstructs the entire index from the data store, which requires JBoss Data Grid to process all data in the grid and can take a very long time to complete. You should only need to rebuild the Lucene index if:

Rebuilding the index may be performed by executing the Start operation on the MassIndexer MBean.

By default, each update is immediately flushed into the index. In order to achieve better throughput, the updates can be batched. However, this can result in a lag between the update and query — the query can see outdated data. If this is acceptable, you can use the Near-Realtime Index Manager by setting the following.

<property name="default.indexmanager">near-real-time</property>

Lucene directory uses three caches to store the index:

Configuration for these caches can be set explicitly, specifying the cache names as in the example below, and configuring those caches as usual. All of these caches must be clustered unless Infinispan Directory is used in local mode.

<distributed-cache name="indexedCache" >
    <indexing index="LOCAL">
        <property name="default.indexmanager">org.infinispan.query.indexmanager.InfinispanIndexManager</property>
        <property name="default.metadata_cachename">lucene_metadata_repl</property>
        <property name="default.data_cachename">lucene_data_dist</property>
        <property name="default.locking_cachename">lucene_locking_repl</property>
    </indexing>
</distributed-cache>

<replicated-cache name="lucene_metadata_repl" />

<distributed-cache name="lucene_data_dist" />

<replicated-cache name="lucene_locking_repl" />

The indexing properties in examples above apply for all indices - this is because we use the default. prefix for each property. To specify different configuration for each index, replace default with the index name. By default, this is the full class name of the indexed object, however you can override the index name in the @Indexed annotation.

The following enables a Hot Rod server using the hotrod socket binding.

<hotrod-connector socket-binding="hotrod"
		  cache-container="local" />

The connector creates a supporting topology cache with default settings. These settings can be tuned by adding the <topology-state-transfer /> child element to the connector as follows:

<hotrod-connector socket-binding="hotrod"
		  cache-container="local">
   <topology-state-transfer lazy-retrieval="false"
   			    lock-timeout="1000"
   			    replication-timeout="5000" />
</hotrod-connector>

The Hot Rod connector can be tuned with additional settings. See Configure Hot Rod Connectors for more information on how to configure the Hot Rod connector.

The following procedure describes the attributes used to configure the Hot Rod connector in Red Hat JBoss Data Grid’s Remote Client-Server Mode. Both the hotrod-connector and topology-state-transfer elements must be configured based on the following procedure.

<subsystem xmlns="urn:infinispan:server:endpoint:8.1">
	<hotrod-connector socket-binding="hotrod"
			  cache-container="local"
			  worker-threads="${VALUE}"
			  idle-timeout="${SECONDS}"
			  tcp-nodelay="${TRUE/FALSE}"
			  send-buffer-size="${VALUE}"
			  receive-buffer-size="${VALUE}" >
		<topology-state-transfer lock-timeout"="${MILLISECONDS}"
				 replication-timeout="${MILLISECONDS}"
				 external-host="${HOSTNAME}"
				 external-port="${PORT}"
				 lazy-retrieval="${TRUE/FALSE}"  />
	</hotrod-connector>
</subsystem>

The REST connector differs from the Hot Rod and Memcached connectors because it requires a web subsystem. Therefore configurations such as socket-binding, worker threads, timeouts, etc, must be performed on the web subsystem.

Once the REST interface has been enabled on the server it may be used normally for adding, removing, and retrieving data. For information on these processes refer to the JBoss Data Grid Developer Guide .

Use the following procedure to configure the rest-connector element in Red Hat JBoss Data Grid’s Remote Client-Server mode.

<subsystem xmlns="urn:infinispan:server:endpoint:8.1">
   <rest-connector cache-container="local"
                   context-path="${CONTEXT_PATH}"/>
</subsystem>

The rest-connector element specifies the configuration information for the REST connector.

The following enables a Memcached server using the memcached socket binding, and exposes the memcachedCache cache declared in the local container, using defaults for all other settings.

<memcached-connector socket-binding="memcached"
		     cache-container="local"/>

Due to the limitations in the Memcached protocol, only one cache can be exposed by a connector. To expose more than one cache, declare additional memcached-connectors on different socket-bindings. See Configure Memcached Connectors.

The following procedure describes the attributes used to configure the memcached connector within the connectors element in Red Hat JBoss Data Grid’s Remote Client-Server Mode.

<subsystem xmlns="urn:infinispan:server:endpoint:8.1">
<memcached-connector socket-binding="memcached"
                     cache-container="local"
                     worker-threads="${VALUE}"
                     idle-timeout="{SECONDS}"
                     tcp-nodelay="{TRUE/FALSE}"
                     send-buffer-size="{VALUE}"
                     receive-buffer-size="${VALUE}" />
</subsystem>

Optimistic locking allows multiple transactions to complete simultaneously by deferring lock acquisition to the transaction prepare time.

Optimistic mode assumes that multiple transactions can complete without conflict. It is ideal where there is little contention between multiple transactions running concurrently, as transactions can commit without waiting for other transaction locks to clear. With write-skew enabled, transactions in optimistic locking mode roll back if one or more conflicting modifications are made to the data before the transaction completes.

Pessimistic locking is also known as eager locking.

Pessimistic locking prevents more than one transaction to modify a value of a key by enforcing cluster-wide locks on each write operation. Locks are only released once the transaction is completed either through committing or being rolled back.

Pessimistic mode is used where a high contention on keys is occurring, resulting in inefficiencies and unexpected roll back operations.

Red Hat JBoss Data Grid includes explicit pessimistic locking and implicit pessimistic locking:

The following is an example of explicit pessimistic locking that depicts a transaction that runs on one of the cache nodes:

tx.begin()
cache.lock(K)
cache.put(K,V5)
tx.commit()

An example of implicit pessimistic locking using a transaction that runs on one of the cache nodes is as follows:

tx.begin()
cache.put(K,V)
cache.put(K2,V2)
cache.put(K,V5)
tx.commit()

To configure a locking mode in Red Hat JBoss Data Grid’s Remote Client-Server mode, use the transaction element as follows:

<transaction locking="{OPTIMISTIC/PESSIMISTIC}" />

In Red Hat JBoss Data Grid’s Library mode, the locking mode is set within the transaction element as follows:

<transaction transaction-manager-lookup="{TransactionManagerLookupClass}"
	     mode="{NONE, BATCH, NON_XA, NON_DURABLE_XA, FULL_XA}"
	     locking="{OPTIMISTIC,PESSIMISTIC}">
</transaction>

Set the locking value to OPTIMISTIC or PESSIMISTIC to configure the locking mode used for the transactional cache.

The LockManager component is responsible for locking an entry before a write process initiates. The LockManager uses a LockContainer to locate, hold and create locks. There are two types of LockContainers JBoss Data Grid uses internally and their choice is dependent on the useLockStriping setting. The first type offers support for lock striping while the second type supports one lock per entry.

See Also: Set Up Lock Striping

Red Hat JBoss Data Grid acquires remote locks lazily by default. The node running a transaction locally acquires the lock while other cluster nodes attempt to lock cache keys that are involved in a two phase prepare/commit phase. JBoss Data Grid can lock cache keys in a pessimistic manner either explicitly or implicitly.

Concurrency refers to the number of threads simultaneously interacting with the data grid. In Red Hat JBoss Data Grid, concurrency levels refer to the number of concurrent threads used within a lock container.

In JBoss Data Grid, concurrency levels determine the size of each striped lock container. Additionally, concurrency levels tune all related JDK ConcurrentHashMap based collections, such as those internal to DataContainers.

Cache stores can be configured in a chain. Cache read operations checks each cache store in the order configured until a valid non-null element of data has been located. Write operations affect all cache stores unless the ignoreModifications element has been set to "true" for a specific cache store.

The following example demonstrates cache store configuration using XML in JBoss Data Grid’s Library mode:

<persistence passivation="false">
   <file-store shared="false"
               preload="true"
               fetch-state="true"
               purge-startup="false"
               singleton="true"
               location="${java.io.tmpdir}" >
      <write-behind enabled="true"
             flush-lock-timeout="15000"
             thread-pool-size="5" />
   </singleFile>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

In Red Hat JBoss Data Grid’s Remote Client-Server mode, when the cache is preloaded from a cache store and eviction is disabled, read requests go to the memory. If the entry is not found in a memory during a read request, it accesses the cache store which may impact the read performance.

To avoid referring to the cache store when a key is not found in the memory, use the SKIP_CACHE_LOAD flag.

When the SKIP_CACHE_STORE Flag is used then the cache store will not be considered for the specified cache operations. This flag can be useful to place an entry in the cache without having it included in the configured cache store, along with determining if an entry is found within a cache without retrieving it from the associated cache store.

When the SKIP_SHARED_CACHE_STORE Flag is enabled then any shared cache store will not be considered for the specified cache operations. This flag can be useful to place an entry in the cache without having it included in the shared cache store, along with determining if an entry is found within a cache without retrieving it from the shared cache store.

A shared cache store is a cache store that is shared by multiple cache instances.

A shared cache store is useful when all instances in a cluster communicate with the same remote, shared database using the same JDBC settings. In such an instance, configuring a shared cache store prevents the unnecessary repeated write operations that occur when various cache instances attempt to write the same data to the cache store.

When used in conjunction with a shared cache store, Red Hat JBoss Data Grid’s invalidation mode causes remote caches to see the shared cache store to retrieve modified data.

The benefits of using invalidation mode in conjunction with shared cache stores include the following:

In Red Hat JBoss Data Grid, a cache store can be used to enforce the passivation of entries and to activate eviction in a cache. Whether passivation mode or activation mode are used, the configured cache store both reads from and writes to the data store.

When passivation is disabled in JBoss Data Grid, after the modification, addition or removal of an element is carried out the cache store steps in to persist the changes in the store.

It is not necessary to register an application cache store for an isolated deployment. This is not a requirement in Red Hat JBoss Data Grid because lazy deserialization is used to work around this problem.

In Red Hat JBoss Data Grid, all JDBC cache stores rely on a ConnectionFactory implementation to obtain a database connection. This process is also known as connection management or pooling.

A connection factory can be specified using the ConnectionFactoryClass configuration attribute. JBoss Data Grid includes the following ConnectionFactory implementations:

ManagedConnectionFactory is a connection factory that is ideal for use within managed environments such as application servers. This connection factory can explore a configured location in the JNDI tree and delegate connection management to the DataSource.

SimpleConnectionFactory is a connection factory that creates database connections on a per invocation basis. This connection factory is not designed for use in a production environment.

PooledConnectionFactory is a connection factory based on C3P0, and is typically recommended for standalone deployments as opposed to deployments utilizing a servlet container, such as JBoss EAP. This connection factory functions by allowing the user to define a set of parameters which may be used for all DataSource instances generated by the factory.

Red Hat JBoss Data Grid includes one file system based cache store: the SingleFileCacheStore.

The SingleFileCacheStore is a simple file system based implementation and a replacement to the older file system based cache store: the FileCacheStore.

SingleFileCacheStore stores all key/value pairs and their corresponding metadata information in a single file. To speed up data location, it also keeps all keys and the positions of their values and metadata in memory. Hence, using the single file cache store slightly increases the memory required, depending on the key size and the amount of keys stored. Hence SingleFileCacheStore is not recommended for use cases where the keys are too big.

To reduce memory consumption, the size of the cache store can be set to a fixed number of entries to store in the file; however, this works only when JBoss Data Grid is used as a cache. When JBoss Data Grid is used this way, data which is not present in the cache can be recomputed or re-retrieved from the authoritative data store and stored in the JBoss Data Grid cache. This limitation exists so that once the maximum number of entries is reached older data in the cache store is removed. If JBoss Data Grid were used as an authoritative data store in this scenario it would lead to potential data loss.

Due to its limitations, SingleFileCacheStore can be used in a limited capacity in production environments. It can not be used on shared file system (such as NFS and Windows shares) due to a lack of proper file locking, resulting in data corruption. Furthermore, file systems are not inherently transactional, resulting in file writing failures during the commit phase if the cache is used in a transactional context.

The following is an example of a Single File Store configuration for Red Hat JBoss Data Grid’s Remote Client-Server mode:

<local-cache name="default" statistics="true">
    <file-store name="myFileStore"
                passivation="true"
                purge="true"
                relative-to="{PATH}"
                path="{DIRECTORY}"
                max-entries="10000"
                fetch-state="true"
                preload="false" />
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

In Red Hat JBoss Grid’s Library mode, configure a Single File Cache Store as follows:.

<local-cache name="writeThroughToFile">
      <persistence passivation="false">
         <file-store fetch-state="true"
                      purge="false"
                      shared="false"
                      preload="false"
                      location="/tmp/Another-FileCacheStore-Location"
                      max-entries="100">
            <write-behind enabled="true"
    	           threadPoolSize="500"
    	           flush-lock-timeout="1"
	           modification-queue-size="1024"
	           shutdown-timeout="25000"/>
        </singleFile>
      </persistence>
 </local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

Red Hat JBoss Data Grid 7 stores data in a different format than previous versions of JBoss Data Grid. As a result, the newer version of JBoss Data Grid cannot read data stored by older versions. Use rolling upgrades to upgrade persisted data from the format used by the old JBoss Data Grid to the new format. Additionally, the newer version of JBoss Data Grid also stores persistence configuration information in a different location.

Rolling upgrades is the process by which a JBoss Data Grid installation is upgraded without a service shutdown. For JBoss Data Grid servers, this procedure refers to the server side components. The upgrade can be due to either hardware or software change, such as upgrading JBoss Data Grid.

Rolling upgrades are only available in JBoss Data Grid’s Remote Client-Server mode.

LevelDB is a key-value storage engine that provides an ordered mapping from string keys to string values.

The LevelDB Cache Store uses two filesystem directories. Each directory is configured for a LevelDB database. One directory stores the non-expired data and the second directory stores the keys pending to be purged permanently.

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

The following is a sample XML configuration of LevelDB Cache Store:

<local-cache name="vehicleCache">
      <persistence passivation="false">
          <leveldb-store xmlns="urn:infinispan:config:store:leveldb:8.0
                        relative-to="/path/to/leveldb/data"
                        shared="false"
                        preload="true"/>
      </persistence>
   </local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

Use the following procedure to set up a new LevelDB cache store using the JBoss Operations Network.

Red Hat JBoss Data Grid offers several cache stores for use with common data storage formats. JDBC based cache stores are used with any cache store that exposes a JDBC driver. JBoss Data Grid offers the following JDBC based cache stores depending on the key to be persisted:

The RemoteCacheStore is an implementation of the cache loader that stores data in a remote Red Hat JBoss Data Grid cluster. The RemoteCacheStore uses the Hot Rod client-server architecture to communicate with the remote cluster.

For remote cache stores, Hot Rod provides load balancing, fault tolerance and the ability to fine tune the connection between the RemoteCacheStore and the cluster.

The following is a sample remote cache store configuration for Red Hat JBoss Data Grid’s Remote Client-Server mode:

<remote-store cache="default"
              socket-timeout="60000"
              tcp-no-delay="true"
              hotrod-wrapping="true">
	<remote-server outbound-socket-binding="remote-store-hotrod-server" />
</remote-store>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Remote Client-Server Mode).

The following is a sample remote cache store configuration for Red Hat JBoss Data Grid’s Library mode:

<persistence passivation="false">
	<remote-store xmlns="urn:infinispan:config:store:remote:8.0"
	             cache="default"
		     fetch-state="false"
		     shared="true"
		     preload="false"
		     purge="false"
		     tcp-no-delay="true"
		     key-size-estimate="62"
		     value-size-estimate="512"
		     force-return-values="false">
		<remote-server host="127.0.0.1"
			port="1971" />
		<connectionPool max-active="99"
				max-idle="97"
				max-total="98" />
	</remote-store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

The Hot Rod server used by the remote cache store is defined using the outbound-socket-binding element in a standalone.xml file.

An example of this configuration in the standalone.xml file is as follows:

<server>
    <!-- Additional configuration elements here -->
    <socket-binding-group name="standard-sockets"
    			  default-interface="public"
    			  port-offset="${jboss.socket.binding.port-offset:0}">
        <!-- Additional configuration elements here -->
        <outbound-socket-binding name="remote-store-hotrod-server">
            <remote-destination host="remote-host"
                                port="11222"/>
        </outbound-socket-binding>
    </socket-binding-group>
</server>

The JPA (Java Persistence API) Cache Store stores cache entries in the database using a formal schema, which allows other applications to read the persisted data and load data provided by other applications into Red Hat JBoss Data Grid. The database should not be used by the other applications concurrently with JBoss Data Grid.

To configure JPA Cache Stores using XML in Red Hat JBoss Data Grid, add the following configuration to the infinispan.xml file:

<local-cache name="users">
  <!-- Insert additional configuration elements here -->
	<persistence passivation="false">
            <jpa-store xmlns="urn:infinispan:config:store:jpa:8.0"
                      shared="true"
                      preload="true"
                      persistence-unit="MyPersistenceUnit"
                      entity-class="org.infinispan.loaders.jpa.entity.User" />
	</persistence>
</local-cache>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

When storeMetadata is set to true (default value), meta information about the entries such as expiration, creation and modification timestamps, and versioning is stored in the database. JBoss Data Grid stores the metadata in an additional table named _ispn_metadata_ because the entity table has a fixed layout that cannot accommodate the metadata.

The structure of this table depends on the database in use. Enable the automatic creation of this table using the same database as the test environment and then transfer the structure to the production database.

As outlined, metadata is always stored in a new table. If metadata information collection and storage is not required, set the storeMetadata attribute to false in the JPA Store configuration.

Red Hat JBoss Data Grid JPA Cache Store implementations are deployed normally for all supported containers, except Red Hat JBoss Enterprise Application Platform. The JBoss Data Grid JBoss EAP modules contain the JPA cache store and related libraries such as Hibernate. As a result, the relevant libraries are not packaged inside the application, but instead the application refers to the libraries in the JBoss EAP modules that have them installed.

These modules are not required for containers other than JBoss EAP. As a result, all the relevant libraries are packaged in the application’s WAR/EAR file, such as with the following Maven dependency:

<dependency>
    <groupId>org.infinispan</groupId>
    <artifactId>infinispan-cachestore-jpa</artifactId>
    <version>{FullInfinispanVersion}</version>
</dependency>

Red Hat JBoss Data Grid allows Apache Cassandra to function as a Cache Store, leveraging their distributed database architecture to provide a virtually unlimited, horizontally scalable persistent store for cache entries.

In order to use the Cassandra Cache Store an appropriate keyspace must first be created on the Cassandra database. This may either be performed automatically or by enabling the auto-create-keyspace parameter in the cache store configuration. A sample keyspace creation is demonstrated below:

CREATE KEYSPACE IF NOT EXISTS Infinispan WITH replication = {'class':'SimpleStrategy', 'replication_factor':1};
CREATE TABLE Infinispan.InfinispanEntries (key blob PRIMARY KEY, value blob, metadata blob);

The Cassandra Cache Store is included based on the downloaded distribution. The following indicates where this is located, and steps to enable it if required:

In Remote Client-Server mode the Cassandra Cache Store is defined by using the class org.infinispan.persistence.cassandra.CassandraStore and defining the properties individually within the store.

The following configuration snippet provides an example on how to define a Cassandra Cache Store inside of an xml file:

<local-cache name="cassandracache">
    <locking acquire-timeout="30000" concurrency-level="1000" striping="false"/>
    <transaction mode="NONE"/>
    <store name="cassstore1"
           class="org.infinispan.persistence.cassandra.CassandraStore"
           shared="true"
           passivation="false">
        <property name="autoCreateKeyspace">true</property>
        <property name="keyspace">store1</property>
        <property name="entryTable">entries1</property>
        <property name="consistencyLevel">LOCAL_ONE</property>
        <property name="serialConsistencyLevel">SERIAL</property>
        <property name="servers">127.0.0.1[9042],127.0.0.1[9041]</property>
        <property name="connectionPool.heartbeatIntervalSeconds">30</property>
        <property name="connectionPool.idleTimeoutSeconds">120</property>
        <property name="connectionPool.poolTimeoutMillis">5</property>
    </store>
</local-cache>

In Library Mode the Cassandra Cache Store may be configured using two different methods:

When defining a backing Cassandra instance in Library Mode one or more cassandra-server elements may be specified in the configuration. Each of the elements has the following properties:

The following properties may be configured on the Cassandra Cache Store:

A connection-pool may also be defined with the following elements:

Custom cache stores are a customized implementation of Red Hat JBoss Data Grid cache stores.

In order to create a custom cache store (or loader), implement all or a subset of the following interfaces based on the need:

See Cache Loaders and Cache Writers for individual functions of the interfaces.

To migrate the existing cache store to the new API or to write a new store implementation, use SingleFileStore as an example. To view the SingleFileStore example code, download the JBoss Data Grid source code.

Use the following procedure to download SingleFileStore example code from the Customer Portal:

An easy way to get started with developing a Custom Cache Store is to use the Maven archetype; creating an archetype will generate a new Maven project with the correct directory layout and sample code.

The following is a sample configuration for a custom cache store in Red Hat JBoss Data Grid’s Library mode:

<persistence>
	<store class="org.infinispan.custom.CustomCacheStore"
	       preload="true"
	       shared="true">
	       <property name="customStoreProperty">10</property>
	</store>
</persistence>

For details about the elements and parameters used in this sample configuration, see Cache Store Configuration Details (Library Mode).

To ensure that a single copy of an entry remains, either in memory or in a cache store, use passivation in conjunction with eviction.

The primary reason to use passivation instead of a normal cache store is that updating entries require less resources when passivation is in use. This is because passivation does not require an update to the cache store.

If the eviction policy caused the eviction of an entry from the cache while passivation is enabled, the following occur as a result:

When an attempt to retrieve an evicted entry is made, the entry is lazily loaded into memory from the cache loader. After the entry and its children are loaded a notification regarding the entry’s activation is sent to the cache listeners.

With passivation disabled, when an element is modified, added, or removed, the modification is persisted in the backend store via the cache loader. There is no direct relationship between eviction and cache loading. When eviction is not in use, the persistent store is effectively a copy of what’s in memory. If eviction is in use, the persistent store is effectively a superset of what’s in memory (i.e. it includes entries that have been evicted from memory).

When passivation is enabled and the cache store is unshared, there is a direct relationship between eviction and the cache loader. Writes to the persistent store via the cache loader only occur as part of the eviction process. Data is deleted from the persistent store when the application reads it back into memory. In this case, the data in memory and data in the persistent store are two subsets of the total information set, with no intersection between the subsets. With a shared store, entries which have been passivated in the past will continue to exist in the store, although they may have a stale value if this has been overwritten in memory.

The following example indicates the state of the memory and the persistent store during eviction operations in three different configurations: passivation off, passivation on with a cache store with shared off, and passivation on with a cache store with shared on.

The Write-Through (or Synchronous) mode in Red Hat JBoss Data Grid ensures that when clients update a cache entry (usually via a Cache.put() invocation), the call does not return until JBoss Data Grid has located and updated the underlying cache store. This feature allows updates to the cache store to be concluded within the client thread boundaries.

No specific configuration operations are required to configure a Write-Through or synchronous cache store. All cache stores are Write-Through or synchronous unless explicitly marked as Write-Behind or asynchronous. The following procedure demonstrates a sample configuration file of a Write-Through unshared local file cache store.

<local-cache name="persistentCache">
		<persistence>
		    <file-store fetch-state="true"
			    purge="false"
			    shared="false"
			    location="${java.io.tmpdir}"/>
		</persistence>
</local-cache>

In Red Hat JBoss Data Grid’s Write-Behind (Asynchronous) mode, cache updates are asynchronously written to the cache store. Asynchronous updates ensure that cache store updates are carried out by a thread different from the client thread interacting with the cache.

One of the foremost advantages of the Write-Behind mode is that the cache operation performance is not affected by the underlying store update. However, because of the asynchronous updates, for a brief period the cache store contains stale data compared to the cache.

In the Unscheduled Write-Behind Strategy mode, Red Hat JBoss Enterprise Data Grid attempts to store changes as quickly as possible by applying pending changes in parallel. This results in multiple threads waiting for modifications to conclude. Once these modifications are concluded, the threads become available and the modifications are applied to the underlying cache store.

This strategy is ideal for cache stores with low latency and low operational costs. An example of this is a local unshared file based cache store in which the cache store is local to the cache itself. Using this strategy the period of time where an inconsistency exists between the contents of the cache and the contents of the cache store is reduced to the shortest possible interval.

To set the write-behind strategy in Red Hat JBoss Data Grid’s Remote Client-Server mode, add the write-behind element to the target cache store configuration as follows:

<file-store passivation="false"
            path="${PATH}"
            purge="true"
            shared="false">
    <write-behind modification-queue-size="1024"
                  shutdown-timeout="25000"
                  flush-lock-timeout="15000"
                  thread-pool-size="5" />
</file-store>

The write-behind element uses the following configuration parameters:

To enable the write-behind strategy of the cache entries to a store, add the async element to the store configuration as follows:

<persistence>
    <singleFile location="${LOCATION}">
        <async enabled="true"
                    modificationQueueSize="1024"
                    shutdownTimeout="25000"
                    flushLockTimeout="15000"
                    threadPoolSize="5"/>
    </singleFile>
</persistence>

An MBean represents a manageable resource such as a service, component, device or an application.

Red Hat JBoss Data Grid provides MBeans that monitor and manage multiple aspects. For example, MBeans that provide statistics on the transport layer are provided. If a JBoss Data Grid server is configured with JMX statistics, an MBean that provides information such as the hostname, port, bytes read, bytes written and the number of worker threads exists at the following location:

jboss.infinispan:type=Server,name=<Memcached|Hotrod>,component=Transport

MBeans are available under two JMX domains:

Only the MBeans under jboss.infinispan should be used for Red Hat JBoss Data Grid, as the ones under jboss.as are for Red Hat JBoss Enterprise Application Platform.

When JMX reporting is enabled at either the Cache Manager or Cache level, use a standard JMX GUI such as JConsole or VisualVM to connect to a Java Virtual Machine running Red Hat JBoss Data Grid. When connected, the following MBeans are available:

As an example, the cache store JMX component MBean for a default cache configured for synchronous distribution would be named as follows:

jboss.infinispan:type=Cache,name="default(dist_sync)", manager="default",component=CacheStore

Each cache and cache manager name is within quotation marks to prevent the use of unsupported characters in these user-defined names.

The default location where all the MBeans used are registered is the standard JVM MBeanServer platform. Users can set up an alternative MBeanServer instance as well. Implement the MBeanServerLookup interface to ensure that the getMBeanServer() method returns the desired (non default) MBeanServer.

To set up a non default location to register your MBeans, create the implementation and then configure Red Hat JBoss Data Grid with the fully qualified name of the class. An example is as follows:

<globalJmxStatistics enabled="true" mBeanServerLookup="com.acme.MyMBeanServerLookup"/>

In order to install JBoss Operations Network in Red Hat JBoss Data Grid, the following is required:

Use the following procedure to download Red Hat JBoss Operations Network (JON) from the Customer Portal:

A port value must be provided to allow Red Hat JBoss Data Grid instances to be located. The value itself can be any available port.

Provide unique (and available) remote JMX ports to run multiple JBoss Data Grid instances on a single machine. A locally running JBoss Operations Network agent can discover each instance using the remote port values.

In Red Hat JBoss Data Grid’s Remote Client-Server mode, the JBoss Operations Network plug-in is used to

In Remote Client-Server mode, the JBoss Operations Network plug-in uses JBoss Enterprise Application Platform’s management protocol to obtain metrics and perform operations on the JBoss Data Grid server.

The following procedure details how to install the JBoss Operations Network plug-ins for Red Hat JBoss Data Grid’s Remote Client-Server mode.

JBoss Operation Network can now discover running JBoss Data Grid servers.

Use the following steps to create a new cache using JBoss Operations Network (JON) for Remote Client-Server mode.

In Red Hat JBoss Data Grid’s Library mode, the JBoss Operations Network plug-in is used to

In Library mode, the JBoss Operations Network plug-in uses JMX to obtain metrics and perform operations on an application using the JBoss Data Grid library.

Use the following procedure to install the JBoss Operations Network plug-in for Red Hat JBoss Data Grid’s Library mode.

Managing Red Hat JBoss Data Grid instances requires exposing significant amounts of relevant statistical information. This information allows administrators to get a clear view of each JBoss Data Grid node’s state. A single installation can comprise of tens or hundreds of JBoss Data Grid nodes and it is important to provide this information in a clear and concise manner. JBoss Operations Network is one example of a tool that provides runtime visibility. Other tools, such as JConsole can be used where JMX is enabled.

Caches that have been configured with a REST interface have access to Red Hat JBoss Data Grid using RESTful HTTP access.

The RESTful service only requires a HTTP client library, eliminating the need for tightly coupled client libraries and bindings. For more information about how to retrieve data using the REST interface, refer to the JBoss Data Grid Developer Guide .

HTTP put() and post() methods place data in the cache, and the URL used determines the cache name and key(s) used. The data is the value placed into the cache, and is placed in the body of the request.

A Content-Type header must be set for these methods. GET and HEAD methods are used for data retrieval while other headers control cache settings and behavior.

Specific Map methods, such as size(), values(), keySet() and entrySet(), can be used with certain limitations with Red Hat JBoss Data Grid as they are unreliable. These methods do not acquire locks (global or local) and concurrent modification, additions and removals are excluded from consideration in these calls.

The listed methods have a significant impact on performance. As a result, it is recommended that these methods are used for informational and debugging purposes only.

In this mode of operation, the result returned by the size() method is affected by the flags org.infinispan.context.Flag#CACHE_MODE_LOCAL, to force it to return the number of entries present on the local node, and org.infinispan.context.Flag#SKIP_CACHE_LOAD, to ignore any passivated entries. Either of these flags may be used to increase performance of this method, at the cost of not returning a count of all elements across the entire cluster.

The Administration Console is started automatically when JBoss Data Grid is running in Remote Client-Server Mode. A management user must be added to the server instance, which will then be used to access the web console.

In order to use the JBoss Data Grid Administration Console, a new management user must be created. To add a new user, execute the add-user.sh utility script within the bin folder of your JBoss Data Grid Server installation and enter the requested information.

The following procedure outlines the steps to add a new management user:

Once the JBoss Data Grid server is running, in either domain or standalone mode, the JBoss Data Grid Administration Console may be accessed at the following login page:

http://${jboss.bind.address.management}:9990/console/index.html

Figure 25.1. JBoss Data Grid Administration Console Login Screen

Enter the user credentials to log in. After logging in, the cache container view is displayed.

The Dashboard view is split into 3 tabs namely:

The first default view after logging in is the Cache Container list. A Cache Container is the primary mechanism for treating a cache instance and is used as a starting point for using a cache itself.

Cache centric view presents the list of configured caches. It is used for viewing and adding caches to clusters, adding and adjusting new cache configurations, adding and configuring endpoints and other cache related administrative tasks.

Figure 25.2. Cache Containers View

In this instance, there is one cache container with the name clustered with two caches deployed on the cluster group with UDP transport and three Endpoints attached to it. There are no remote sites configured for this cache container.

The Cluster tab presents the summary of the clusters along with the current status, number of hosts and number of nodes.

Figure 25.3. Clusters View

The JBoss Data Grid Administration Console displays the cluster wide events such as local rebalancing, cluster start and stop, cluster-split and cluster-merge events in a consolidated section. To view the detailed status events, navigate to the Status Events tab from the Dashboard.

Figure 25.4. Status Events View

The status events are displayed with the associated timestamp and the event description.

To add a new cache, follow these steps:

The JBoss Data Grid Administration Console allows administrators to edit the configuration of an existing cache.

The following procedure outlines the steps to edit a cache configuration:

The JBoss Data Grid Administration Console allows administrators to view all the cache statistics including the average time for reads, average times for writes, total number of entries, total number of reads, total number of failed reads and total number of writes.

To view the cache statistics, follow these steps:

To view on which node a cache resides, click on the Nodes tab next to the General Status tab on the cache statistics page.

Figure 25.21. General Status Tab

The name of the Node(s) is displayed along with the read-write statistics.

Figure 25.22. Cache Node Labels

The following procedure outlines the steps to disable a cache:

The following procedure outlines the steps to enable a cache:

The JBoss Data Grid Administration Console allows administrators to remove all the entries from a cache and the cache stores through the cache Clear operation. The console also provides the Flush operation to store the entries from the cache memory to the cache store. These entries are not removed from the cache memory, as during a Clear operation.

Flushing a Cache

To flush a cache, follow these steps:

Clearing a Cache

To clear a cache, follow these steps:

The JBoss Data Grid Administration Console allows administrators to start a server script job on the JBoss Data Grid cluster.

The JBoss Data Grid Administration Console allows users to view and set Cache Container level settings such as transport, thread pools, security, cache templates, deployment of remote Executables/Scripts. Each cache container is associated with a cluster.

The following procedure outlines the steps to aceess the Cache Container Configuration settings:

The Cache Container Configuration interface is displayed.

Figure 25.49. Cache Container Configuration

A Protocol Buffer Schema is defined in the Cache Container Configuration interface.

The following procedure outlines the steps to define a protobuf schema:

To access the Transport setting, click on the Transport tab in the Cache Container Configuration interface. Enter the Transport settings and click Save .

Figure 25.52. Transport Setting

A dialog box will prompt to restart the server due to configuration changes. Restart to apply the changes.

Figure 25.53. Restart Confirmation

To define thread pools for different cache related operations, click on the Thread Pools tab in the Cache Container Configuration interface.

The JBoss Data Grid Administration Console allows administrators to set Thread Pool values for the following cache level operations:

Async Operations

Figure 25.54. Async Operations

The currently set value for each parameter is set by the console. Hover the cursor over the information icon to view the parameter description in form of a tooltip. To change a thread pool value, enter the new value in the parameter field and click Save . A server restart is needed after every change of values.

Expiration

For Expiration settings, the user can set values for the following parameters:

Figure 25.55. Expiration Values

Listener

For Listener settings, the user can set values for the following parameters:

Figure 25.56. Listener Values

Persistence

For Persistence settings, the user can set values for the following parameters:

Figure 25.57. Persistence Values

Remote Commands

For Remote Commands settings, the user can set values for the following parameters:

Figure 25.58. Remote Commands

Replication Queue

For Replication Queue settings, the user can set values for the following parameters:

Figure 25.59. Replication Queue Values

State Transfer

For Listener settings, the user can set values for the following parameters:

Figure 25.60. State Transfer Values

Transport

For Transport settings, the user can set values for the following parameters:

Figure 25.61. Transport Values

The following procedure outlines the steps to add a new security role:

The Templates tab in the Cache Container Configuration interface lists all the configured and available cache templates.

Figure 25.66. Cache Templates View

The following procedure outlines the steps to create a new Cache configuration template :

Clusters centric view allows to view the nodes created for each server group and the list of deployed servers can be viewed. In Clusters view, you can add new nodes to the cluster group and view performance metrics of the particular nodes.

To access the Clusters view, navigate to the Clusters tab from the Dashboard and click on the name of the cluster.

Figure 25.69. Nodes View

The total number of server nodes on the JBoss Data Grid cluster should ideally match the number of nodes shown in the JBoss Data Grid Administration Console. If in case, due to some reason, the expected nodes in the console do not match with the exact number of nodes on the JBoss Data Grid physical cluster, the console issues a mismatch warning by displaying the number of nodes detected and the number of expected nodes. Knowing the expected number of server nodes helps in handling Network Partitions.

If nodes mismatch occurs, it can be viewed in the clusters view, above the list of nodes as a warning. To access the Clusters view, navigate to the Clusters tab from the Dashboard and click on the name of the cluster.

In the following screen, the Console alerts the user in the form of a warning. The expected number of server nodes are 5 but only 3 are detected by the console.

Figure 25.70. Cluster Nodes Mismatch

The Red Hat JBoss Data Grid Administration Console allows the user to enable and disable cluster rebalancing at the cache container and cache levels.

The following procedure outlines the steps to enable and disable cluster rebalancing at a cache container level :

Rebalancing is successfully enabled.

The following procedure outlines the steps to enable and disable cluster rebalancing at a cache level :

The rebalancing for the cache is successfully enabled.

The JBoss Data Grid Administration Console alerts the user with a visual warning when the cluster changes state to DEGRADED.

The assumed causes for a DEGRADED cluster are occurrence of a network partition, unreachable node(s) or unexpected extra nodes.

The visual warning is displayed in the Clusters view.

To access the Clusters view, navigate to the Clusters tab from the Dashboard and click on the name of the cluster.

In the following screen, the visual warning DEGRADED is displayed next to the cluster name JDG Cluster #1.

Figure 25.71. Network Partition Warning

This visual warning for a DEGRADED cluster is shown at Cluster, Cache Container, and Cache levels of the console.

The JBoss Data Grid Console displays the cluster wide events such as cluster-split and cluster-merge events in a consolidated section.

Along with the cluster events, the console displays the timestamp of the associated event. Cluster events can be viewed in the Cache containers page, the Clusters view page and also in the Status Events tab of the Dashboard.

To view cluster events on the cache containers page, navigate to the default cache containers view which is the default landing interface after logging into the console. The Cluster events are displayed at the right hand side in a consolidated section under the title Latest Grid Events

To view the cluster events on the Clusters view page, navigate to the Clusters view by clicking on the Clusters tab. The Cluster events are displayed at the right hand side in a consolidated section under the title Latest status Events

The JBoss Data Grid Administration Console allows administrators to configure new nodes.

The following procedure outlines the steps to add a new Node: