JAVA-1159: Document workaround for using tuple with udt field in Mapper (apache#1166)

tolbertam · web-flow · commit a0bbb520e505 · 2019-01-07T12:32:19.000-06:00
diff --git a/changelog/README.md b/changelog/README.md
@@ -13,6 +13,7 @@
 - [improvement] JAVA-2003: Simplify CBUtil internal API to improve performance.
 - [improvement] JAVA-2002: Reimplement TypeCodec.accepts to improve performance.
 - [documentation] JAVA-2041: Deprecate cross-DC failover in DCAwareRoundRobinPolicy.
+- [documentation] JAVA-1159: Document workaround for using tuple with udt field in Mapper.
 
 
 ### 3.6.0
diff --git a/driver-mapping/src/test/java/com/datastax/driver/mapping/MapperUDTCollectionsTest.java b/driver-mapping/src/test/java/com/datastax/driver/mapping/MapperUDTCollectionsTest.java
@@ -15,9 +15,14 @@
  */
 package com.datastax.driver.mapping;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.testng.Assert.assertEquals;
 
 import com.datastax.driver.core.CCMTestsSupport;
+import com.datastax.driver.core.DataType;
+import com.datastax.driver.core.TupleType;
+import com.datastax.driver.core.TupleValue;
+import com.datastax.driver.core.UserType;
 import com.datastax.driver.core.utils.CassandraVersion;
 import com.datastax.driver.core.utils.MoreObjects;
 import com.datastax.driver.mapping.annotations.FrozenKey;
@@ -30,6 +35,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.UUID;
 import org.testng.annotations.Test;
 import org.testng.collections.Lists;
 
@@ -47,7 +53,8 @@ public void onTestContextInitialized() {
             + "s set<frozen<\"Sub\">>, "
             + "m1 map<int,frozen<\"Sub\">>, "
             + "m2 map<frozen<\"Sub\">,int>, "
-            + "m3 map<frozen<\"Sub\">,frozen<\"Sub\">>)");
+            + "m3 map<frozen<\"Sub\">,frozen<\"Sub\">>)",
+        "CREATE TABLE user_with_tuple (id uuid PRIMARY KEY, sub tuple<text,\"Sub\">)");
   }
 
   @UDT(name = "Sub", caseSensitiveType = true)
@@ -198,4 +205,108 @@ public void testNullCollection() {
 
     assertEquals(m.get(c.getId()), c);
   }
+
+  @Table(name = "user_with_tuple")
+  public static class UserWithTuple {
+    @PartitionKey private UUID id;
+
+    private TupleValue sub;
+
+    public UUID getId() {
+      return id;
+    }
+
+    public void setId(UUID id) {
+      this.id = id;
+    }
+
+    public TupleValue getSub() {
+      return sub;
+    }
+
+    public void setSub(TupleValue sub) {
+      this.sub = sub;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+      if (this == o) return true;
+      if (o == null || getClass() != o.getClass()) return false;
+
+      UserWithTuple that = (UserWithTuple) o;
+
+      if (id != null ? !id.equals(that.id) : that.id != null) return false;
+      return sub != null ? sub.equals(that.sub) : that.sub == null;
+    }
+
+    @Override
+    public int hashCode() {
+      int result = id != null ? id.hashCode() : 0;
+      result = 31 * result + (sub != null ? sub.hashCode() : 0);
+      return result;
+    }
+  }
+
+  @UDT(name = "Sub", caseSensitiveType = true)
+  // Create a separate class with the same structure to test effectiveness of udtCodec
+  public static class SubInTuple {
+    private int i;
+
+    public SubInTuple() {}
+
+    public SubInTuple(int i) {
+      this.i = i;
+    }
+
+    public int getI() {
+      return i;
+    }
+
+    public void setI(int i) {
+      this.i = i;
+    }
+
+    @Override
+    public boolean equals(Object other) {
+      if (other instanceof SubInTuple) {
+        SubInTuple that = (SubInTuple) other;
+        return this.i == that.i;
+      }
+      return false;
+    }
+
+    @Override
+    public int hashCode() {
+      return MoreObjects.hashCode(i);
+    }
+  }
+
+  /**
+   * Validates that tables having a tuple that has a UDT field can be handled by the object mapper
+   * assuming a udt codec has been registered with {@link MappingManager#udtCodec(Class)}
+   *
+   * @jira_ticket JAVA-1159
+   * @test_category object_mapper
+   */
+  @Test(groups = "short")
+  public void should_be_able_to_create_entity_from_table_having_tuple_with_udt() {
+    MappingManager manager = new MappingManager(session());
+    Mapper<UserWithTuple> mapper = manager.mapper(UserWithTuple.class);
+
+    // register a codec using udtCodec, this is mandatory.
+    manager.udtCodec(SubInTuple.class);
+
+    UserType subType = cluster().getMetadata().getKeyspace(keyspace).getUserType("\"Sub\"");
+    TupleType tt = cluster().getMetadata().newTupleType(DataType.text(), subType);
+    TupleValue tv = tt.newValue("seven", new SubInTuple(7));
+
+    UserWithTuple user = new UserWithTuple();
+    user.setId(UUID.randomUUID());
+    user.setSub(tv);
+
+    mapper.save(user);
+
+    UserWithTuple retrieved = mapper.get(user.getId());
+    assertThat(retrieved).isEqualTo(user);
+  }
 }
diff --git a/manual/object_mapper/creating/README.md b/manual/object_mapper/creating/README.md
@@ -359,9 +359,32 @@ private Map<Address, List<String>> frozenKeyValueMap;
 private Map<String, List<Address>> frozenValueMap;
 ```
 
+With regards to tuples, these can be represented as `TupleValue` fields, i.e.:
+
+```java
+@Frozen
+private TupleValue myTupleValue;
+```
+
+Please note however that tuples are not a good fit for the mapper since it is up to the user to
+resolve the associated `TupleType` when creating and accessing `TupleValue`s and properly use the
+right types since java type information is not known.
+
+Also note that `@UDT`-annotated classes are not implicitly registered with `TupleValue` like they
+otherwise are because the mapper is not able to identify the cql type information at the time
+entities are constructed.
+
+To work around this, one may use [udtCodec] to register a `TypeCodec` that the mapper can use
+to figure out how to appropriately handle UDT conversion, i.e.:
+
+```java
+mappingManager.udtCodec(Address.class);
+```
+
 [frozen]:http://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/annotations/Frozen.html
 [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
+[udtCodec]:https://docs.datastax.com/en/drivers/java/3.6/com/datastax/driver/mapping/MappingManager.html#udtCodec-java.lang.Class-
 
 #### Prefer Frozen Collections
 
