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 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 cacheserver 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 and multi-site gateway hubs for communication between distributed systems.
  • 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 dtd listed in the product dtd/cache6_6.dtd.

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

cache.xml for Peer/Server:
<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC
    "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.6//EN" 
"http://www.gemstone.com/dtd/cache6_6.dtd">
<cache>
	...
</cache>
cache.xml for Client:
<?xml version="1.0"?>
<!DOCTYPE client-cache PUBLIC
    "-//GemStone Systems, Inc.//GemFire Declarative Caching 6.6//EN" 
"http://www.gemstone.com/dtd/cache6_6.dtd">
<client-cache>
	...
</client-cache>

For more information on the cache.xml file, see cache.xml (Declarative Cache Configuration File).

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.

The steps in this section use gemfire.properties 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 listings may not include the full cache.xml file listing. All of your declarative cache configuration must conform to the cache DTD listing in the product installation dtd/cache6_6.dtd.

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.