This is an automated email from the ASF dual-hosted git repository.
kmiller pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/geode.git
The following commit(s) were added to refs/heads/develop by this push:
new 2f5fe0a GEODE-5845 Document not to use enums for keys (#2605)
2f5fe0a is described below
commit 2f5fe0a8bcbd3245531abf33e43adae2f93f0272
Author: Karen Miller <[email protected]>
AuthorDate: Wed Oct 17 12:51:27 2018 -0700
GEODE-5845 Document not to use enums for keys (#2605)
* GEODE-5845 Document not to use enums for keys
* GEODE-5845 Revise docs (on not having enums as keys) per review
---
.../managing_data_entries.html.md.erb | 22 +++++++++++++++++++++-
.../using_custom_classes.html.md.erb | 7 +++++++
2 files changed, 28 insertions(+), 1 deletion(-)
diff --git
a/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb
b/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb
index a81696d..7d66e16 100644
---
a/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb
+++
b/geode-docs/basic_config/data_entries_custom_classes/managing_data_entries.html.md.erb
@@ -23,7 +23,27 @@ 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. 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 <%=vars.product_name%>, including cache listeners and expiration
activities, and can produce undesired results.
+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
diff --git
a/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb
b/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb
index e66825a..bb4b3de 100644
---
a/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb
+++
b/geode-docs/basic_config/data_entries_custom_classes/using_custom_classes.html.md.erb
@@ -49,3 +49,10 @@ The region uses hashing on keys. If you define a custom
class to use as a key, f
- `equals`
- `hashCode`. The default `hashCode` inherited from `Object` uses identity,
which is different in every system member. In partitioned regions, hashing
based on identity puts data in the wrong place. For details, see the Java API
documentation for `java.lang.Object`.
+Do not call `hashCode()` on an `enum` type data member
+within the key's custom `hashCode()` implementation.
+The `enum` `hashCode()` may not be overridden,
+and its hash is based upon an address.
+Therefore, an enumerated type's `hashCode()` return value can be different
+on each server, violating the restriction that `hashCode()` must return
+the same value on every server that hosts the region.
