Apache Geode Native C++

Client Cache XML Reference

This section documents the XML elements you can use to configure your Geode 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 Geode 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 Geode 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>

Sub-elements of <client-cache>

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

<pool> Element

The <pool> element is a collection of the connections by which your client application communicates with the Geode 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.

Attributes of <pool>

<locator>

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

Attributes of <locator>

For example:

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

<server>

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

Attributes of <server>

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

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.

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

Attributes of <region-attributes>

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

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

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

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

<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-function-name and optionally a library-name. Take into account that if library-name is not specified, the function will be looked for in the application itself. See the API Class Reference for the CacheLoader class.

<cache-listener>

<cache-listener> identifies a cache listener function by specifying library-function-name and optionally a library-name. Take into account that if library-name is not specified, the function will be looked for in the application itself. See the API Class Reference for the CacheListener class.

<cache-writer>

<cache-writer> identifies a cache writer function by specifying library-function-name and optionally a library-name. Take into account that if library-name is not specified, the function will be looked for in the application itself. 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>