Pivotal GemFire® v8.2

Introduction to Cache Management

Introduction to Cache Management

The cache provides in-memory storage and management for your data.

You organize your data in the cache into data regions, each with its own configurable behavior. You store your data into your regions in key/value pairs called data entries. The cache also provides features like transactions, data querying, disk storage management, and logging. See the Javadocs for com.gemstone.gemfire.cache.Cache.

You generally configure caches using the gfsh command-line utility or a combination of XML declarations and API calls. GemFire loads and processes your XML declarations when you first create the cache.

GemFire has one cache type for managing server and peer caches and one for one for managing client caches. The cache server process automatically creates its server cache at startup. In your application process, the cache creation returns an instance of the server/peer or client cache. From that point on, you manage the cache through API calls in your application.

The Caching APIs

GemFire's caching APIs provide specialized behavior for different system member types and security settings.

  • com.gemstone.gemfire.cache.RegionService. Generally, you use the RegionService functionality through instances of Cache and ClientCache. You only specifically use instances of RegionService for limited-access users in secure client applications that service many users. The RegionService API provides access to existing cache data regions and to the standard query service for the cache. For client caches, queries are sent to the server tier. For server and peer caches, queries are run in the current cache and any available peers. RegionService is implemented by GemFireCache.
  • com.gemstone.gemfire.cache.GemFireCache. You do not specifically use instances of GemFireCache, but you use GemFireCache functionality in your instances of Cache and ClientCache. GemFireCache extends RegionService and adds general caching features like region attributes, disk stores for region persistence and overflow, and access to the underlying distributed system. GemFireCache is implemented by Cache and ClientCache.
  • com.gemstone.gemfire.cache.Cache. Use the Cache interface to manage server and peer caches. You have one Cache per server or peer process. The Cache extends GemFireCache and adds server/peer caching features like communication within the distributed system, region creation, transactions and querying, and cache server functionality.
  • com.gemstone.gemfire.cache.ClientCache. Use the ClientCache interface to manage the cache in your clients. You have one ClientCache per client process. The ClientCache extends GemFireCache and adds client-specific caching features like client region creation, subscription keep-alive management for durable clients, querying on server and client tiers, and RegionService creation for secure access by multiple users within the client.

The Cache XML

Your cache.xml must be formatted according to the product XML schema definition cache8-1.xsd. The schema definition file is available in the product distribution at $GEMFIRE/schemas/

You use one format for peer and server caches and another for client caches.

cache.xml for Peer/Server:
<?xml version="1.0" encoding="UTF-8"?>
<cache xmlns=""
cache.xml for Client:
<?xml version="1.0" encoding="UTF-8"?>

For more information on the cache.xml file, see cache.xml.

Create and Close a Cache

Your system configuration and cache configuration are initialized when you start your member processes and create each member’s GemFire cache. If you are using the cluster configuration service, member processes can pick up its cache configuration from the cluster or group's current configuration. See Overview of the Cluster Configuration Service.

The steps in this section use and cache.xml file examples, except where API is required. You can configure your distributed system properties and cache through the API as well, and you can use a combination of file configuration and API configuration.

The XML examples may not include the full cache.xml file listing. All of your declarative cache configuration must conform to the cache XSD in the product installation $GEMFIRE/schemas/

For all of your GemFire applications:

  1. Create your Cache, for peer/server applications, or ClientCache, for client applications. This connects to the GemFire system you have configured and initializes any configured data regions. Use your cache instance to access your regions and perform your application work.
  2. Close your cache when you are done. This frees up resources and disconnects your application from the distributed system in an orderly manner.

Follow the instructions in the subtopics under Cache Management to customize your cache creation and closure for your application needs. You may need to combine more than one of the sets of instructions. For example, to create a client cache in a system with security, you would follow the instructions for creating and closing a client cache and for creating and closing a cache in a secure system.

Export and Import a Cache Snapshot

To aid in the administration of cache data and speed the setup of new environments, you can export a snapshot of the entire cache (all regions) and then import the snapshot into a new cache. For example, you could take a snapshot of the production environment cache in order to import the cache's data into a testing environment.

For more details on exporting and importing snapshots of a cache, see Cache and Region Snapshots.

Cache Management with gfsh and the Cluster Configuration Service

You can use gfsh commands to mange a server cache. There are gfsh commands to create regions, start servers, and to create queues and other objects. As you issue these commands, the Cluster Configuration Service saves cache.xml and files on the locators and distributes those configurations to any new members that join the cluster. See Overview of the Cluster Configuration Service.