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

Annotation Type Update

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

Annotates a Dao method that updates one or more instances of an Entity-annotated class.

Example:

 @Dao
 public interface ProductDao {
   @Update
   void update(Product product);
 }
 

Parameters

The first parameter must be an entity instance. All of its non-PK properties will be interpreted as values to update.

• If customWhereClause() is empty, the mapper defaults to an update by primary key (partition key + clustering columns). The WHERE clause is generated automatically, and bound with the PK components of the provided entity instance. The query will update at most one row.
• If customWhereClause() is not empty, it completely replaces the WHERE clause. If the provided string contains placeholders, the method must have corresponding additional parameters (same name, and a compatible Java type):

   @Update(customWhereClause = "description LIKE :searchString")
   void updateIfDescriptionMatches(Product product, String searchString);
         

  The PK components of the provided entity are ignored. Multiple rows may be updated.

If the query has a TTL or timestamp with placeholders, the method must have corresponding additional parameters (same name, and a compatible Java type):

 @Update(ttl = ":ttl")
 void updateWithTtl(Product product, int ttl);
 

 @Update(timestamp = ":timestamp")
 void updateWithTimestamp(Product product, long timestamp);
 

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 conditional queries.

   @Update(ifExists = true)
   boolean updateIfExists(Product product);
         

• a ResultSet. The method will return the raw query result, without any conversion. This is intended for queries with custom IF clauses; when those queries are not applied, they return the actual values of the tested columns.

   @Update(customIfClause = "description = :expectedDescription")
   ResultSet updateIfDescriptionMatches(Product product, 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:

   @Update
   BoundStatement update(Product product);
        

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

   @Update
   CompletionStage<Void> update(Product product);
  
   @Update(ifExists = true)
   CompletableFuture<Boolean> updateIfExists(Product product);
  
   @Update(customIfClause = "description = :expectedDescription")
   CompletableFuture<AsyncResultSet> updateIfDescriptionMatches(Product product, String expectedDescription);
         

• a ReactiveResultSet.

   @Update
   ReactiveResultSet updateReactive(Product product);
         

• a custom type.

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 UPDATE query.
String	customWhereClause A custom WHERE clause for the UPDATE query.
boolean	ifExists Whether to append an IF EXISTS clause at the end of the generated UPDATE query.
NullSavingStrategy	nullSavingStrategy How to handle null entity properties during the update.
String	timestamp The timestamp to use in the generated INSERT query.
String	ttl The TTL (time to live) to use in the generated INSERT query.

Element Detail

customWhereClause

public abstract String customWhereClause

A custom WHERE clause for the UPDATE 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.

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:

""

ifExists

public abstract boolean ifExists

Whether to append an IF EXISTS clause at the end of the generated UPDATE 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 UPDATE 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:

""

ttl

public abstract String ttl

The TTL (time to live) to use in the generated INSERT query.

If this starts with ":", it is interpreted as a named placeholder (that must have a corresponding parameter in the method signature). Otherwise, it must be a literal integer value (representing a number of seconds).

If the placeholder name is invalid or the literal can't be parsed as an integer (according to the rules of Integer.parseInt(String)), the mapper will issue a compile-time warning.

Default:

""

timestamp

public abstract String timestamp

The timestamp to use in the generated INSERT query.

If this starts with ":", it is interpreted as a named placeholder (that must have a corresponding parameter in the method signature). Otherwise, it must be literal long value (representing a number of microseconds since epoch).

If the placeholder name is invalid or the literal can't be parsed as a long (according to the rules of Long.parseLong(String)), the mapper will issue a compile-time warning.

Default:

""

nullSavingStrategy

public abstract NullSavingStrategy nullSavingStrategy

How to handle null entity properties during the update.

This defaults either to the DAO-level strategy (if set), or NullSavingStrategy.DO_NOT_SET.

Default:

com.datastax.oss.driver.api.mapper.entity.saving.NullSavingStrategy.DO_NOT_SET