cache.xml (Declarative Cache Configuration File)

The declarations in the cache XML file correspond to APIs in the com.gemstone.gemfire.cache package. The cache XML file is generally referred to as cache.xml, although you can give it any name.

cache.xml Requirements

The cache.xml file has these requirements:
  • The contents must conform to the XML definition in dtd/cache6_6.dtd of your GemFire installation.
  • The file must include a DOCTYPE of one of the following forms:
    • Server or peer cache:
      <!DOCTYPE cache PUBLIC 
      "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.6//EN" 
      "http://www.gemstone.com/dtd/cache6_6.dtd">
    • Client cache:
      <!DOCTYPE client-cache PUBLIC 
      "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.6//EN" 
      "http://www.gemstone.com/dtd/cache6_6.dtd">
  • Any class name specified in the file must have a public zero-argument constructor and must implement the com.gemstone.gemfire.cache.Declarable interface. Parameters declared in the XML for the class are passed to the class’s init method.

Variables in cache.xml

You can use variables in the cache.xml to customize your settings without modifying the XML file.

Set your variables in Java system properties when you start your cacheserver or application process.

Example cache.xml with variables and cacheserver start command that sets the variables:
<!DOCTYPE cache PUBLIC
  "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.6//EN"
  "http://www.gemstone.com/dtd/cache6_6.dtd">
<cache>
  <cache-server port="${PORT}" max-connections="${MAXCNXS}"/>
  <region name="root">
    <region-attributes refid="REPLICATE"/>
  </region>
</cache>
cacheserver start -J-DPORT=30333 -J-DMAXCNXS=77

<cache> attributes

These are the attributes of the cache.xml <cache> and <client-cache> elements. Some apply only to the <cache> element.

Attribute Definition Default
copy-on-read Boolean indicating whether entry value retrieval methods return direct references to the entry value objects in the cache (false) or copies of the objects (true). false
is-server Applies only to <cache> element.

Boolean indicating whether this member is a cache server.

false
lock-timeout Applies only to <cache> element.

The timeout, in seconds, for implicit object lock requests. This setting affects automatic locking only, and does not apply to manual locking. If a lock request does not return before the specified timeout period, it is cancelled and returns with a failure.

60
lock-lease Applies only to <cache> element.

The timeout, in seconds, for implicit and explicit object lock leases. This affects both automatic locking and manual locking. Once a lock is obtained, it can remain in force for the lock lease time period before being automatically cleared by the system.

120
message-sync-interval Applies only to <cache> element.

Used for client subscription queue synchronization when this member acts as a server to clients and server redundancy is used. Sets the frequency (in seconds) at which the primary server sends messages to its secondary servers to remove queued events that have already been processed by the clients.

1
search-timeout Applies only to <cache> element.

How many seconds a netSearch operation can wait for data before timing out. You may want to change this based on your knowledge of the network load or other factors.

300

<cache> elements

These are the subelements of the cache.xml <cache> and <client-cache> elements. Some apply only to the <cache> element. By default, these subelements are not defined.

Element Definition
cache-server Applies only to <cache> element.

Configures the cache to serve region data to clients in a client/server caching system. This element indicates the port the server listens on for client communication.

cache-transaction-manager Provides the means for defining transaction listeners.
disk-store Defines a pool of one or more disk stores, which can be used by regions, client subscription queues, and WAN gateway queues. The cache default disk store, named "DEFAULT", is used when disk is used but no disk store is named.
dynamic-region-factory Configures the cache for the dynamic region management. When this is enabled, this cache can distribute dynamic region creations and destructions to other caches with a factory defined and can receive modifications to dynamic regions from other caches.
function-service Configures the behavior of the function execution service.
gateway-hub Applies only to <cache> element.

Specifies that this process is a hub of a multi-site (WAN) gateway.

jndi-bindings Specifies the binding for a data-source used in transaction management.
initializer Used to specify a callback class (and optionally its parameters) that will be run after the cache is initialized. This element can be specified for both server and client caches.
pool For client caches. Defines a client's server pool used to communicate with servers running in a different distributed system.
region Defines a region in the cache.
region-attributes Specifies a region attributes template that can be named (by id) and referenced (by refid) later in the cache.xml and through the API.
resource-manager A memory monitor that tracks cache size as a percentage of total tenured heap and controls size by restricting access to the cache and prompting eviction of old entries from the cache. Used in conjunction with settings for JVM memory and Java garbage collection.
serialization-registration Set of serializer or instantiator tags to register customer DataSerializer extensions or DataSerializable implementations respectively.

Sub-elements and Attributes of pdx Elements

The following tables list the sub-elements and attributes of the <pdx> element in cache.xml. <pdx> itself can be a sub-element of <cache> or <client-cache>. You can also configure these settings using API methods found in CacheFactory or ClientCacheFactory.
Sub-element Description
pdx-serializer Allows you to configure the PdxSerializer for this GemFire member.
Attribute Description
read-serialized Set it to true if you want PDX deserialization to produce a PdxInstance instead of an instance of the domain class.
ignore-unread-fields Set it to true if you do not want unread PDX fields to be preserved during deserialization. You can use this option to save memory. Set to true only in members that are only reading data from the cache.
persistent Set to true if you are using persistent regions or WAN gateways. This causes the PDX type information to be written to disk.
disk-store-name If using persistence, this attribute allows you to configure the disk store that the PDX type data will be stored in. By default, the default disk store is used.