---
title:  Managing Data Entries
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

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

<a id="managing_data_entries__section_AACC36127F17411F86D1E409B86C6E5C"></a>
**Note:**
If you do not have the cache's `copy-on-read` attribute set to true, do not change the objects returned from the Java entry access methods. See [Safe Entry Modification](#managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809).

## <a id="managing_data_entry_keys" class="no-quick-link"></a>Keys

<%=vars.product_name%> calls `hashCode()` on the key
to map an entry within the region.
The `hashCode()` return value must be the same for
a given key on every server that hosts the region.

An `equals()` call return value on a given key also must be
the same on every server that hosts the region.

A key may be a primitive type or a custom class.
For custom classes, see [Classes Used as Keys](using_custom_classes.html#using_custom_classes__section_CE776B94EDCB4D269A71C3C9CFEDD5FD).

Do not use an enumerated type (`enum`) for a key.
The `enum` `hashCode()` may not be overridden,
and its hash code is based upon an address.
Therefore, the return value for a `hashCode()` call can be different
on each server, violating the restriction that it must return
the same value on every server that hosts the region. 

## <a id="managing_data_entries__section_B095A4073EFB4A3C91AF7C03632EEBFB" class="no-quick-link"></a>Basic Create and Update

To create or update an entry in the cache, use `Region.put`. For example:

``` pre
String name = ... 
String value = ...  
this.currRegion.put(name,value); 
```

**Note:**
You can also use the `gfsh put` command to add entries to a region, and the `get` command to retrieve entries from a region. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html) 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.

## <a id="managing_data_entries__section_7578349EA26A4621B732FE851D71A84F" class="no-quick-link"></a>Batch Operations (getAll, putAll, removeAll)

<%=vars.product_name%> provides three APIs to perform batch operations on multiple region entries:

-   `Region.getAll`
-   `Region.putAll`
-   `Region.removeAll`

The `getAll` method takes a collection of keys and returns a `Map` of values for the provided keys. If a given key does not exist in the region, then that key's value in the returned map will be null.

The `putAll` method takes a `Map` of key-value pairs and puts them into the cache and distributes them in a single operation.

**Example:**

``` pre
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));
  this.currRegion.putAll(map); 
}
```

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.

The `removeAll` method takes a collection of keys and removes all of the entries for the specified keys from this region. This call performs the equivalent of calling`destroy(Object)` on this region once for each key in the specified collection. If an entry does not exist, then that key is skipped. An `EntryNotFoundException` is not thrown. This operation will be distributed to other caches if the region's scope is not set to `Scope.LOCAL`.

## <a id="managing_data_entries__section_A0E0F889AC344EFA8DF304FD64418809" class="no-quick-link"></a>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 <%=vars.product_name%> 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).

    ``` pre
    <cache copy-on-read="true">
     ...
    </cache>
    ```

    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`
    `Query.select`

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 `org.apache.geode.CopyHelper.copy`. Example:

    ``` pre
    Object o = (StringBuffer)region.get("stringBuf");
    StringBuffer s = (StringBuffer) CopyHelper.copy(o);
    s.append("Changes to value, added using put.");
    region.put("stringBuf", s);
    ```

## <a id="managing_data_entries__section_78F6731642944DE594316B86ECB4E70F" class="no-quick-link"></a>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.

## Using gfsh to get and put

You can use the gfsh `get` and `put` commands to manage data. See [get](../../tools_modules/gfsh/command-pages/get.html) and [put](../../tools_modules/gfsh/command-pages/put.html).

For example:

``` pre
get --key=('id':'133abg124') --region=region1

// Retrieving when key type is a wrapper(primitive)/String
get --key=('133abg124') --region=/region1/region12 --value-class=data.ProfileDetails

get --key=('100L') --region=/region1/region12 --value-class=data.ProfileDetails 
--key-class=java.lang.Long
```

``` pre
put --key=('id':'133abg125') --value=('firstname':'James','lastname':'Gosling') 
--region=/region1 --key-class=data.ProfileKey --value-class=data.ProfileDetails

put --key=('133abg124') --value=('Hello World!!') --region=/region2

put --key=('100F') --value=('2146547689879658564')  --region=/region1/region12 
--key-class=java.lang.Float --value-class=java.lang.Long
```