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
String name = ...
String value = ...
You can also use the gfsh
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
void putAll(String command) throws CacheException
// Get Entry keys and values into Strings key1, ... keyN and value1, ... valueN
Map map = new LinkedHashMap();
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:
- Change the entry retrieval behavior
for your cache by setting the cache attribute,
copy-on-read, to true (the default is false).
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
||result of Region.put
- 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
Object o = (StringBuffer)region.get("stringBuf");
StringBuffer s = (StringBuffer) CopyHelper.copy(o);
s.append("Changes to value, added using put.");
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.