From be9414b1d40fe3c9ba44543cf7cbbd63992b7bd9 Mon Sep 17 00:00:00 2001 From: Andrew Tolbert Date: Fri, 14 Dec 2018 15:07:38 -0600 Subject: [PATCH 1/2] JAVA-2062: Document frozen collection preference with Mapper --- changelog/README.md | 3 ++- manual/object_mapper/creating/README.md | 20 ++++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/changelog/README.md b/changelog/README.md index c715898d3dd..b4e1c6d82d6 100644 --- a/changelog/README.md +++ b/changelog/README.md @@ -2,8 +2,9 @@ ### 3.7.0 (In progress) -- [improvement] JAVA-2025: Include exception message in Abstract*Codec.accepts(null). +- [improvement] JAVA-2025: Include exception message in Abstract\*Codec.accepts(null). - [improvement] JAVA-1980: Use covariant return types in RemoteEndpointAwareJdkSSLOptions.Builder methods. +- [documentation] JAVA-2062: Document frozen collection preference with Mapper. ### 3.6.0 diff --git a/manual/object_mapper/creating/README.md b/manual/object_mapper/creating/README.md index bb2edf3055f..fdcc5c91dbf 100644 --- a/manual/object_mapper/creating/README.md +++ b/manual/object_mapper/creating/README.md @@ -363,6 +363,26 @@ private Map> frozenValueMap; [frozenkey]:http://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/annotations/FrozenKey.html [frozenvalue]:http://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/annotations/FrozenValue.html +#### Prefer Frozen Collections + +If `Mapper.save` is used to create and update entities, it is recommended to +use frozen collections over non-frozen collections. + +Frozen collections in Cassandra are serialized as a single cell value where +non-frozen collections serialize each individual element in a collection as a +cell. + +Since `Mapper.save` provides the entire collection for a entity field value on +each invocation, it is more efficient to use frozen collections as the entire +collection is serialized as one cell. + +Also, when using non-frozen collections, on INSERT cassandra must +create a tombstone to invalidate all existing collection elements, even if +there are none. When using frozen collections, no such tombstone is needed. + +See [Freezing collection types] for more information about the frozen keyword. + +[Freezing collection types]: https://docs.datastax.com/en/dse/6.7/cql/cql/cql_using/refCollectionType.html ### Polymorphism support From 6694e7dc9ce920419b20f70bd344675fdfc39bbe Mon Sep 17 00:00:00 2001 From: Andrew Tolbert Date: Mon, 17 Dec 2018 09:51:52 -0600 Subject: [PATCH 2/2] [feedback] grammar and punctuation fixes --- manual/object_mapper/creating/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/object_mapper/creating/README.md b/manual/object_mapper/creating/README.md index fdcc5c91dbf..0819888e0b2 100644 --- a/manual/object_mapper/creating/README.md +++ b/manual/object_mapper/creating/README.md @@ -372,11 +372,11 @@ Frozen collections in Cassandra are serialized as a single cell value where non-frozen collections serialize each individual element in a collection as a cell. -Since `Mapper.save` provides the entire collection for a entity field value on +Since `Mapper.save` provides the entire collection for an entity field value on each invocation, it is more efficient to use frozen collections as the entire collection is serialized as one cell. -Also, when using non-frozen collections, on INSERT cassandra must +Also, when using non-frozen collections, on INSERT Cassandra must create a tombstone to invalidate all existing collection elements, even if there are none. When using frozen collections, no such tombstone is needed.