Managing Data Entries

Program your applications to create, modify, and manage your cached data entries.

Note: If you do not have the cachecopy-on-read attribute set to true, do not change the objects returned from the Java entry access methods. Instead, create a copy of the object, then modify the copy and pass it to the Java put method. Modifying a value in place bypasses the entire distribution framework provided by GemFire, including cache listeners and expiration activities, and can produce undesired results.

Basic Create and Update

To create or update an entry in the cache, use Region.put. For example:
String name = ... 
String value = ...  
Note: You can also use the gfsh put command to add an entry to a region. See put for more information.

If you want only to create the entry (with a null value and with method failure if the entry already exists), use Region.create instead.

Batch Entry Gets and Puts

To batch updates to multiple entries, use Region.putAll and Region.getAll. The method takes a Map of key-value pairs and puts them into the cache and distributes them in a single operation.

void putAll(String command) throws CacheException 
// Get Entry keys and values into Strings key1, ... keyN and value1, ... valueN 
  Map map = new LinkedHashMap(); 
  map.put(key1, value1)); 
  map.put(keyN, valueN));
The updates to the cache are done individually in the order in which they were placed in the Map. For partitioned regions, multiple events are sent as a single message to the primary buckets and then distributed to the secondary buckets.
Note: The processing of maps with very many entries and/or very large data may affect system performance and cause cache update timeouts, especially if the region uses overflow or persistence to disk.

Safe Entry Modification

When you get an entry value from the cache, by default, the retrieval methods return a direct reference to the cached object. This provides the value as quickly as possible, but also opens the cache to direct, in-place changes.
Note: Do not directly modify cached values. Modifying a value in place bypasses the GemFire distribution framework, including cache writers and listeners, expiration activities, and transaction management, and can produce undesired results.
Always change your entries using copies of the retrieved objects—never directly modify the returned objects. You can do this in one of two ways:
  1. Change the entry retrieval behavior for your cache by setting the cache attribute, copy-on-read, to true (the default is false).
    <cache copy-on-read="true">
    When copy-on-read is true, the entry access methods return copies of the entries. This protects you from inadvertently modifying in-place, but negatively impacts performance and memory consumption when copying is not needed.
    These entry access methods return an entry reference if copy-on-read is false and a copy of the entry if copy-on-read is true:
    Region.get result of Region.put EntryEvent.getNewValue
    Region.values Region.Entry.getValue EntryEvent.getOldValue
  2. Create a copy of the returned object and work with that. For objects that are cloneable or serializable, you can copy the entry value to a new object using com.gemstone.gemfire.CopyHelper.copy. Example:
    Object o = (StringBuffer)region.get("stringBuf");
    StringBuffer s = (StringBuffer) CopyHelper.copy(o);
    s.append("Changes to value, added using put.");
    region.put("stringBuf", s);

Retrieving Region Entries from Proxy Members

The Region.values method call applies to the local region instance only. If you call the values method from a client region using the PROXY shortcut, the method call will not be redirected to the server region. To obtain a collection of all values in the Region from a client, you should use interest registration on ALL_KEYS, or use a query.

If you use the Region.get method from a proxy member, the method call will redirect to the region on the server if it cannot find the key locally.