Add BoundStatement ReturnType as a return type for Create, Update, and Delete operations

Motivation:

In the 3.x driver the object-mapper had Mapper.saveQuery(entity) and
 Mapper.deleteQuery(id) which returned a BoundStatement that you could
 later execute. This was useful for creating a list of BoundStatement
 that would be added to a LOGGED Batch statement for atomically saving
 data that is saved across several denormalized tables (to support
 different query patterns on the same data).

While the current code sort of enables that with the @SetEntity, it
 however lacks a lot of the features that the other DAO methods have,
 for instance setting a TTL, custom IF and WHERE clauses that are
 are supported by the @insert, @update, and @delete methods. And not
 all of these features may be supportable on this more generic implemenation.

Modifcations:

Added a new DaoReturnType.BOUND_STATEMENT that is practically identical to
 to the existing DaoReturnType. Since it just returns the BoundStatment
 instead of executing it.

Result:

For @insert, @update, @delete, and @query DAO methods BoundStatement is
 now a new supported return type. This is an additive change to the API
 of the Mapper so it is non-breaking.

Author: fromanator

changelog/README.md

@@ -4,6 +4,7 @@
 
 ### 4.4.0 (in progress)
 
+- [new feature] JAVA-2532: Add BoundStatement ReturnType for insert, update, and delete DAO methods
 - [improvement] JAVA-2107: Add XML formatting plugin
 - [bug] JAVA-2527: Allow AllNodesFailedException to accept more than one error per node
 - [improvement] JAVA-2546: Abort schema refresh if a query fails

integration-tests/src/test/java/com/datastax/oss/driver/mapper/DeleteIT.java

@@ -21,6 +21,7 @@
 import com.datastax.oss.driver.api.core.CqlSession;
 import com.datastax.oss.driver.api.core.PagingIterable;
 import com.datastax.oss.driver.api.core.cql.AsyncResultSet;
+import com.datastax.oss.driver.api.core.cql.BoundStatement;
 import com.datastax.oss.driver.api.core.cql.ResultSet;
 import com.datastax.oss.driver.api.core.cql.Row;
 import com.datastax.oss.driver.api.core.cql.SimpleStatement;
@@ -174,6 +175,21 @@ public void should_delete_with_condition() {
     assertThat(dao.findById(id)).isNull();
   }
 
+  @Test
+  public void should_delete_with_condition_statement() {
+    UUID id = FLAMETHROWER.getId();
+    assertThat(dao.findById(id)).isNotNull();
+
+    BoundStatement bs = dao.deleteIfDescriptionMatchesStatement(id, "foo");
+    ResultSet rs = SESSION_RULE.session().execute(bs);
+    assertThat(rs.wasApplied()).isFalse();
+    assertThat(rs.one().getString("description")).isEqualTo(FLAMETHROWER.getDescription());
+
+    rs = dao.deleteIfDescriptionMatches(id, FLAMETHROWER.getDescription());
+    assertThat(rs.wasApplied()).isTrue();
+    assertThat(dao.findById(id)).isNull();
+  }
+
   @Test
   public void should_delete_with_condition_asynchronously() {
     UUID id = FLAMETHROWER.getId();
@@ -198,6 +214,13 @@ public void should_delete_by_partition_key() {
     assertThat(saleDao.all().all()).containsOnly(FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
   }
 
+  @Test
+  public void should_delete_by_partition_key_statement() {
+    // should delete FLAMETHROWER_SALE_[1-4]
+    SESSION_RULE.session().execute(saleDao.deleteByIdForDayStatement(FLAMETHROWER.getId(), DATE_1));
+    assertThat(saleDao.all().all()).containsOnly(FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
+  }
+
   @Test
   public void should_delete_by_partition_key_and_partial_clustering() {
     // should delete FLAMETHROWER_SALE_{1,3,4]
@@ -206,6 +229,16 @@ public void should_delete_by_partition_key_and_partial_clustering() {
         .containsOnly(FLAMETHROWER_SALE_2, FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
   }
 
+  @Test
+  public void should_delete_by_partition_key_and_partial_clustering_statement() {
+    // should delete FLAMETHROWER_SALE_{1,3,4]
+    SESSION_RULE
+        .session()
+        .execute(saleDao.deleteByIdForCustomerStatement(FLAMETHROWER.getId(), DATE_1, 1));
+    assertThat(saleDao.all().all())
+        .containsOnly(FLAMETHROWER_SALE_2, FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
+  }
+
   @Test
   public void should_delete_by_primary_key_sales() {
     // should delete FLAMETHROWER_SALE_2
@@ -220,6 +253,23 @@ public void should_delete_by_primary_key_sales() {
             MP3_DOWNLOAD_SALE_1);
   }
 
+  @Test
+  public void should_delete_by_primary_key_sales_statement() {
+    // should delete FLAMETHROWER_SALE_2
+    SESSION_RULE
+        .session()
+        .execute(
+            saleDao.deleteByIdForCustomerAtTimeStatement(
+                FLAMETHROWER.getId(), DATE_1, 2, FLAMETHROWER_SALE_2.getTs()));
+    assertThat(saleDao.all().all())
+        .containsOnly(
+            FLAMETHROWER_SALE_1,
+            FLAMETHROWER_SALE_3,
+            FLAMETHROWER_SALE_4,
+            FLAMETHROWER_SALE_5,
+            MP3_DOWNLOAD_SALE_1);
+  }
+
   @Test
   public void should_delete_if_price_matches() {
     ResultSet result =
@@ -238,6 +288,26 @@ public void should_delete_if_price_matches() {
     assertThat(result.wasApplied()).isTrue();
   }
 
+  @Test
+  public void should_delete_if_price_matchesStatement() {
+    BoundStatement bs =
+        saleDao.deleteIfPriceMatchesStatement(
+            FLAMETHROWER.getId(), DATE_1, 2, FLAMETHROWER_SALE_2.getTs(), 250.0);
+    ResultSet result = SESSION_RULE.session().execute(bs);
+
+    assertThat(result.wasApplied()).isFalse();
+    Row row = result.one();
+    assertThat(row).isNotNull();
+    assertThat(row.getDouble("price")).isEqualTo(500.0);
+
+    bs =
+        saleDao.deleteIfPriceMatchesStatement(
+            FLAMETHROWER.getId(), DATE_1, 2, FLAMETHROWER_SALE_2.getTs(), 500.0);
+    result = SESSION_RULE.session().execute(bs);
+
+    assertThat(result.wasApplied()).isTrue();
+  }
+
   @Test
   public void should_delete_if_exists_sales() {
     assertThat(saleDao.deleteIfExists(FLAMETHROWER.getId(), DATE_1, 2, FLAMETHROWER_SALE_2.getTs()))
@@ -262,6 +332,24 @@ public void should_delete_within_time_range() {
             FLAMETHROWER_SALE_2, FLAMETHROWER_SALE_4, FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
   }
 
+  @Test
+  public void should_delete_within_time_range_statement() {
+    // should delete FLAMETHROWER_SALE_{1,3}, but not 4 because range ends before
+    SESSION_RULE
+        .session()
+        .execute(
+            saleDao.deleteInTimeRangeStatement(
+                FLAMETHROWER.getId(),
+                DATE_1,
+                1,
+                FLAMETHROWER_SALE_1.getTs(),
+                Uuids.startOf(Uuids.unixTimestamp(FLAMETHROWER_SALE_4.getTs()) - 1000)));
+
+    assertThat(saleDao.all().all())
+        .containsOnly(
+            FLAMETHROWER_SALE_2, FLAMETHROWER_SALE_4, FLAMETHROWER_SALE_5, MP3_DOWNLOAD_SALE_1);
+  }
+
   @Test
   public void should_delete_if_price_matches_custom_where() {
     ResultSet result =
@@ -280,6 +368,26 @@ public void should_delete_if_price_matches_custom_where() {
     assertThat(result.wasApplied()).isTrue();
   }
 
+  @Test
+  public void should_delete_if_price_matches_custom_where_statement() {
+    BoundStatement bs =
+        saleDao.deleteCustomWhereCustomIfStatement(
+            2, FLAMETHROWER.getId(), DATE_1, FLAMETHROWER_SALE_2.getTs(), 250.0);
+    ResultSet result = SESSION_RULE.session().execute(bs);
+
+    assertThat(result.wasApplied()).isFalse();
+    Row row = result.one();
+    assertThat(row).isNotNull();
+    assertThat(row.getDouble("price")).isEqualTo(500.0);
+
+    bs =
+        saleDao.deleteCustomWhereCustomIfStatement(
+            2, FLAMETHROWER.getId(), DATE_1, FLAMETHROWER_SALE_2.getTs(), 500.0);
+    result = SESSION_RULE.session().execute(bs);
+
+    assertThat(result.wasApplied()).isTrue();
+  }
+
   @Mapper
   public interface InventoryMapper {
     @DaoFactory
@@ -305,6 +413,9 @@ public interface ProductDao {
     @Delete(entityClass = Product.class, customIfClause = "description = :expectedDescription")
     ResultSet deleteIfDescriptionMatches(UUID productId, String expectedDescription);
 
+    @Delete(entityClass = Product.class, customIfClause = "description = :expectedDescription")
+    BoundStatement deleteIfDescriptionMatchesStatement(UUID productId, String expectedDescription);
+
     @Delete
     CompletionStage<Void> deleteAsync(Product product);
 
@@ -335,25 +446,50 @@ public interface ProductSaleDao {
     @Delete(entityClass = ProductSale.class)
     ResultSet deleteByIdForDay(UUID id, String day);
 
+    // delete all rows in partition
+    @Delete(entityClass = ProductSale.class)
+    BoundStatement deleteByIdForDayStatement(UUID id, String day);
+
     // delete by partition key and partial clustering key
     @Delete(entityClass = ProductSale.class)
     ResultSet deleteByIdForCustomer(UUID id, String day, int customerId);
 
+    // delete by partition key and partial clustering key
+    @Delete(entityClass = ProductSale.class)
+    BoundStatement deleteByIdForCustomerStatement(UUID id, String day, int customerId);
+
     // delete row (full primary key)
     @Delete(entityClass = ProductSale.class)
     ResultSet deleteByIdForCustomerAtTime(UUID id, String day, int customerId, UUID ts);
 
+    // delete row (full primary key)
+    @Delete(entityClass = ProductSale.class)
+    BoundStatement deleteByIdForCustomerAtTimeStatement(
+        UUID id, String day, int customerId, UUID ts);
+
     @Delete(entityClass = ProductSale.class, customIfClause = "price = :expectedPrice")
     ResultSet deleteIfPriceMatches(
         UUID id, String day, int customerId, UUID ts, double expectedPrice);
 
+    @Delete(entityClass = ProductSale.class, customIfClause = "price = :expectedPrice")
+    BoundStatement deleteIfPriceMatchesStatement(
+        UUID id, String day, int customerId, UUID ts, double expectedPrice);
+
     @Delete(
         entityClass = ProductSale.class,
         customWhereClause =
             "id = :id and day = :day and customer_id = :customerId and ts >= :startTs and ts < "
                 + ":endTs")
     ResultSet deleteInTimeRange(UUID id, String day, int customerId, UUID startTs, UUID endTs);
 
+    @Delete(
+        entityClass = ProductSale.class,
+        customWhereClause =
+            "id = :id and day = :day and customer_id = :customerId and ts >= :startTs and ts < "
+                + ":endTs")
+    BoundStatement deleteInTimeRangeStatement(
+        UUID id, String day, int customerId, UUID startTs, UUID endTs);
+
     // transpose order of parameters so doesn't match primary key to ensure that works.
     @Delete(
         entityClass = ProductSale.class,
@@ -362,6 +498,14 @@ ResultSet deleteIfPriceMatches(
     ResultSet deleteCustomWhereCustomIf(
         int customerId, UUID id, String day, UUID ts, double expectedPrice);
 
+    // transpose order of parameters so doesn't match primary key to ensure that works.
+    @Delete(
+        entityClass = ProductSale.class,
+        customWhereClause = "id = :id and day = :day and customer_id = :customerId and ts = :ts",
+        customIfClause = "price = :expectedPrice")
+    BoundStatement deleteCustomWhereCustomIfStatement(
+        int customerId, UUID id, String day, UUID ts, double expectedPrice);
+
     @Delete(entityClass = ProductSale.class, ifExists = true)
     boolean deleteIfExists(UUID id, String day, int customerId, UUID ts);
 

integration-tests/src/test/java/com/datastax/oss/driver/mapper/InsertIT.java

@@ -20,6 +20,7 @@
 import com.datastax.oss.driver.api.core.CqlIdentifier;
 import com.datastax.oss.driver.api.core.CqlSession;
 import com.datastax.oss.driver.api.core.cql.AsyncResultSet;
+import com.datastax.oss.driver.api.core.cql.BoundStatement;
 import com.datastax.oss.driver.api.core.cql.ResultSet;
 import com.datastax.oss.driver.api.core.cql.Row;
 import com.datastax.oss.driver.api.core.cql.SimpleStatement;
@@ -98,6 +99,15 @@ public void should_insert_entity_returning_result_set() {
     assertThat(dao.findById(FLAMETHROWER.getId())).isEqualTo(FLAMETHROWER);
   }
 
+  @Test
+  public void should_return_bound_statement_to_execute() {
+    assertThat(dao.findById(FLAMETHROWER.getId())).isNull();
+    BoundStatement bs = dao.saveReturningBoundStatement(FLAMETHROWER);
+    ResultSet rs = SESSION_RULE.session().execute(bs);
+    assertThat(rs.getAvailableWithoutFetching()).isZero();
+    assertThat(dao.findById(FLAMETHROWER.getId())).isEqualTo(FLAMETHROWER);
+  }
+
   @Test
   public void should_insert_entity_asynchronously() {
     assertThat(dao.findById(FLAMETHROWER.getId())).isNull();
@@ -289,6 +299,9 @@ public interface ProductDao {
     @Insert
     ResultSet saveReturningResultSet(Product product);
 
+    @Insert
+    BoundStatement saveReturningBoundStatement(Product product);
+
     @Insert(timestamp = ":timestamp")
     void saveWithBoundTimestamp(Product product, long timestamp);
 

integration-tests/src/test/java/com/datastax/oss/driver/mapper/UpdateCustomIfClauseIT.java

@@ -20,6 +20,7 @@
 import com.datastax.oss.driver.api.core.CqlIdentifier;
 import com.datastax.oss.driver.api.core.CqlSession;
 import com.datastax.oss.driver.api.core.cql.AsyncResultSet;
+import com.datastax.oss.driver.api.core.cql.BoundStatement;
 import com.datastax.oss.driver.api.core.cql.ResultSet;
 import com.datastax.oss.driver.api.core.cql.SimpleStatement;
 import com.datastax.oss.driver.api.mapper.annotations.CqlName;
@@ -90,6 +91,22 @@ public void should_update_entity_if_condition_is_met() {
     assertThat(dao.updateIfLength(otherProduct, 10).wasApplied()).isEqualTo(true);
   }
 
+  @Test
+  public void should_update_entity_if_condition_is_met_statement() {
+    dao.update(
+        new Product(FLAMETHROWER.getId(), "Description for length 10", new Dimensions(10, 1, 1)));
+    assertThat(dao.findById(FLAMETHROWER.getId())).isNotNull();
+
+    Product otherProduct =
+        new Product(FLAMETHROWER.getId(), "Other description", new Dimensions(1, 1, 1));
+    assertThat(
+            SESSION_RULE
+                .session()
+                .execute(dao.updateIfLengthStatement(otherProduct, 10))
+                .wasApplied())
+        .isEqualTo(true);
+  }
+
   @Test
   public void should_not_update_entity_if_condition_is_not_met() {
     dao.update(
@@ -101,6 +118,22 @@ public void should_not_update_entity_if_condition_is_not_met() {
     assertThat(dao.updateIfLength(otherProduct, 20).wasApplied()).isEqualTo(false);
   }
 
+  @Test
+  public void should_not_update_entity_if_condition_is_not_met_statement() {
+    dao.update(
+        new Product(FLAMETHROWER.getId(), "Description for length 10", new Dimensions(10, 1, 1)));
+    assertThat(dao.findById(FLAMETHROWER.getId())).isNotNull();
+
+    Product otherProduct =
+        new Product(FLAMETHROWER.getId(), "Other description", new Dimensions(1, 1, 1));
+    assertThat(
+            SESSION_RULE
+                .session()
+                .execute(dao.updateIfLengthStatement(otherProduct, 20))
+                .wasApplied())
+        .isEqualTo(false);
+  }
+
   @Test
   public void should_async_update_entity_if_condition_is_met() {
     dao.update(
@@ -144,6 +177,9 @@ public interface ProductDao {
     @Update(customIfClause = "dimensions.length = :length")
     ResultSet updateIfLength(Product product, int length);
 
+    @Update(customIfClause = "dimensions.length = :length")
+    BoundStatement updateIfLengthStatement(Product product, int length);
+
     @Update(customIfClause = "dimensions.length = :\"Length\"")
     CompletableFuture<AsyncResultSet> updateIfLengthAsync(
         Product product, @CqlName("\"Length\"") int length);