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

Annotation Type Insert

  • @Target(METHOD)
@Retention(RUNTIME)
public @interface Insert
    Annotates a Dao method that inserts an instance of an Entity-annotated class.

    Example: 

     @Dao
 public interface ProductDao {
   @Insert
   void insert(Product product);
 }

    Parameters

    The first parameter must be the entity to insert.

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

     @Insert(ttl = ":ttl")
 void insertWithTtl(Product product, int ttl);

    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.
    • the entity class. This is intended for INSERT ... IF NOT EXISTS queries. The method will return null if the insertion succeeded, or the existing entity if it failed. 
       @Insert(ifNotExists = true)
 Product insertIfNotExists(Product product);
    • an Optional of the entity class, as a null-safe alternative for INSERT ... IF NOT EXISTS queries. 
       @Insert(ifNotExists = true)
 Optional<Product> insertIfNotExists(Product product);
    • a boolean or Boolean, which will be mapped to ResultSet.wasApplied(). This is intended for IF NOT EXISTS queries: 
       @Insert(ifNotExists = true)
 boolean saveIfNotExists(Product product);
    • a ResultSet. This is intended for cases where you intend to inspect data associated with the result, such as PagingIterable.getExecutionInfo(). 
       @Insert
 ResultSet save(Product product);
    • a BoundStatement This is intended for cases where you intend to execute this statement later or in a batch: 
       @Insert
 BoundStatement save(Product product);
    • a CompletionStage or CompletableFuture of any of the above. The mapper will execute the query asynchronously. 
       @Insert
 CompletionStage<Void> insert(Product product);

 @Insert(ifNotExists = true)
 CompletableFuture<Product> insertIfNotExists(Product product);

 @Insert(ifNotExists = true)
 CompletableFuture<Optional<Product>> insertIfNotExists(Product product);
    • a ReactiveResultSet. 
       @Insert
 ReactiveResultSet insertReactive(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 Description
      boolean ifNotExists
      Whether to append an IF NOT EXISTS clause at the end of the generated INSERT query.
      NullSavingStrategy nullSavingStrategy
      How to handle null entity properties during the insertion.
      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.
      String usingTimeout
      The timeout to use in the generated INSERT query.

    • Element Detail

      • ifNotExists

        boolean ifNotExists
        Whether to append an IF NOT EXISTS clause at the end of the generated INSERT query.
        Default:
        false

      • ttl

        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:
        ""

      • usingTimeout

        String usingTimeout
        The timeout to use in the generated INSERT query. Equivalent to USING TIMEOUT <duration> clause.

        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 String representing a valid CqlDuration.

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

        Default:
        ""

      • timestamp

        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:
        ""