Client Region Design

Cached data are held in regions. A region is a logical grouping of data, and acts as a map data structure. Each entry within a region is a key/value pair.


Each region entry must have a unique key. Use a simple type of string, as opposed to an object or (integer) number. Using a string key enhances the development and debugging environment by permitting the use of a REST API, which works with string types.

Regions as Used by the App

The app accesses regions hosted on the servers by creating a cache local to the app. This local cache is called a client cache. The client cache creates regions that must match the name of the regions hosted on cluster servers. The name of the region is used to connect the client and server for communication and updates. The type of the client region determines if data is only on the servers or if data is also cached locally within the client region (within the app) in addition to being on the servers. You may choose to store data locally for applications that require extremely low latency reads. Locally cached data can introduce data inconsistency issues, because region entries updated on a server are not automatically propagated to the client’s local cache.

Client region types associate a name with a particular client region configuration.

  • PROXY forwards all region operations to the servers. No entries are locally cached. Use this client region type unless there is a compelling reason to use the other type. Use this type for all Twelve-Factor apps in order to assure stateless processes are implemented. Not caching any entries locally prevents the app from accidentally caching state.
  • CACHING_PROXY stores a locally cached copy of data in the client cache for get operations. All put operations are forwarded to servers. Locally cached data can become stale unless subscriptions are enabled and register interest is configured for the region, such that server updates are reflected in the client cache. As a best practice, local caching should only be used with small data sets that infrequently change, and only if the in-process performance is critical. Zip codes are an example of an infrequently-changing, small data set.