com.datastax.oss.driver.api.mapper.annotations

Annotation Type Delete

@Target(value=METHOD)
 @Retention(value=RUNTIME)
public @interface Delete

Annotates a Dao method that deletes an instance of an Entity-annotated class.

Example:

 @Dao
 public interface ProductDao {
   @Delete
   void delete(Product product);
 }
 

Parameters

The method can operate either on an entity instance, or on a primary key (partition key + clustering columns).

In the latter case, the parameters must match the types of the primary key columns, in the exact order (which is defined by the integer values of the PartitionKey and ClusteringColumn annotations in the entity class). The parameter names don't necessarily need to match the names of the columns. In addition, because the entity class can't be inferred from the method signature, it must be specified in the annotation with entityClass():

 @Delete(entityClass = Product.class)
 void deleteById(UUID productId);
 

An optional IF clause can be appended to the generated query. It can contain placeholders, for which the method must have corresponding parameters (same name, and a compatible Java type):

 @Delete(entityClass = Product.class, customIfClause = "description = :expectedDescription")
 ResultSet deleteIfDescriptionMatches(UUID productId, String expectedDescription);
 

A Function<BoundStatementBuilder, BoundStatementBuilder> or UnaryOperator<BoundStatementBuilder> can be added as the last parameter. It will be applied to the statement before execution. This allows you to customize certain aspects of the request (page size, timeout, etc) at runtime.

Return type

The method can return:

• void.
• a boolean or Boolean, which will be mapped to ResultSet.wasApplied(). This is intended for IF EXISTS queries:

   @Delete(ifExists = true)
   boolean deleteIfExists(Product product);
         

• a ResultSet. This is intended for queries with custom IF clauses; when those queries are not applied, they return the actual values of the tested columns.

   @Delete(entityClass = Product.class, customIfClause = "description = :expectedDescription")
   ResultSet deleteIfDescriptionMatches(UUID productId, String expectedDescription);
   // if the condition fails, the result set will contain columns '[applied]' and 'description'
         

• a BoundStatement. This is intended for queries where you will execute this statement later or in a batch.

   @Delete
   BoundStatement delete(Product product);
         

• a CompletionStage or CompletableFuture of any of the above. The method will execute the query asynchronously. Note that for result sets, you need to switch to AsyncResultSet.

   @Delete
   CompletableFuture<Void> deleteAsync(Product product);
  
   @Delete(ifExists = true)
   CompletionStage<Boolean> deleteIfExistsAsync(Product product);
  
   @Delete(entityClass = Product.class, customIfClause = "description = :expectedDescription")
   CompletionStage<AsyncResultSet> deleteIfDescriptionMatchesAsync(UUID productId, String expectedDescription);
         

Note that you can also return a boolean or result set for non-conditional queries, but there's no practical purpose for that since those queries always return wasApplied = true and an empty result set.

Target keyspace and table

If a keyspace was specified when creating the DAO (see DaoFactory), then the generated query targets that keyspace. Otherwise, it doesn't specify a keyspace, and will only work if the mapper was built from a Session that has a default keyspace set.

If a table was specified when creating the DAO, then the generated query targets that table. Otherwise, it uses the default table name for the entity (which is determined by the name of the entity class and the naming convention).

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	customIfClause A custom IF clause for the DELETE query.
String	customWhereClause A custom WHERE clause for the DELETE query.
Class<?>[]	entityClass A hint to indicate the entity class, for cases where it can't be determined from the method's signature.
boolean	ifExists Whether to append an IF EXISTS clause at the end of the generated DELETE query.

Element Detail

entityClass

public abstract Class<?>[] entityClass

A hint to indicate the entity class, for cases where it can't be determined from the method's signature.

This is only needed if the method receives the primary key components as arguments or uses a custom where clause:

 @Delete(entityClass = Product.class)
 void delete(UUID productId);

 @Delete(entityClass = Product.class, customWhereClause="product_id = :productId")
 void delete(UUID productId);
 

Note that, for technical reasons, this is an array, but only one element is expected. If you specify more than one class, the mapper processor will generate a compile-time warning, and proceed with the first one.

Default:

{}

customWhereClause

public abstract String customWhereClause

A custom WHERE clause for the DELETE query.

If this is not empty, it completely replaces the WHERE clause in the generated query. Note that the provided string must not contain the WHERE keyword and entityClass() must be specified.

This clause can contain placeholders that will be bound with the method's parameters; see the top-level javadocs of this class for more explanations.

Also note that this can be used in conjunction with customIfClause() or ifExists().

Default:

""

ifExists

public abstract boolean ifExists

Whether to append an IF EXISTS clause at the end of the generated DELETE query.

This is mutually exclusive with customIfClause() (if both are set, the mapper processor will generate a compile-time error).

Default:

false

customIfClause

public abstract String customIfClause

A custom IF clause for the DELETE query.

This is mutually exclusive with ifExists() (if both are set, the mapper processor will generate a compile-time error).

If this is not empty, it gets added to the generated query. Note that the provided string must not contain the IF keyword.

This clause can contain placeholders that will be bound with the method's parameters; see the top-level javadocs of this class for more explanations.

Default:

""