Client Cache XML Reference

This section documents the XML elements you can use to configure your VMware GemFire® native client application.

To define a configuration using XML:

  1. Set cache configuration parameters in a declarative XML file. By convention, this user guide refers to the file as cache.xml, but you can choose any name.

  2. Specify the filename and path to your XML configuration file by setting the cache-xml-file property in the geode.properties file. If you do not specify path, the application will search for the file in its runtime startup directory.

For example:

cache-xml-file=cache.xml

When you run your application, the native client runtime library reads and applies the configuration specified in the XML file.

The declarative XML file is used to externalize the configuration of the client cache. The contents of the XML file correspond to APIs found in theapache::geode::client package for C++ applications, and the Apache::Geode::Client package for .NET applications.

Elements are defined in the Client Cache XSD file, named cpp-cache-1.0.xsd, which you can find in your native client distribution in the xsds directory, and online at https://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd.

Cache Initialization File: XML Essentials

This section assumes you are familiar with XML. When creating a cache initialization file for your native client application, keep these basics in mind:

  • Place an XML prolog at the top of the file. For example:

    <?xml version="1.0" encoding="UTF-8"?>
    
  • Quote all parameter values, including numbers and booleans. For example:

    concurrency-level="10"
    caching-enabled="true"
    

Some types are specific to the VMware GemFire® cache initialization file:

  • Duration: Time specified as a non-negative integer and a unit, with no intervening space. The recognized units are h, min, s, ms, us, and ns. For example:

    idle-timeout = "5555ms"
    statistic-interval = "10s"
    update-locator-list-interval="5min"
    
  • Expiration: Complex type consisting of a duration (integer + unit) and an action, where the action is one of invalidate, destroy, local-invalidate, or local-destroy. For example:

    <expiration-attributes timeout="20s" action="destroy"/>
    <expiration-attributes timeout="10s" action="invalidate"/>
    
  • Library: Complex type consisting of a library name and a function name. Used by the client to invoke functions. For example:

    <persistence-manager library-name="SqLiteImpl"
     library-function-name="createSqLiteInstance">
    

Cache Initialization File Element Descriptions

This section shows the hierarchy of <client-cache> sub-elements that you use to configure VMware GemFire® caches and clients. The top-level element in this syntax is <client-cache>.

<client-cache>
      <pool>
            <locator>
            <server>
      <region>
            <region-attributes>
                  <region-time-to-live>
                  <region-idle-time>
                  <entry-time-to-live>
                  <entry-idle-time>
                  <partition-resolver>
                  <cache-loader>
                  <cache-listener>
                  <cache-writer>
                  <persistence-manager>
      <pdx>

In the descriptions, elements and attributes not designated “required” are optional.

<client-cache> Element

The <client-cache> element is the top-level element of the XSD file.

Your declarative cache file must include a schema of the following form:

<client-cache
 xmlns="http://geode.apache.org/schema/cpp-cache"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://geode.apache.org/schema/cpp-cache
   http://geode.apache.org/schema/cpp-cache/cpp-cache-1.0.xsd"
 version="1.0">
  ...
</client-cache>

Attributes of <client-cache>

Attribute Description
version Required. Must be “1.0”

Sub-elements of <client-cache>

<client-cache> must contain at least one of these sub-elements:

Element Minimum Occurrences Maximum Occurrences
<pool> 0 unbounded
<region> 0 unbounded
<pdx> 0 1

<pool> Element

The <pool> element is a collection of the connections by which your client application communicates with the VMware GemFire® server.

  • A connection can specify either a locator or a server.
  • A <pool> must contain at least one connection, locator or server, and can contain multiples of either or both.

Sub-elements of <pool>

A <pool> must contain at least one sub-element that specifies a connection, which can be either a server or a locator. Multiples of either or both types are permitted.

Element Minimum Occurrences Maximum Occurrences
<locator> 0 unbounded
<server> 0 unbounded

Attributes of <pool>

Attribute Description Default
name String. Required. Name of the pool, used when connecting regions to this pool.
free-connection-timeout Duration. The amount of time to wait for a free connection if max-connections is set and all of the connections are in use. 10s
load-conditioning-interval Duration. The interval at which the pool checks to see if a connection to a given server should be moved to a different server to improve the load balance. 5min
min-connections Non-negative integer. The minimum number of connections to keep available at all times. When the pool is created, it will create this many connections. If 0 (zero), then connections are not made until an operation is performed that requires client-to-server communication. 1
max-connections Integer >= -1. The maximum number of connections to be created. If all of the connections are in use, an operation requiring a client to server connection blocks until a connection is available. A value of -1 means no maximum. -1
retry-attempts Integer >= -1. The number of times to retry an operation after a timeout or exception. A value of -1 indicates that a request should be tried against every available server before failing. -1
idle-timeout Duration. Sets the amount of time a connection can be idle before it expires. A value of 0 (zero) indicates that connections should never expire. 5s
ping-interval Duration. The interval at which the pool pings servers. 10s
read-timeout Duration. The amount of time to wait for a response from a server before timing out and trying the operation on another server (if any are available). 10s
server-group String. Specifies the name of the server group to which this pool should connect. If the value is null or "" then the pool connects to all servers. ""
socket-buffer-size String. The size in bytes of the socket buffer on each connection established. 32768
subscription-enabled Boolean. When true, establish a server to client subscription. false
subscription-message-tracking-timeout String. The amount of time that messages sent from a server to a client will be tracked. The tracking is done to minimize duplicate events. Entries that have not been modified for this amount of time are expired from the list. 900s
subscription-ack-interval String. The amount of time to wait before sending an acknowledgement to the server for events received from server subscriptions. 100ms
subscription-redundancy String. Sets the redundancy level for this pool’s server-to-client subscriptions. An effort is made to maintain the requested number of copies (one copy per server) of the server-to-client subscriptions. At most, one copy per server is made up to the requested level. If 0 then no redundant copies are kept on the servers. 0
statistic-interval Duration. The interval at which client statistics are sent to the server. A value of 0 (zero) means do not send statistics. 0ms (disabled)
pr-single-hop-enabled String. When true, enable single hop optimizations for partitioned regions. true
thread-local-connections Boolean. Sets the thread local connections policy for this pool. When true then any time a thread goes to use a connection from this pool it will check a thread local cache and see if it already has a connection in it. If so it will use it. If not it will get one from this pool and cache it in the thread local. This gets rid of thread contention for the connections but increases the number of connections the servers see. When false then connections are returned to the pool as soon as the operation being done with the connection completes. This allows connections to be shared among multiple threads keeping the number of connections down. false
multiuser-authentication Boolean. Sets the pool to use multi-user secure mode. If in multiuser mode, then app needs to get RegionService instance of Cache. false
update-locator-list-interval Duration. The frequency with which client updates the locator list. To disable this set its value to std::chrono::milliseconds::zero().

<locator>

<locator> is a sub-element of <pool> that defines a connection to a VMware GemFire® locator, specified by a host and port combination.

Attributes of <locator>

Attribute Description
host String. Locator host name.
port Integer in the range 0 - 65535, inclusive. Locator port number.

For example:

<locator host="stax01" port="1001" />

<server>

<server> is a sub-element of <pool> that defines a connection to a VMware GemFire® server, specified by a host and port combination.

Attributes of <server>

Attribute Description
host String. Server host name.
port Integer in the range 0 - 65535, inclusive. Server port number.

For example:

<server host="motown01" port="2001" />

<region>

You can specify 0 or more regions per <client-cache>. There is no maximum limit on the number of regions a <client-cache> can contain.

In order to connect to a VMware GemFire® server, a client application must define at least one region whose name corresponds to that of a region on the server.

Regions can be nested.

Sub-elements of <region>

Use the <region-attributes> sub-element to specify most of the characteristics of a region. Regions may be nested.

Element Minimum Occurrences Maximum Occurrences
<region-attributes> 0 1
<region> 0 unbounded

Attributes of <region>

You can specify many attributes to configure a region, but most of these attributes are encapsulated in the <region-attributes> sub-element. The <region> element itself has only two attributes: a required name and an optional reference identifier.

Attribute Description
name String. Required.
refid String.

<region-attributes>

Specify 0 or 1 <region-attributes> element for each <region> you define.

If you specify a <region-attributes> element, you must specify at least one of these sub-elements. When more than one sub-element is specified, they must be defined in this order:

Element Type Minimum Occurrences Maximum Occurrences
<region-time-to-live> expiration 0 1
<region-idle-time> expiration 0 1
<entry-time-to-live> expiration 0 1
<entry-idle-time> expiration 0 1
<partition-resolver> library 0 1
<cache-loader> library 0 1
<cache-listener> library 0 1
<cache-writer> library 0 1
<persistence-manager> list of properties 0 1

Attributes of <region-attributes>

Attribute Description Default
caching-enabled Boolean. If true, cache data for this region in this process. If false, then no data is stored in the local process, but events and distributions will still occur, and the region can still be used to put and remove, etc. true
cloning-enabled Boolean. Sets cloning on region. false
scope Enumeration: local, distributed-no-ack, distributed-ack
initial-capacity String. Sets the initial entry capacity for the region. 10000
load-factor String. Sets the entry load factor for the next RegionAttributes to be created. 0.75
concurrency-level String. Sets the concurrency level of the next RegionAttributes to be created. 16
lru-entries-limit String. Sets the maximum number of entries this cache will hold before using LRU eviction. A return value of zero, 0, indicates no limit. If disk-policy is overflows, must be greater than zero.
disk-policy Enumeration: none, overflows, persist. Sets the disk policy for this region. none
endpoints String. A list of servername:port-number pairs separated by commas.
client-notification Boolean true/false (on/off) false
pool-name String. The name of the pool to attach to this region. The pool with the specified name must already exist.
concurrency-checks-enabled Boolean: true/false. Enables concurrent modification checks. true
id String.
refid String.

<region-time-to-live>

<region-time-to-live> specifies how long this region remains in the cache after the last create or update, and the expiration action to invoke when time runs out. A create or update operation on any entry in the region resets the region’s counter, as well. Get (read) operations do not reset the counter.

Use the <expiration-attributes> sub-element to specify duration and expiration action. The attributes of <expiration-attributes> must be defined in this order:

Attribute Description
timeout Duration, specified as an integer and units. Required.
action Enumeration. One of: invalidate, destroy, local-invalidate, local-destroy

<region-idle-time>

<region-idle-time> specifies how long this region remains in the cache after the last access, and the expiration action to invoke when time runs out. The counter is reset after any access, including create, put, and get operations. Access to any entry in the region resets the region’s counter, as well.

Use the <expiration-attributes> sub-element to specify duration and expiration action. The attributes of <expiration-attributes> must be defined in this order:

Attribute Description
timeout Duration, specified as an integer and units. Required.
action Enumeration. One of: invalidate, destroy, local-invalidate, local-destroy

<entry-time-to-live>

<entry-time-to-live> specifies how long this entry remains in the cache after the last create or update, and the expiration action to invoke when time runs out. Get (read) operations do not reset the counter.

Use the <expiration-attributes> sub-element to specify duration and expiration action. The attributes of <expiration-attributes> must be defined in this order:

Attribute Description
timeout Duration, specified as an integer and units. Required.
action Enumeration. One of: invalidate, destroy, local-invalidate, local-destroy

<entry-idle-time>

<entry-idle-time> specifies how long this entry remains in the cache after the last access, and the expiration action to invoke when time runs out. The counter is reset after any access, including create, put, and get operations.

Use the <expiration-attributes> sub-element to specify duration and expiration action. The attributes of <expiration-attributes> must be defined in this order:

Attribute Description
timeout Duration, specified as an integer and units. Required.
action Enumeration. One of: invalidate, destroy, local-invalidate, local-destroy

<partition-resolver>

<partition-resolver> identifies a function by specifying library-name and library-function-name.

A partition resolver is used for single-hop access to partitioned region entries on the server side. This resolver implementation must match that of the PartitionResolver on the server side. See the API Class Reference for the PartitionResolver class.

For example:

<partition-resolver library-name="appl-lib"
 library-function-name="createTradeKeyResolver"/>

<cache-loader>

<cache-loader> identifies a cache loader function by specifying library-name and library-function-name. See the API Class Reference for the CacheLoader class.

<cache-listener>

<cache-listener> identifies a cache listener function by specifying library-name and library-function-name. See the API Class Reference for the CacheListener class.

<cache-writer>

<cache-writer> identifies a cache writer function by specifying library-name and library-function-name. See the API Class Reference for the CacheWriter class.

<persistence-manager>

For each region, if the disk-policy attribute is set to overflows, a persistence-manager plug-in must perform cache-to-disk and disk-to-cache operations. See the API Class Reference for the PersistenceManager class.

<persistence-manager> identifies a persistence manager function by specifying library-name and library-function-name. You can also specify a set of properties to be passed to the function as parameters.

The sub-element <properties> is a sequence of 0 or more <property> elements.

Each <property> is a name-value pair. Where the attributes must be specified in this order:

  • name
  • value

For example:

<region-attributes>
   <persistence-manager library-name="libSqLiteImpl.so" library-function-name="createSqLiteInstance">
      <properties>
         <property name="PersistenceDirectory" value="/xyz"/>
         <property name="PageSize" value="65536"/>
         <property name="MaxPageCount" value="1073741823"/>
      </properties>
   </persistence-manager>
</region-attributes>

<pdx>

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

Attributes of <pdx>

Attribute Description
ignore-unread-fields Boolean. When true, do not preserve unread PDX fields during deserialization. You can use this option to save memory. Set this attribute to true only in members that are only reading data from the cache.
read-serialized Boolean. When true, PDX deserialization produces a PdxInstance instead of an instance of the domain class.