<client-cache> Element Reference

This topic documents all of the cache.xml elements that you use to configureVMware Tanzu GemFire clients. All elements are sub-elements of the <client-cache> element.

For Tanzu GemFire server configuration, see <cache> Element Reference.

API: org.apache.geode.cache.client.ClientCacheFactory and PoolFactory interfaces.

client-cache Attributes

client-cache Attributes

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`

Example:

<client-cache>
  <pool
    name="client"
    subscription-enabled="true">
    <locator host="localhost" port="41111"/>
  </pool>
  <region-attributes
    id="clientAttributes"
    pool-name="client"
    refid="CACHING_PROXY"/>
  <region name="root">
    <region-attributes scope="local"/>
    <region name="cs_region">
      <region-attributes refid="clientAttributes"/>
    </region>
  </region>
</client-cache>

cache-transaction-manager

<cache-transaction-manager>

Specifies a transaction listener.

API: CacheTransactionManager

Example:

<client-cache search-timeout="60">
  <cache-transaction-manager>
    <transaction-listener>
      <class-name>com.company.data.MyTransactionListener</class-name>
      <parameter name="URL">
        <string>jdbc:cloudscape:rmi:MyData</string>
      </parameter>
    </transaction-listener>
    <transaction-listener> ... </transaction-listener>
    <transaction-writer>
      <class-name>com.company.data.MyTransactionWriter</class-name>
      <parameter name="URL">
        <string>jdbc:cloudscape:rmi:MyData</string>
      </parameter>
    </transaction-writer>
  </cache-transaction-manager> ...
</client-cache>

transaction-listener

<transaction-listener>

When a transaction ends, its thread calls the TransactionListener to perform the appropriate follow-up for successful commits, failed commits, or voluntary rollbacks.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

transaction-writer

<transaction-writer>

When you commit a transaction, a TransactionWriter can perform additional tasks, including cancelling the transaction.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

pool

<pool>

Use for client caches. Defines a client’s server pool used to communicate with servers running in a different cluster.

API: org.apache.geode.cache.client.PoolFactory

<pool> Attributes

Attribute	Description	Default
free-connection-timeout	Amount of time, in milliseconds, a thread will wait to get a pool connection before timing out with an exception. This timeout keeps threads from waiting indefinitely when a pool's `max-connections` has been reached and all connections in the pool are in use by other threads. Takes effect only when `pr-single-hop-enabled` is `false`. When `pr-single-hop-enabled` is `true`, use `server-connection-timeout`.	`10000` (10 seconds)
idle-timeout	Maximum time, in milliseconds, a pool connection can stay open without being used when there are more than `min-connections` in the pool. Pings over the connection do not count as connection use. If set to `-1`, there is no idle timeout. If `load-conditioning-interval` is set to a nonzero value, then `idle-timeout` cannot exceed that value. In this case, if `idle-timeout` is set to `-1` or to a value greater than the `load-conditioning-interval`, it is reset to the same value as `load-conditioning-interval`.	`120000` (2 minutes)
load-conditioning-interval	Amount of time, in milliseconds, a pool connection can remain open before being eligible for silent replacement to a less-loaded server. VMware recommends that you set `load-polling-interval` higher than the server's `load-poll-interval` and the client's `ping-interval`.	`300000` (5 minutes)
max-connections	Maximum number of pool connections the pool can create. If the maximum connections are in use, an operation requiring a client-to-server connection blocks until a connection becomes available or the `free-connection-timeout` is reached. If set to `-1`, there is no maximum. The setting must indicate a cap greater than `min-connections`. Takes effect only when `pr-single-hop-enabled` is `false`. When `pr-single-hop-enabled` is `true`, use `max-connections-per-server`.	`-1`
max-connections-per-server	Maximum number of connections pooled to a single server. If the maximum connections are in use, an operation requiring a client-to-server connection to that server blocks until a connection becomes available or `server-connection-timeout` is reached. If set to `-1`, there is no maximum. The setting must indicate a cap greater than `min-connections-per-server`. Takes effect only when `pr-single-hop-enabled` is `true`. When `pr-single-hop-enabled` is `false`, use `max-connections`.	`-1`
min-connections	Minimum number of pool connections to keep available at all times. Used to establish the initial connection pool. If set to `0` (zero), no connection is created until an operation requires it. This number is the starting point, with more connections added later as needed, up to the `max-connections` setting. The setting must be an integer greater than or equal to `0`.	`1`
min-connections-per-server	Minimum number of connections for each cache server in the cluster. The system tries to to keep available at least this many connections to each server at all times. When a new pool is created, it immediately begins creating connections to each server, up to this minimum. If set to `0` (zero), no connection is created until an operation requires it. This number is the starting point, with more connections added later as needed, up to the `max-connections-per-server` setting. The setting must be an integer greater than or equal to `0`.	`1`
multiuser-authentication	Used for installations with security where you want to accommodate multiple users within a single client. If set to `true`, the pool provides authorization for multiple user instances in the same client application, and each user accesses the cache through its own `RegionService` instance. If set to `false`, the client either uses no authorization or only provides credentials for the single client process.	`false`
name	Name of this pool. Used in the client region pool-name to assign this pool to a region in the client cache. Note: This is a required property with no default setting.	none
ping-interval	How often to communicate with the server to show the client is alive, set in milliseconds. Pings are only sent when the ping-interval elapses between normal client messages. Note: Set this lower than the server's `maximum-time-between-pings`.	`10000`
pr-single-hop-enabled	Optimizes access to partitioned region data in the servers. When `true`, the pool configuration is also affected by the attributes `max-connections-per-server`, `min-connections-per-server`, and `server-connection-timeout`. When `false`, the pool configuration is also affected by the attributes `max-connections`, `min-connections`, and `free-connection-timeout`. For details about how these settings interact, see Configuring a Client/Server System.	`true`
read-timeout	Maximum time, in milliseconds, for the client to wait for a response from a server.	`10000` (10 seconds)
retry-attempts	Number of times to retry a client request before giving up. If one server fails, the pool moves to the next, and continues to move to the next until it is successful or it meets this limit. If the number of available servers is lower than this setting, the pool will retry servers that have already failed until it reaches the limit. If this is set to `-1`, the pool tries every available server once.	`-1`
server-connection-timeout	Time, in milliseconds, that a thread will wait to get a pool connection to a specific server, before timing out with an exception. This timeout keeps threads from waiting indefinitely when the pool's `max-connections-per-server` has been reached and all connections in a pool are in use by other threads.	`0`
server-group	Logical named server group to use from the pool. A null value uses the global server group to which all servers belong. Note: This is only used when the `locator` list is defined.	null
socket-buffer-size	Size for socket buffers from the client to the server.	`32768`
socket-connect-timeout	Time, in milliseconds, to wait before timing out on the client socket connect to a server or locator. A value of `0` (zero) indicates an infinite timeout. If set to `0`, the connection blocks until established or an error occurs.	`59000`
statistic-interval	Interval, in milliseconds, at which to send client statistics to the server. If set to `-1`, statistics are not sent.	`-1`
subscription-ack-interval	Time, in milliseconds, between messages to the primary server to acknowledge event receipt. Note: Used only when `subscription-redundancy` is not `0` (zero).	`100`
subscription-enabled	Boolean that indicates whether the server should connect back to the client and automatically sends server-side cache update information. Any bind address information for the client is automatically passed to the server for use in the callbacks.	`false`
subscription-message- tracking-timeout	Time-to-live, in milliseconds, for entries in the client's message tracking list.	`900000` (15 minutes)
subscription-redundancy	Number of servers to use as backup to the primary for highly available subscription queue management. If set to `0`, no servers are used. If set to `-1`, all available servers are used.	`0`
subscription-timeout-multiplier	Number of missing server pings that trigger timeout of a subscription feed. A value of `0` (zero) deactivates timeouts. A value of `1` or higher sets the server connection to time out after the specified number of ping intervals have elapsed. VMware recommends that you do not set this to a value of `1`.	`0`

Example:

<pool
  name="publisher"
  subscription-enabled="true">
  <locator
    host="myLocatorAddress1"
    port="12345"/>
   <locator
     host="myLocatorAddress2"
     port="45678"/>
</pool>

locator

<locator>

Addresses and ports of the locators to connect to. You can define multiple locators for the pool.

Note
Provide a locator list or server list, but not both.

<locator> Attributes

Attribute	Description	Default
host	Hostname of the locator
port	Port number of the locator

Example:

<pool ...>
  <locator
    host="myLocatorHost"
    port="12345"/>

server

<server>

Addresses and ports of the servers to connect to.

Note
Provide a server list or locator list, but not both.

Default:

<server> Attributes

Attribute	Description	Default
host	Hostname of the server
port	Port number of the server

Example:

<pool ...>
  <server
    host="myServerHost"
    port="123456"/>
</pool>

socket-factory

<socket-factory>

Defines a factory to create socket connections to locators and servers. A typical use of this element is to redirect connections to an ingress gateway such as Istio or HAProxy in a cluster where the TLS (SSL) Server Name Indication (SNI) field is set to indicate the actual locator or server the client is trying to reach. This allows you to expose only the gateway hostname:port without the client needing to be able to resolve the names of the locator and server machines.

Note
This setting may be used with either a Server list or a Locator list. It will be used to form connections to either.

Default:

API: org.apache.geode.cache.client.proxy.ProxySocketFactories

Example:

<pool ...>
  <socket-factory>
    <class-name>org.apache.geode.cache.client.proxy.SniProxySocketFactory</class-name>
    <parameter name="hostname">
      <string>my-gateway-address</string>
    </parameter>
    <parameter name="port">
      <string>12345</string>
    </parameter>
  </socket-factory>
</pool>

disk-store

<disk-store>

Defines a pool of one or more disk stores, which can be used by regions, and client subscription queues.

Default: The cache default disk store, named “DEFAULT”, is used when disk is used but no disk store is named.

API: org.apache.geode.cache.DiskStore

<disk-store> Attributes

Attribute	Description	Default
name	The name of the Disk Store.
auto-compact	Set to true to automatically compact the disk files.
compaction-threshold	The threshold at which an operation log (oplog) will become able to be compacted. Until this threshold is reached, the oplog will not be compacted. The threshold is a percentage in the range `0` to `100`.
allow-force-compaction	Set to true to allow disk compaction to be forced on this disk store.
max-oplog-size	The maximum size, in megabytes, of an operation log (oplog) file.
time-interval	Time, in milliseconds, that can elapse before unwritten data is written to disk.
write-buffer-size	The size of the write buffer that this disk store uses when writing data to disk. Larger values may increase performance but use more memory. The disk store allocates one direct memory buffer of this size.
queue-size	Maximum number of operations that can be asynchronously queued to be written to disk.
disk-usage-warning-percentage	Disk usage above this threshold generates a warning message. For example, if the threshold is set to 90%, then on a 1 TB drive falling under 100 GB of free disk space generates the warning. Set to `0` (zero) to deactivate.	`90`
disk-usage-critical-percentage	Disk usage above this threshold generates an error message and shuts down the member's cache. For example, if the threshold is set to 99%, then falling under 10 GB of free disk space on a 1 TB drive generates the error and shuts down the cache. Set to `0` (zero) to deactivate.	`99`

Example:

<disk-store
  name="DEFAULT"
  allow-force-compaction="true">
  <disk-dirs>
    <disk-dir>/export/thor/customerData</disk-dir>
    <disk-dir>/export/odin/customerData</disk-dir>
    <disk-dir>/export/embla/customerData</disk-dir>
  </disk-dirs>
</disk-store>

disk-dirs

<disk-dirs>

An element of a disk store that defines a set of <disk-dir> elements.

disk-dir

<disk-dir>

Specifies a region or disk store’s disk directory.

<disk-dir> Attributes

Attribute	Description	Default
dir-size	Maximum amount of space to use for the disk store, in megabytes.	`214748364` (2 petabytes)

Example:

<disk-dir
    dir-size="20480">/host3/users/gf/memberA_DStore</disk-dir>

pdx

<pdx>

Specifies the configuration for the Portable Data eXchange (PDX) method of serialization.

API: org.apache.geode.cache.CacheFactory.setPdxReadSerialized, setPdxDiskStore, setPdxPersistent, setPdxIgnoreUnreadFields and org.apache.geode.cache.ClientCacheFactory.setPdxReadSerialized, setPdxDiskStore, setPdxPersistent, setPdxIgnoreUnreadFields

Attribute	Description	Default
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. 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.

Example:

<client-cache>
  <pdx persistent="true" disk-store-name="myDiskStore">
    <pdx-serializer>
      <class-name>
        org.apache.geode.pdx.ReflectionBasedAutoSerializer
      </class-name>
      <parameter name="classes">
        <string>com.company.domain.DomainObject</string>>
      </parameter>
    </pdx-serializer>
  </pdx>
  ...
</client-cache>

pdx-serializer

<pdx-serializer>

Allows you to configure the PdxSerializer for this Tanzu GemFire member.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

Default:

API: org.apache.geode.cache.CacheFactory.setPdxSerializer

Example:

<client-cache>
  <pdx>
    <pdx-serializer>
     <class-name>com.company.ExamplePdxSerializer</class-name>
    </pdx-serializer>
  </pdx>
  ...
</client-cache>

region-attributes

<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.

API: org.apache.geode.cache.RegionFactory or org.apache.geode.cache.ClientRegionFactory

<region-attributes> Attributes

Attribute Description Default

concurrency-level

Gives an estimate of the maximum number of application threads that will concurrently access a region entry at one time. This attribute does not apply to partitioned regions. This attribute helps Tanzu GemFire optimize the use of system resources and reduce thread contention. This sets an initial parameter on the underlying java.util.ConcurrentHashMap used for storing region entries.

Note: Before you modify this, read the concurrency level description, then see the Java API documentation for java.util.ConcurrentHashMap.

API: setConcurrencyLevel

Example:

<region-attributes
  concurrency-level="10">
</region-attributes>

16 (threads)

data-policy

Specifies how the local cache handles data for a region. This setting controls behavior such as local data storage and region initialization.

Note: Configure the most common options using the region shortcuts, RegionShortcut and ClientRegionShortcut. The default data-policy of normal specifies local cache storage. The empty policy specifies no local storage. In the region shortcuts, empty corresponds to the settings with the string PROXY. You can use an empty region for event delivery to and from the local cache without the memory overhead of data storage.

You can specify the following data policies:

`empty`	No data storage in the local cache. The region always appears empty. Use this for event delivery to and from the local cache without the memory overhead of data storage - zero-footprint producers that only distribute data to others and zero-footprint consumers that only see events. To receive events with this, set the region's `subscription-attributes` `interest-policy` to all.
`normal`	Data used locally (accessed with `get`, stored with `put`, etc.) is stored in the local cache. This policy allows the contents in the cache to differ from other caches.
`partition`	Data is partitioned across local and remote caches using the automatic data distribution behavior of partitioned regions. Additional configuration is done in the `partition-attributes`.
`replicate`	The region is initialized with the data from other caches. After initialization, all events for the distributed region are automatically copied into the local region, maintaining a replica of the entire distributed region in the local cache. Operations that would cause the contents to differ with other caches are not allowed. This is compatible with local `scope`, behaving the same as for normal.
`persistent-partition`	Behaves the same as `partition` and also persists data to disk.
`persistent-replicate`	Behaves the same as `replicate` and also persists data to disk.
`preloaded`	Initializes like a replicated region. After initialization, behaves like a normal region.

API: setDataPolicy

Example:

<region-attributes
  data-policy="replicate">
</region-attributes>

This is similar to using a region shortcut with refid, however when you use the REPLICATE region shortcut, it automatically sets the region's scope to distributed-ack.

<region-attributes
  refid="REPLICATE">
</region-attributes>

If you use data-policy, you must set the scope explicitly.

normal

enable-async-conflation

For TCP/IP distributions between peers, specifies whether to allow aggregation of asynchronous messages sent by the producer member for the region. This is a special-purpose boolean attribute that applies only when asynchronous queues are used for slow consumers. A false value deactivates conflation so that all asynchronous messages are sent individually. This special-purpose attribute gives you extra control over peer-to-peer communication between distributed regions using TCP/IP. This attribute does not apply to client/server communication.

Note: To use this attribute, asynchronous queues must be enabled for slow consumers, specified with the async* gemfire properties.

API: setEnableAsyncConflation

Example:

<region-attributes
  enable-async-conflation="false">
</region-attributes>

true

enable-gateway

Determines whether the gateway is enabled for the region. When set to true, events in the region are sent to the defined gateway hubs.

Used only with GemFire version 6.x gateway configurations. For GemFire 7.0 configuration, see the gateway-sender-id attribute of the <region-attributes> element.

false

enable-subscription-conflation

Boolean for server regions that specifies whether the server can conflate its messages to the client. A value of true enables conflation.

Note: The client can override this setting with the conflate-events property in its gemfire.properties.

API: setEnableSubscriptionConflation

Example:

<region-attributes
  enable-subscription-conflation="true">
</region-attributes>

false

gateway-sender-ids

Specifies one or more gateway sender IDs to use for distributing region events to remote Tanzu GemFire sites. Specify multiple IDs as a comma-separated list.

API: addGatewaySenderId

Example:

<region-attributes
  gateway-sender-ids="nwsender,swsender">
</region-attributes>

not set

async-event-queue-ids

Specifies one or more asynchronous event queues to use for distributing region events an AsyncEventListener implementation (for example, for write-behind cache event handling). Specify multiple IDs as a comma-separated list.

API: addAsyncEventQueueId

Example:

<region-attributes
  async-event-queue-ids="customerqueue,ordersqueue">
</region-attributes>

not set

hub-id

If the enable-gateway attribute is set to true, a comma-separated list of gateway hub IDs that receive events from the region.

Used only with GemFire version 6.x gateway configurations. For GemFire 7.0 configuration, see the gateway-sender-id attribute of the <region-attributes> element.

null

Stores the region attribute settings in the cache with this identifier. Once stored, the attributes can be retrieved using the region attribute refid.

API: setId

Example:

<region-attributes
  id="persistent-replicated">
</region-attributes>

not set

ignore-jta

Boolean that determines whether operations on this region participate in active JTA transactions or ignore them and operate outside of the transactions. This is primarily used in cache loaders, writers, and listeners that need to perform non-transactional operations on a region, such as caching a result set.

API: setIgnoreJTA

Example:

<region-attributes
  ignore-jta="true">
</region-attributes>

false

index-update-type

Specifies whether region indexes are maintained synchronously with region modifications, or asynchronously in a background thread. In the cache.xml file, this is set as a value, asynchronous or synchronous, assigned to the index-update-type region attribute. Set this through the API by passing a boolean to the setIndexMaintenanceSynchronous method.

API: setIndexMaintenanceSynchronous

Example:

<region-attributes
  index-update-type="asynchronous">
</region-attributes>

synchronous updates

initial-capacity

Together with the load-factor region attribute, sets the initial parameters on the underlying java.util.ConcurrentHashMap used for storing region entries.

API: setInitialCapacity

Example:

<region-attributes
  initial-capacity="20">
</region-attributes>

16

is-lock-grantor

Determines whether this member defines itself as the lock grantor for the region at region creation time. This only specifies whether the member becomes lock grantor at creation and does not reflect the current state of the member's lock grantor status. The member's lock grantor status may change if another member subsequently defines the region with is-lock-grantor set to true. This attribute is only relevant for regions with global scope, as only they allow locking. It affects implicit and explicit locking.

API: setLockGrantor

Example:

<region-attributes
  is-lock-grantor="true">
</region-attributes>

false

load-factor

Together with the initial-capacity region attribute, sets the initial parameters on the underlying java.util.ConcurrentHashMap used for storing region entries. This must be a floating point number from 0 and 1, inclusive.

Note: Before you set this attribute, VMware recommends that you read the discussion of initial capacity and load factor, then see the Java API documentation for java.util.ConcurrentHashMap.

API: setLoadFactor

Example:

<region-attributes
  load-factor="0.85">
</region-attributes>

.75

mirror-type Deprecated

pool-name

Identifies the region as a client region and specifies the server pool the region is to use. The named pool must be defined in the client cache before the region is created. If this is not set, the region does not connect to the servers as a client region.

API: setPoolName

Examples:

This declaration creates the region as a client region with a server pool named DatabasePool. This pool-name specification is required, as there are multiple pools in the client cache:

<client-cache>
  <pool name="DatabasePool"
    subscription-enabled="true">
    ...
  </pool>
  <pool >
    name="OtherPool"
    subscription-enabled="true">
    ...
  </pool>
  <region ...>
    <region-attributes
      pool-name="DatabasePool">
    </region-attributes>
    ...

This declaration creates the region as a client region assigned the single pool that is defined for the client cache. Here the pool-name specification is implied to be the only pool that exists in the cache:

<client-cache>
  <pool
    name="publisher"
    subscription-enabled="true">
    ...
  </pool>
  <region
    name="myRegion"
    refid="CACHING_PROXY">
  </region>
</client-cache>

not set

disk-store-name

Assigns the region to the disk store with this name from the disk stores defined for the cache. Persist region data to disk by defining the region as persistent using the Shortcut Attribute Options or data-policy settings. Overflow data to disk by implementing LRU eviction-attributes with an action of overflow to disk. Each disk store defines the file system directories to use, how data is written to disk, and other disk storage maintenance properties. In addition, the disk-synchronous region attribute specifies whether writes are done synchronously or asynchronously.

API: setDiskStoreName

Example:

<region-attributes
  disk-store-name="myStoreA" >
</region-attributes>

null

disk-synchronous

For regions that write to disk, boolean that specifies whether disk writes are done synchronously for the region.

API: setDiskSynchronous

Example:

<region-attributes
  disk-store-name="myStoreA"
  disk-synchronous="true">
</region-attributes>

true

refid

Retrieves region shortcuts and user-defined named region attributes for attributes initialization

API: setRefId

Example:

<region-attributes
  refid="persistent-replicated">
  <!-- Override any stored
    attribute settings that you
    need to ... -->
</region-attributes>

not set

scope

Determines how updates to region entries are distributed to the other caches in the cluster where the region and entry are defined. Scope also determines whether to allow remote invocation of some of the region's event handlers, and whether to use region entry versions to provide consistent updates across replicated regions.

Note: You can configure the most common of these options with Tanzu GemFire region shortcuts in RegionShortcut and ClientRegionShortcut.

Note: Server regions that are not partitioned must be replicated with distributed-ack or global scope. The region shortcuts that specify REPLICATE have distributed-ack scope.

Set one of the following scope values:

`local`	No distribution. The region is visible only to threads running inside the member.
`distributed-no-ack`	Events are distributed to remote caches with no acknowledgement required.
`distributed-ack`	Events are distributed to remote caches with receipt acknowledgement required. Region entry versions are used to provide consistent updates across members of the cluster.
`global`	Events are distributed to remote caches with global locking to ensure distributed cache consistency.

API: setScope

Example:

<region-attributes
  scope="distributed-ack">
</region-attributes>

distributed-no-ack

statistics-enabled

Boolean that specifies whether to gather statistics on the region. Must be true to use expiration on the region. Tanzu GemFire provides a standard set of statistics for cached regions and region entries, which give you information for fine-tuning your cluster. Unlike other Tanzu GemFire statistics, statistics for local and distributed regions are not archived and cannot be charted. They are kept in instances of org.apache.geode.cache.CacheStatistics and made available through the region and its entries through the Region.getStatistics and Region.Entry.getStatistics methods.

API: setStatisticsEnabled

Example:

<region-attributes
  statistics-enabled="true">
</region-attributes>

false

cloning-enabled

Boolean used to determine how fromDelta applies deltas to the local cache for delta propagation. When set to true, the updates are applied to a clone of the value and then the clone is saved to the cache. When set to false, the value is modified in place in the cache.

API: setCloningEnabled

Example:

<region-attributes
  cloning-enabled="true">
</region-attributes>

false

concurrency-checks-enabled

Boolean used to determine whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed regions. See Consistency for Region Updates.

Note: Applications that use a client-cache may want to deactivate concurrency checking to see all events for a region. Tanzu GemFire server members can continue using concurrency checks for the region, but they will pass all events to the client cache. This configuration ensures that the client sees all events, but it does not prevent the client cache from becoming unsynchronized with the server cache.

API: setConcurrencyChecksEnabled

Example:

<region-attributes
  concurrency-checks-enabled="true">
</region-attributes>

true

off-heap

Boolean used to determine whether the region uses off-heap memory to store entry values, including values for region entries and queue entries. The region continues to use heap memory for everything else, such as entry keys and the ConcurrentHashMap.

API: setOffHeap

Example:

<region-attributes
  off-heap="true">
</region-attributes>

false

key-constraint

<key-constraint>

Defines the type of object to be allowed for the region entry keys. This must be a fully-qualified class name. The attribute ensures that the keys for the region entries are all of the same class. If key-constraint is not used, the region’s keys can be of any class. This attribute, along with value-constraint, is used for querying and indexing because it provides object type information to the query engine.

Note
Set the constraint in every cache where you create or update the region entries. For client/server installations, match constraints between client and server and between clusters. The constraint is only checked in the cache that does the entry put or create operation. To avoid deserializing the object, the constraint is not checked when the entry is distributed to other caches.

Default: not set

API: org.apache.geode.cache.RegionFactory.setKeyConstraint

Example:

<region-attributes>
  <key-constraint>
    java.lang.String
  </key-constraint>
</region-attributes>

value-constraint

<value-constraint>

Defines the type of object to be allowed for the region entry values. This must be a fully-qualified class name. If value constraint is not used, the region’s value can be of any class. This attribute, along with key-constraint, is used for querying and indexing because it provides object type information to the query engine.

Note
Set the constraint in every cache where you create or update the region entries. For client/server installations, match constraints between client and server and between clusters. The constraint is only checked in the cache that does the entry put or create operation. To avoid deserializing the object, the constraint is not checked when the entry is distributed to other caches.

Default: not set

API: org.apache.geode.cache.RegionFactory.setValueConstraint

Example:

<region-attributes>
  <value-constraint>
    cacheRunner.Portfolio
  </value-constraint>
</region-attributes>

region-time-to-live

<region-time-to-live>

Expiration setting that specifies how long the region can remain in the cache without anyone accessing or updating it.

Default: not set - no expiration of this type

API: org.apache.geode.cache.RegionFactory.setRegionTimeToLive

Example:

<region-attributes
  statistics-enabled="true">
  <region-time-to-live>
    <expiration-attributes
      timeout="3600"
      action="local-destroy"/>
  </region-time-to-live>
</region-attributes>

expiration-attributes

<expiration-attributes>

Within the entry-time-to-live or entry-idle-time element, this element specifies the expiration rules for removing old region entries that you are not using. You can destroy or invalidate entries, either locally or across the cluster. Within the region-time-to-live or region-idle-time element, this element specifies the expiration rules for the entire region.

API: See APIs for entry-time-to-live, entry-idle-time, region-time-to-live, region-idle-time

<expiration-attributes> Attributes

Attribute Description Default

timeout Number of seconds before a region or an entry expires. If timeout is not specified, it defaults to 0 (zero), which indicates no expiration. 0

action

Action that should take place when a region or an entry expires.

Select one of the following expiration actions:

`local-destroy`	Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
`destroy`	Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
`invalidate`	Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. Use this option when the region or the entry is no longer valid for any application in the cluster.
`local-invalidate`	Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.

invalidate

Example:

<region-attributes
  statistics-enabled="true">
  <entry-time-to-live>
    <expiration-attributes
      timeout="60"
      action="local-destroy"/>
  </entry-time-to-live>
</region-attributes>

custom-expiry

<custom-expiry>

Specifies the custom class that implements org.apache.geode.cache.CustomExpiry. You define this class in order to override the region-wide settings for specific entries. See Configure Data Expiration for an example.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: org.apache.geode.cache.RegionFactory.setCustomEntryIdleTimeout, setCustomeEntryTimeToLive

Example:

<region-attributes>
  <expiration-attributes
    timeout="60"
    action="local-destroy"/>
  <custom-expiry>
    <class-name>
      com.megaconglomerate.mypackage.MyClass
    </class-name>
  </custom-expiry>
</region-attributes>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

region-idle-time

<region-idle-time>

Expiration setting that specifies how long the region can remain in the cache without anyone accessing it.

Note
To ensure reliable read behavior across the partitioned region, use region-time-to-live for region expiration instead of this setting.

Default: not set - no expiration of this type

API: org.apache.geode.cache.RegionFactory.setRegionIdleTimeout

Example:

<region-attributes statistics-enabled="true">
  <region-idle-time>
    <expiration-attributes
      timeout="3600"
      action="local-destroy"/>
  </region-idle-time>
</region-attributes>

expiration-attributes

<expiration-attributes>

API: See APIs for entry-time-to-live, entry-idle-time, region-time-to-live, region-idle-time

<expiration-attributes> Attributes

Attribute Description Default

timeout Number of seconds before a region or an entry expires. If timeout is not specified, it defaults to 0 (zero), which indicates no expiration. 0

action

Action that should take place when a region or an entry expires.

Select one of the following expiration actions:

`local-destroy`	Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
`destroy`	Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
`invalidate`	Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. Use this option when the region or the entry is no longer valid for any application in the cluster.
`local-invalidate`	Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.

invalidate

Example:

<region-attributes
  statistics-enabled="true">
  <entry-time-to-live>
    <expiration-attributes
      timeout="60"
      action="local-destroy"/>
  </entry-time-to-live>
</region-attributes>

custom-expiry

<custom-expiry>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: org.apache.geode.cache.RegionFactory.setCustomEntryIdleTimeout, setCustomeEntryTimeToLive

Example:

<region-attributes>
  <expiration-attributes
    timeout="60"
    action="local-destroy"/>
  <custom-expiry>
    <class-name>
      com.megaconglomerate.mypackage.MyClass
    </class-name>
  </custom-expiry>
</region-attributes>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

entry-time-to-live

<entry-time-to-live>

Expiration setting that specifies how long the region’s entries can remain in the cache without anyone accessing or updating them. See <expiration-attributes> for details.

Default: not set - no expiration of this type.

API: org.apache.geode.cache.RegionFactory.setEntryTimeToLive

Example:

<region-attributes
  statistics-enabled="true">
  <entry-time-to-live>
    <expiration-attributes
     timeout="60"
     action="local-destroy"/>
  </entry-time-to-live>
</region-attributes>

expiration-attributes

<expiration-attributes>

API: See APIs for entry-time-to-live, entry-idle-time, region-time-to-live, region-idle-time

<expiration-attributes> Attributes

Attribute Description Default

timeout Time, in seconds, before a region or an entry expires. If timeout is not specified, it defaults to 0 (zero), which indicates no expiration. 0

action

Action that should take place when a region or an entry expires.

Select one of the following expiration actions:

`local-destroy`	Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
`destroy`	Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
`invalidate`	Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. Use this option when the region or the entry is no longer valid for any application in the cluster.
`local-invalidate`	Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.

invalidate

Example:

<region-attributes
  statistics-enabled="true">
  <entry-time-to-live>
    <expiration-attributes
      timeout="60"
      action="local-destroy"/>
  </entry-time-to-live>
</region-attributes>

custom-expiry

<custom-expiry>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: org.apache.geode.cache.RegionFactory.setCustomEntryIdleTimeout, setCustomeEntryTimeToLive

Example:

<region-attributes>
  <expiration-attributes
    timeout="60"
    action="local-destroy"/>
  <custom-expiry>
    <class-name>
      com.megaconglomerate.mypackage.MyClass
    </class-name>
  </custom-expiry>
</region-attributes>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

entry-idle-time

<entry-idle-time>

Expiration setting that specifies how long the region’s entries can remain in the cache without anyone accessing them. See <expiration-attributes> for details.

Note
To ensure reliable read behavior across the partitioned region, use entry-time-to-live for entry expiration instead of this setting.

API: org.apache.geode.cache.RegionFactory.setEntryIdleTimeout

Example:

<region-attributes
  statistics-enabled="true">
  <entry-idle-time>
    <expiration-attributes
      timeout="60"
      action="local-invalidate"/>
    </expiration-attributes>
  </entry-idle-time>
</region-attributes>

expiration-attributes

<expiration-attributes>

API: See APIs for entry-time-to-live, entry-idle-time, region-time-to-live, region-idle-time

<expiration-attributes> Attributes

Attribute Description Default

timeout Time, in seconds, before a region or an entry expires. If timeout is not specified, it defaults to 0 (zero), which indicates expiration. 0

action

Action that should take place when a region or an entry expires.

Select one of the following expiration actions:

`local-destroy`	Removes the region or entry from the local cache, but does not distribute the removal operation to remote members. You cannot use this action on partitioned region entries.
`destroy`	Removes the region or entry completely from the cache. Destroy actions are distributed according to the region's distribution settings. Use this option when the region or entry is no longer needed for any application in the cluster.
`invalidate`	Default expiration action. Marks an entry or all entries in the region as invalid. Distributes the invalidation according to the region's scope. Use this option when the region or the entry is no longer valid for any application in the cluster.
`local-invalidate`	Marks an entry or all entries in the region as invalid but does not distribute the operation. You cannot use this action on partitioned region entries. Local region invalidation is only supported for regions that are not configured as replicated regions.

invalidate

Example:

<region-attributes
  statistics-enabled="true">
  <entry-time-to-live>
    <expiration-attributes
      timeout="60"
      action="local-destroy"/>
  </entry-time-to-live>
</region-attributes>

custom-expiry

<custom-expiry>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: org.apache.geode.cache.RegionFactory.setCustomEntryIdleTimeout, setCustomeEntryTimeToLive

Example:

<region-attributes>
  <expiration-attributes
    timeout="60"
    action="local-destroy"/>
  <custom-expiry>
    <class-name>
      com.megaconglomerate.mypackage.MyClass
    </class-name>
  </custom-expiry>
</region-attributes>

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

cache-loader

<cache-loader>

An event-handler plug-in that allows you to program for cache misses. At most, one cache loader can be defined in each member for the region. For distributed regions, a cache loader may be invoked remotely from other members that have the region defined. When an entry get results in a cache miss in a region with a cache loader defined, the loader’s load method is called. This method is usually programmed to retrieve data from an outside data source, but it can do anything required by your application.

For partitioned regions, to have a cache loader you must install an instance of the cache loader in every data store. Partitioned regions support partitioned loading, where each cache loader loads only the data entries in the local member. If data redundancy is configured, data is loaded only if the local member holds the primary copy.

API: org.apache.geode.cache.RegionFactory.setCacheLoader

Example:

<region-attributes>
  <cache-loader>
    <class-name>quickstart.SimpleCacheLoader</class-name>
  </cache-loader>
</region-attributes>

cache-writer

<cache-writer>

An event-handler plug-in that allows you to receive before-event notification for changes to the region and its entries. It also has the ability to cancel events. At most, one cache writer can be defined in each member for the region. A cache writer may be invoked remotely from other members that have the region defined.

API: org.apache.geode.cache.RegionFactory.setCacheWriter

Example:

<region-attributes>
  <cache-writer>
    <class-name>quickstart.SimpleCacheWriter</class-name>
  </cache-writer>
</region-attributes>

cache-listener

<cache-listener>

An event-handler plug-in that receives after-event notification of changes to the region and its entries. Any number of cache listeners can be defined for a region in any member. Tanzu GemFire offers several listener types with callbacks to handle data and process events. Depending on the data-policy and the interest-policy subscription attributes, a cache listener may receive only events that originate in the local cache, or it may receive those events along with events that originate remotely.

Specify the Java class for the cache listener and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

API: org.apache.geode.cache.RegionFactory.addCacheListener

Example:

<region-attributes>
  <cache-listener>
    <class-name>
      quickstart.SimpleCacheListener
    </class-name>
  </cache-listener>
</region-attributes>

eviction-attributes

<eviction-attributes>

Specifies whether and how to control a region’s size. Size is controlled by removing least recently used (LRU) entries to make space for new ones. This may be done through destroy or overflow actions. You can configure your region for lru-heap-percentage with an eviction action of local-destroy using stored region attributes.

Default: Uses the lru-entry-count algorithm.

API: org.apache.geode.cache.RegionFactory.setEvictionAttributes

Example:

<region-attributes>
  <eviction-attributes>
    <lru-entry-count
      maximum="1000"
      action="overflow-to-disk"/>
  </eviction-attributes>
</region-attributes>

lru-entry-count

<lru-entry-count>

Using the maximum attribute, specifies maximum region capacity based on entry count.

<lru-entry-count> Attributes

Attribute Description Default

action

Set one of the following eviction actions:

`local-destroy`	Entry is destroyed locally. Not available for replicated regions.
`overflow-to-disk`	Entry is overflowed to disk and the value set to null in memory. For partitioned regions, this provides the most reliable read behavior across the region.

local-destroy

maximum The maximum number of entries allowed in a region.

lru-heap-percentage

<lru-heap-percentage>

Runs evictions when the Tanzu GemFire resource manager says to. The manager orders evictions when the total cache size is over the heap percentage limit specified in the manager configuration. You can declare a Java class that implements the ObjectSizer interface to measure the size of objects in the Region.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

<lru-heap-percentage> Attributes

Attribute Description Default

action

Set one of the following eviction actions:

`local-destroy`	Entry is destroyed locally. Not available for replicated regions.
`overflow-to-disk`	Entry is overflowed to disk and the value set to null in memory. For partitioned regions, this provides the most reliable read behavior across the region.

local-destroy

lru-memory-size

<lru-memory-size>

Using the maximum attribute, specifies maximum region capacity based on the amount of memory used, in megabytes. You can declare a Java class that implements the ObjectSizer interface to measure the size of objects in the Region.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

<lru-memory-size> Attributes

Attribute Description Default

action

Set one of the following eviction actions:

`local-destroy`	Entry is destroyed locally. Not available for replicated regions.
`overflow-to-disk`	Entry is overflowed to disk and the value set to null in memory. For partitioned regions, this provides the most reliable read behavior across the region.

local-destroy

maximum The maximum amount of memory used in the region, in megabytes.

jndi-bindings

<jndi-bindings>

Specifies the binding for a data-source used in transaction management. See Configuring Database Connections Using JNDI.

Example:

<jndi-bindings>
  <jndi-binding type="XAPooledDataSource"
    jndi-name="newDB2trans"
    init-pool-size="20"
    max-pool-size="100"
    idle-timeout-seconds="20"
    blocking-timeout-seconds="5"
    login-timeout-seconds="10"
    xa-datasource-class="org.apache.derby.jdbc.EmbeddedXADataSource"
    user-name="mitul"
    password="encrypted(83f0069202c571faf1ae6c42b4ad46030e4e31c17409e19a)">
    <config-property>
      <config-property-name>Description</config-property-name>
      <config-property-type>java.lang.String</config-property-type>
      <config-property-value>pooled_transact</config-property-value>
    </config-property>
    <config-property>
      <config-property-name>DatabaseName</config-property-name>
      <config-property-type>java.lang.String</config-property-type>
      <config-property-value>newDB</config-property-value>
    </config-property>
    <config-property>
      <config-property-name>CreateDatabase</config-property-name>
      <config-property-type>java.lang.String</config-property-type>
      <config-property-value>create</config-property-value>
    </config-property>
    ...
  </jndi-binding>
</jndi-bindings>

jndi-binding

<jndi-binding>

For every datasource that is bound to the JNDI tree, there should be one <jndi-binding> element. This element describes the property and the configuration of the datasource. Tanzu GemFire uses the attributes of the <jndi-binding> element for configuration. Use the <config-property> element to configure properties for the datasource.

VMware recommends that you set the username and password with the user-name and password <jndi-binding> attributes instead of using the <config-property> element.

<jndi-binding> Attributes

Attribute Description Default

blocking-timeout-seconds Time, in seconds, that a connection remains associated with a transaction. If this value is exceeded, the connection is disassociated from the transaction. 120

conn-pooled-datasource-class Java class used for the PooledDataSource type.

connection-url

URL for connecting to the datasource.

Note: If you are connecting to a JCA data source driver that implements XA transactions (where the jndi-binding type is XAPooledDataSource), do not use this attribute. Instead, define configuration properties for your database. See <config-property> for an example.

idle-timeout-seconds The maximum time, in seconds, that a connection can remain idle in a pool. When this threshold is reached, the connection is removed. 600

init-pool-size The initial pool size of a PooledConnection (an XAConnection or a non-XAConnection). 10

jdbc-driver-class Java class used for the SimpleDataSource type.

jndi-name The jndi-name attribute is the key binding parameter. If the value of jndi-name is a DataSource, it is bound as java:/myDatabase, where myDatabase is the name you assign to your data source. If the data source cannot be bound to JNDI at runtime, Tanzu GemFire logs a warning.

The maximum time, in seconds, for which a thread seeking a connection from a connection pool may be blocked. If the thread is unable to obtain connection in the stipulated time, a PoolException is thrown

If a connection is available the thread returns immediately.

If an existing connection is not available and the maximum number of connections in the pool has not been reached, a new connection is created and the thread returns immediately with the connection.

If a connection is not available, the thread blocks for the specified time while waiting for an available connection.

30

managed-conn-factory-class If the Resource Adapter is of type ManagedDataSource, this class becomes the source of the PooledConnection. (This class interface complies with the J2CA Java 2 Connector Architecture.)

max-pool-size The maximum size of the PooledConnection. 30

password Password to access the datasource.

transaction-type

When the type attribute is set to ManagedDataSource, specifies the type of transaction. Set one of the following type of transaction:

XATransaction	Select this option when you want to use aManagedConnection interface with a Java Transaction Manager to define transaction boundaries. This option allows a ManagedDataSource to participate in a transaction with a Tanzu GemFire cache.
NoTransaction	No transactional behavior is used.
LocalTransaction	Select this option when using a ManagedDataSource that is not managed by the Java Transaction manager.

none

type

Set one of the following types:

XAPooledDataSource	Pooled SQL connections. For this type, you must also set the `xa-datasource-class` attribute.
ManagedDataSource	JNDI binding type for the J2EE Connector Architecture (JCA). ManagedConnectionFactory. For information about the ManagedConnection interface, see Interface ManagedConnection in the Oracle Java documentation.
PooledDataSource	Pooled SQL connections. For this type, you must also set the `conn-pooled-datasource-class` attribute.
SimpleDataSource	Single SQL connection. No pooling of SQL connections is done. Connections are generated on the fly and cannot be reused. For this type, you must also set the `jdbc-driver-class` attribute.

none

user-name User name to access to the datasource.

xa-datasource-class Java class used for the XAPooledDataSource type.

config-property

<config-property>

A configuration property of the datasource. Use the sub-elements to identify the name, datatype, and value of the property.

Default:

API: ``

Example:

<config-property>
  <config-property-name>DatabaseName</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>newDB</config-property-value>
</config-property>

Configuration properties vary depending on the database vendor. See Configuring Database Connections Using JNDI for examples of different configuration property configurations.

config-property-name

<config-property-name>

The name of this datasource property.

config-property-type

<config-property-type>

The data type of this datasource property.

config-property-value

<config-property-value>

The value of this datasource property.

region

<region>

Defines a region in the cache. See <region-attributes> for more details on configuring regions. You can specify zero or more subregions within a region. See Create and Access Data Subregions for restrictions on creating subregions. For example, you cannot create a partitioned subregion.

Default:

API: org.apache.geode.cache.RegionFactory or org.apache.geode.cache.ClientRegionFactory

<region> Attributes

Attribute	Description	Default
name	Specify the name for the region. See Region Management for details.
refid	Used to apply predefined attributes to the region being defined. If the nested `region-attributes` element has its own `refid`, then it will cause the `refid` on the region to be ignored. The `refid` region attribute can be set to the name of a RegionShortcut or a ClientRegionShortcut. For more information, see Region Shortcuts and Custom Named Region Attributes and Storing and Retrieving Region Shortcuts and Custom Named Region Attributes.

Example:

<!--Using region shortcut-->
<region
  name="PartitionedRegion"
  refid="PARTITION_REDUNDANT">
  ...
</region>

<!-- Retrieving and storing attributes -->
<region-attributes
  id="myPartition"
  refid="PARTITION_REDUNDANT">
  <partition-attributes
    local-max-memory="512"/>
</region-attributes>

<!-- Attributes are retrieved and applied in the first region -->
<region name="PartitionedRegion1" refid="myPartition"/>

See <region-attributes> for a complete listing of region attributes.

region-attributes

<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.

API: org.apache.geode.cache.RegionFactory or org.apache.geode.cache.ClientRegionFactory

<region-attributes> Attributes

Attribute Description Default

concurrency-level

Provides an estimate of the maximum number of application threads that will concurrently access a region entry at one time. This attribute does not apply to partitioned regions. This attribute helps Tanzu GemFire optimize the use of system resources and reduce thread contention. This sets an initial parameter on the underlying java.util.ConcurrentHashMap used for storing region entries.

Note: Before you modify this, VMware recommends that you read the concurrency level description, then see the Java API documentation for java.util.ConcurrentHashMap.

API: setConcurrencyLevel

Example:

<region-attributes
  concurrency-level="10">
</region-attributes>

16 (threads)

data-policy

Specifies how the local cache handles data for a region. This setting controls behavior such as local data storage and region initialization.

You can specify the following data policies:

`empty`	No data storage in the local cache. The region always appears empty. Use this for event delivery to and from the local cache without the memory overhead of data storage - zero-footprint producers that only distribute data to others and zero-footprint consumers that only see events. To receive events with this, set the region's `subscription-attributes` `interest-policy` to all.
`normal`	Data used locally (accessed with `get`, stored with `put`, etc.) is stored in the local cache. This policy allows the contents in the cache to differ from other caches.
`partition`	Data is partitioned across local and remote caches using the automatic data distribution behavior of partitioned regions. Additional configuration is done in the `partition-attributes`.
`replicate`	The region is initialized with the data from other caches. After initialization, all events for the distributed region are automatically copied into the local region, maintaining a replica of the entire distributed region in the local cache. Operations that would cause the contents to differ with other caches are not allowed. This is compatible with local `scope`, behaving the same as for normal.
`persistent-partition`	Behaves the same as `partition` and also persists data to disk.
`persistent-replicate`	Behaves the same as `replicate` and also persists data to disk.
`preloaded`	Initializes like a replicated region. After initialization, behaves like a normal region.

API: setDataPolicy

Example:

<region-attributes
  data-policy="replicate">
</region-attributes>

This is similar to using a region shortcut withrefid, however when you use the REPLICATE region shortcut, it automatically sets the region's scope to distributed-ack.

<region-attributes
  refid="REPLICATE">
</region-attributes>

If you use data-policy, you must set the scope explicitly.

normal

enable-async-conflation

For TCP/IP distributions between peers, specifies whether to allow aggregation of asynchronous messages sent by the producer member for the region. This is a special-purpose boolean attribute that applies only when asynchronous queues are used for slow consumers. A false value deactivates conflation so that all asynchronous messages are sent individually. This special-purpose attribute gives you extra control over peer-to-peer communication between distributed regions using TCP/IP. This attribute does not apply to client/server communication.

Note: To use this attribute, asynchronous queues must be enabled for slow consumers, specified with the async* gemfire properties.

API: setEnableAsyncConflation

Example:

<region-attributes
  enable-async-conflation="false">
</region-attributes>

true

enable-gateway

Determines whether the gateway is enabled for the region. When set to true, events in the region are sent to the defined gateway hubs.

Used only with GemFire version 6.x gateway configurations. For GemFire 7.0 configuration, see the gateway-sender-id attribute of the <region-attributes> element.

false

enable-subscription-conflation

Boolean for server regions that specifies whether the server can conflate its messages to the client. A value of true enables conflation.

Note: The client can override this setting with the conflate-events property in its gemfire.properties.

API: setEnableSubscriptionConflation

Example:

<region-attributes
  enable-subscription-conflation="true">
</region-attributes>

false

gateway-sender-ids

Specifies one or more gateway sender IDs to use for distributing region events to remote Tanzu GemFire sites. Specify multiple IDs as a comma-separated list.

API: addGatewaySenderId

Example:

<region-attributes
  gateway-sender-ids="nwsender,swsender">
</region-attributes>

not set

async-event-queue-ids

Specifies one or more asynchronous event queues to use for distributing region events an AsyncEventListener implementation, for example, for write-behind cache event handling. Specify multiple IDs as a comma-separated list.

API: addAsyncEventQueueId

Example:

<region-attributes
  async-event-queue-ids="customerqueue,ordersqueue">
</region-attributes>

not set

hub-id

If the enable-gateway attribute is set to true, a comma-separated list of gateway hub IDs that receive events from the region.

Used only with GemFire version 6.x gateway configurations. For GemFire 7.0 configuration, see the gateway-sender-id attribute of the <region-attributes> element.

null

Stores the region attribute settings in the cache with this identifier. Once stored, the attributes can be retrieved using the region attribute refid.

API: setId

Example:

<region-attributes
  id="persistent-replicated">
</region-attributes>

not set

ignore-jta

API: setIgnoreJTA

Example:

<region-attributes
  ignore-jta="true">
</region-attributes>

false

index-update-type

API: setIndexMaintenanceSynchronous

Example:

<region-attributes
  index-update-type="asynchronous">
</region-attributes>

synchronous updates

initial-capacity

Together with the load-factor region attribute, sets the initial parameters on the underlying java.util.ConcurrentHashMap used for storing region entries.

API: setInitialCapacity

Example:

<region-attributes
  initial-capacity="20">
</region-attributes>

16

is-lock-grantor

Boolean that determines whether this member defines itself as the lock grantor for the region at region creation time. This only specifies whether the member becomes lock grantor at creation and does not reflect the current state of the member's lock grantor status. The member's lock grantor status may change if another member subsequently defines the region with is-lock-grantor set to true. This attribute is only relevant for regions with global scope, as only they allow locking. It affects implicit and explicit locking.

API: setLockGrantor

Example:

<region-attributes
  is-lock-grantor="true">
</region-attributes>

false

load-factor

Note: Before you set this attribute, VMware recommends that you read the discussion of initial capacity and load factor, then see the Java API documentation for java.util.ConcurrentHashMap.

API: setLoadFactor

Example:

<region-attributes
  load-factor="0.85">
</region-attributes>

.75

mirror-type Deprecated

pool-name

API: setPoolName

Examples:

This declaration creates the region as a client region with a server pool named DatabasePool. This pool-name specification is required, as there are multiple pools in the client cache:

<client-cache>
  <pool name="DatabasePool"
    subscription-enabled="true">
    ...
  </pool>
  <pool >
    name="OtherPool"
    subscription-enabled="true">
    ...
  </pool>
  <region ...
    <region-attributes
      pool-name="DatabasePool">
    </region-attributes>
    ...

<client-cache>
  <pool
    name="publisher"
    subscription-enabled="true">
    ...
  </pool>
  <region
    name="myRegion"
    refid="CACHING_PROXY">
  </region>
</client-cache>

not set

disk-store-name

API: setDiskStoreName

Example:

<region-attributes
  disk-store-name="myStoreA" >
</region-attributes>

null

disk-synchronous

For regions that write to disk, boolean that specifies whether disk writes are done synchronously for the region.

API: setDiskSynchronous

Example:

<region-attributes
  disk-store-name="myStoreA"
  disk-synchronous="true">
</region-attributes>

true

refid

Retrieves region shortcuts and user-defined named region attributes for attributes initialization

API: setRefId

Example:

<region-attributes
  refid="persistent-replicated">
  <!-- Override any stored
    attribute settings that you
    need to ... -->
</region-attributes>

not set

scope

Note: You can configure the most common of these options with region shortcuts in RegionShortcut and ClientRegionShortcut.

Note: Server regions that are not partitioned must be replicated with distributed-ack or global scope. The region shortcuts that specify REPLICATE have distributed-ack scope.

Set one of the following scope values:

`local`	No distribution. The region is visible only to threads running inside the member.
`distributed-no-ack`	Events are distributed to remote caches with no acknowledgement required.
`distributed-ack`	Events are distributed to remote caches with receipt acknowledgement required. Region entry versions are used to provide consistent updates across members of the cluster.
`global`	Events are distributed to remote caches with global locking to ensure distributed cache consistency.

API: setScope

Example:

<region-attributes
  scope="distributed-ack">
</region-attributes>

distributed-no-ack

statistics-enabled

Boolean specifying whether to gather statistics on the region. Must be set to true to use expiration on the region. Tanzu GemFire provides a standard set of statistics for cached regions and region entries, which provide information for fine-tuning your cluster. Unlike other Tanzu GemFire statistics, statistics for local and distributed regions are not archived and cannot be charted. They are kept in instances of org.apache.geode.cache.CacheStatistics and made available through the region and its entries through the Region.getStatistics and Region.Entry.getStatistics methods.

API: setStatisticsEnabled

Example:

<region-attributes
  statistics-enabled="true">
</region-attributes>

false

cloning-enabled

Boolean that determines how fromDelta applies deltas to the local cache for delta propagation. When set to true, the updates are applied to a clone of the value and then the clone is saved to the cache. When set to false, the value is modified in place in the cache.

API: setCloningEnabled

Example:

<region-attributes
  cloning-enabled="true">
</region-attributes>

false

concurrency-checks-enabled

Boolean that determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed regions. See Consistency for Region Updates.

Note: Applications that use a client-cache may benefit from deactivating concurrency checking to see all events for a region. Tanzu GemFire server members can continue using concurrency checks for the region, but they will pass all events to the client cache. This configuration ensures that the client sees all events, but it does not prevent the client cache from becoming unsynchronized with the server cache.

API: setConcurrencyChecksEnabled

Example:

<region-attributes
  concurrency-checks-enabled="true">
</region-attributes>

true

off-heap

Boolean that determine whether the region uses off-heap memory to store entry values, including values for region entries and queue entries. The region continues to use heap memory for everything else, such as entry keys and the ConcurrentHashMap.

API: setOffHeap

Example:

<region-attributes
  off-heap="true">
</region-attributes>

false

index

<index>

Describes an index to be created on a region. The index node, if any, should all come immediately after the “region-attributes” node. The “name” attribute is a required field which identifies the name of the index. See Working with Indexes for more information about indexes.

Default:

API: org.apache.geode.cache.query.QueryService.createIndex, createKeyIndex, createHashIndex

<index> Attributes

Attribute	Description	Default
name	Required. Name of the index.
from-clause	Specifies the collections of objects that the index ranges over. The from-clause must only contain one and only one region path.
expression	Specifies the lookup value of the index.
imports	String containing the imports used to create the index. String should be specified in the query language syntax with each import statement separated by a semicolon. The imports statement provides packages and classes used in variable typing in the indexed and FROM expressions.
key-index	Boolean that determines whether the index should be a key index. If set to `true`, the region key specified in the indexed expression is used to evaluate queries
type	Possible values are `hash` or `range`.	`range`

Example:

<region name=exampleRegion>
  <region-attributes ...>
  </region-attributes>
  <index
    name="myIndex"
    from-clause="/exampleRegion"
    expression="status"/>
  <index
    name="myKeyIndex"
    from-clause="/exampleRegion"
    expression="id" key-index="true"/>
  <index
    name="myHashIndex"
    from-clause="/exampleRegion p"
    expression="p.mktValue" type="hash"/>
  ...
</region>

entry

<entry>

An <entry> element describes an entry to be added to a region. If an entry with the given key already exists in the region, it will be replaced.

Default:

API: org.apache.geode.cache.Region.create, put, get, putAll, getAll

Example:

<region ...>
  <region-attributes ...>
    ...
  </region-attributes>
  <entry>
    <key><string>MyKey</string></key>
    <value><string>MyValue</string></value>
  </entry>
</region>

key

<key>

Required. Describes the key in a region entry. A key can contain either a <string> or a <declarable> sub-element.

string

<string>

Specifies a String to be placed in a Region entry.

Example:

<region ...>
  <region-attributes ...>
    ...
  </region-attributes>
  <entry>
    <key><string>MyKey</string></key>
    <value><string>MyValue</string></value>
  </entry>
</region>

declarable

<declarable>

Specifies a Declarable object to be placed in a Region entry.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: Declarable

Example:

<parameter name="cacheserver">
  <declarable>
    <class-name>org.apache.geode.addon.cache.CacheServerInitializer</class-name>
    <parameter name="system.property.prefix">
      <string>cacheserver</string>
    </parameter>
  </declarable>
</parameter>

value

<value>

Required. Describes the value of a region entry. A <value> can contain either a <string> or a <declarable> sub-element.

string

<string>

Specifies a String to be placed in a Region entry.

Example:

<region ...>
  <region-attributes ...>
    ...
  </region-attributes>
 <entry>
    <key><string>MyKey</string></key>
    <value><string>MyValue</string></value>
  </entry>
</region>

declarable

<declarable>

Specifies a Declarable object to be placed in a Region entry.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements.

API: Declarable

Example:

<parameter name="cacheserver">
  <declarable>
    <class-name>org.apache.geode.addon.cache.CacheServerInitializer</class-name>
    <parameter name="system.property.prefix">
      <string>cacheserver</string>
    </parameter>
  </declarable>
</parameter>

region

<region>

Default:

API: org.apache.geode.cache.RegionFactory or org.apache.geode.cache.ClientRegionFactory

<region> Attributes

Attribute	Description	Default
name	Specify the name for the region. See Region Management for details.
refid	Used to apply predefined attributes to the region being defined. If the nested `region-attributes` element has its own `refid`, the `refid` on the region is ignored. The `refid` region attribute can be set to the name of a RegionShortcut or a ClientRegionShortcut. For more information, see Region Shortcuts and Custom Named Region Attributes and Storing and Retrieving Region Shortcuts and Custom Named Region Attributes.

Example:

<!--Using region shortcut-->
<region
  name="PartitionedRegion"
  refid="PARTITION_REDUNDANT">
  ...
</region>

<!-- Retrieving and storing attributes -->
<region-attributes
  id="myPartition"
  refid="PARTITION_REDUNDANT">
    <partition-attributes
      local-max-memory="512"/>
</region-attributes>

<!-- Attributes are retrieved and applied in the first region -->
<region name="PartitionedRegion1" refid="myPartition"/>

See<region-attributes> for a complete listing of region attributes.

function-service

<function-service>

Configures the behavior of the function execution service.

Example:

<client-cache>
  ...
  <function-service>
    <function>
      <class-name>com.myCompany.tradeService.cache.func.TradeCalc</class-name>
    </function>
  </function-service>
  ...
</client-cache>

function

<function>

Defines a function for registration in the function service

Specify the Java class for the function and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

Default:

API: org.apache.geode.cache.execute.FunctionService

Example:

<function>
  <class-name>
    com.myCompany.tradeService.cache.func.TradeCalc
  </class-name>
</function>

resource-manager

<resource-manager>

A memory monitor that tracks cache size as a percentage of total heap or off-heap memory and controls size by restricting access to the cache and prompting eviction of old entries from the cache. For tenured heap, used in conjunction with settings for JVM memory and Java garbage collection. For off-heap memory, used with the off-heap memory manager.

API: org.apache.geode.cache.control.ResourceManager

<resource-manager> Attributes

Attribute	Description	Default
critical-heap-percentage	Percentage of heap at or above which the cache is considered in danger of becoming inoperable due to garbage collection pauses or out of memory exceptions. Only one change to this attribute or critical heap percentage will be allowed at any given time and its effect will be fully realized before the next change is allowed. This feature requires additional VM flags to perform properly. See `setCriticalHeapPercentage()` for details.	`0`
eviction-heap-percentage	Set the percentage of heap at or above which the eviction should begin on Regions configured for HeapLRU eviction. Changing this value may cause eviction to begin immediately.	`0`, if no region is configured with heap eviction If `critical-heap-percentage` is set to a non-zero value, 5% less than that value. 80%, if `critical-heap-percentage` is not configured.
critical-off-heap-percentage	Percentage of off-heap memory at or above which the cache is considered in danger of becoming inoperable due to garbage collection pauses or out of memory exceptions.	`0`
eviction-off-heap-percentage	Set the percentage of off-heap memory at or above which the eviction should begin on Regions configured for HeapLRU eviction.	`0`, if no region is configured with heap eviction If `critical-off-heap-percentage` is set to a non-zero value, 5% less than that value. 80%, if `critical-off-heap-percentage` is not configured.

Example:

<client-cache>
  ...
  <resource-manager
    critical-heap-percentage="99.9"
    eviction-heap=-percentage="85"/>
  ...
</client-cache>

serialization-registration

<serialization-registration>

Set of serializer or instantiator tags to register customer DataSerializer extensions or DataSerializable implementations respectively.

Example:

<serialization-registration>
  <instantiator id="30">
    <class-name>com.package.MyClass</class-name>
  </instantiator>
</serialization-registration>

serializer

<serializer>

Allows you to configure the DataSerializer for this Tanzu GemFire member. It registers a custom class which extends DataSerializer to support custom serialization of non-modifiable object types inside Tanzu GemFire.

Specify the Java class for the DataSerializer and its initialization parameters with the <class-name> sub-element.

API: You can also register a DataSerializer by using the org.apache.geode.DataSerializer.register API. Use the org.apache.geode.Instantiator API to register a DataSerializable implementation.

instantiator

<instantiator>

An Instantiator registers a custom class which implements the DataSerializable interface to support custom object serialization inside Tanzu GemFire.

Specify the Java class and its initialization parameters with the <class-name> sub-element.

API: DataSerializable

You can also directly specify <instantiator> as a sub-element of <client-cache>. Use the org.apache.geode.Instantiator API to register a DataSerializable implementation as the serialization framework for the cache. The following table lists the attribute that can be specified for an <instantiator>.

<instantiator> Attributes

Attribute	Description	Default
id	Required. ID that the Instantiator should associate with the `DataSerializable` type.

initializer

<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.

Specify the Java class and its initialization parameters with the <class-name> and <parameter> sub-elements. See <class-name> and <parameter>.

Default:

API: Declarable

Example:

<initializer>
  <class-name>MyInitializer</class-name>
  <parameter name="members">
    <string>2</string>
  </parameter>
</initializer>