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

Interface EntityHelper<EntityT>

  • public interface EntityHelper<EntityT>
    A set of utility methods related to a particular mapped entity.

    The mapper processor generates an implementation of this interface for each Entity-annotated class. It is used internally by other mapper components, and can also be injected in custom query providers.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      com.datastax.oss.driver.api.querybuilder.delete.Delete deleteByPrimaryKey()
      Builds a delete query to delete an instance of the entity by primary key (partition key + clustering columns).
      EntityT get​(com.datastax.oss.driver.api.core.data.GettableByName source)
      Deprecated.
      Use get(GettableByName, boolean) instead.
      default EntityT get​(com.datastax.oss.driver.api.core.data.GettableByName source, boolean lenient)
      Gets values from a data structure to fill an entity instance.
      Class<EntityT> getEntityClass()
      The class of the mapped entity.
      com.datastax.oss.driver.api.core.CqlIdentifier getKeyspaceId()
      The keyspace used in the queries generated by this helper.
      com.datastax.oss.driver.api.core.CqlIdentifier getTableId()
      The table used in the queries generated by this helper.
      com.datastax.oss.driver.api.querybuilder.insert.RegularInsert insert()
      Builds an insert query for this entity.
      com.datastax.oss.driver.api.querybuilder.select.Select selectByPrimaryKey()
      Builds a select query to fetch an instance of the entity by primary key (partition key + clustering columns).
      com.datastax.oss.driver.api.querybuilder.select.Select selectStart()
      Builds the beginning of a select query to fetch one or more instances of the entity.
      <SettableT extends com.datastax.oss.driver.api.core.data.SettableByName<SettableT>>
      SettableT      		 set​(EntityT entity, SettableT target, NullSavingStrategy nullSavingStrategy)
      Deprecated.
      Use set(Object, SettableByName, NullSavingStrategy, boolean) instead.
      default <SettableT extends com.datastax.oss.driver.api.core.data.SettableByName<SettableT>>
      SettableT      		 set​(EntityT entity, SettableT target, NullSavingStrategy nullSavingStrategy, boolean lenient)
      Sets the properties of an entity instance into a target data structure.
      com.datastax.oss.driver.api.querybuilder.update.Update updateByPrimaryKey()
      Builds a Update query to update an instance of the entity by primary key (partition key + clustering columns).
      com.datastax.oss.driver.api.querybuilder.update.Update updateStart()
      Builds the beginning of a Update query to update an entity.

    • Method Detail

      • set

        @NonNull
default <SettableT extends com.datastax.oss.driver.api.core.data.SettableByName<SettableT>> SettableT set​(@NonNull
                                                                                                          EntityT entity,
                                                                                                          @NonNull
                                                                                                          SettableT target,
                                                                                                          @NonNull
                                                                                                          NullSavingStrategy nullSavingStrategy,
                                                                                                          boolean lenient)
        Sets the properties of an entity instance into a target data structure.

        The generated code will attempt to write all entity properties in the target data structure. For example: 

        
 target = target.set("id", entity.getId(), UUID.class);
 target = target.set("name", entity.getName(), String.class);
 ...
        The column names are inferred from the naming strategy for this entity.

        The target will typically be one of the built-in driver subtypes: BoundStatement, BoundStatementBuilder or UdtValue. Note that the default BoundStatement implementation is immutable, therefore this argument won't be modified in-place: you need to use the return value to get the resulting structure.

        If lenient is true, the mapper will operate on a best-effort basis and attempt to write all entity properties that have a matching column in the target, leaving unmatched properties untouched. Beware that this may result in a partially-populated target.

        If lenient is false, then the target must contain a matching column for every property in the entity definition, except computed ones. If such a column is not found, an IllegalArgumentException will be thrown.

        Parameters:
        entity - the entity that the values will be read from.
        target - the data structure to fill.
        lenient - whether to tolerate incomplete targets.
        Returns:
        the data structure resulting from the assignments. This is useful for immutable target implementations (see above), otherwise it will be the same as target.
        Throws:
        IllegalArgumentException - if lenient is false and the target does not contain matching columns for every entity property.

      • get

        @NonNull
default EntityT get​(@NonNull
                    com.datastax.oss.driver.api.core.data.GettableByName source,
                    boolean lenient)
        Gets values from a data structure to fill an entity instance.

        The generated code will attempt to read all entity properties from the source data structure. For example: 

        
 User returnValue = new User();
 returnValue.setId(source.get("id", UUID.class));
 returnValue.setName(source.get("name", String.class));
 ...
        The column names are inferred from the naming strategy for this entity.

        The source will typically be one of the built-in driver subtypes: Row or UdtValue (BoundStatement and BoundStatementBuilder are also possible, although it's less likely that data would be read back from them in this manner).

        If lenient is true, the mapper will operate on a best-effort basis and attempt to read all entity properties that have a matching column in the source, leaving unmatched properties untouched. Beware that this may result in a partially-populated entity instance.

        If lenient is false, then the source must contain a matching column for every property in the entity definition, including computed ones. If such a column is not found, an IllegalArgumentException will be thrown.

        Parameters:
        source - the data structure to read from.
        lenient - whether to tolerate incomplete sources.
        Returns:
        the resulting entity.
        Throws:
        IllegalArgumentException - if lenient is false and the source does not contain matching columns for every entity property.

      • insert

        @NonNull
com.datastax.oss.driver.api.querybuilder.insert.RegularInsert insert()
        Builds an insert query for this entity.

        The returned query is roughly the equivalent of: 

        
 QueryBuilder.insertInto(keyspaceId, tableId)
     .value("id", QueryBuilder.bindMarker("id"))
     .value("name", QueryBuilder.bindMarker("name"))
     ...
        All mapped properties of the entity are included as bindable values (the bind markers have the same names as the columns).

        The column names are inferred from the naming strategy for this entity.

        The keyspace and table identifiers are those of the DAO that this helper was obtained from; if the DAO was built without a specific keyspace and table, the query doesn't specify a keyspace, and the table name is inferred from the naming strategy.

      • updateStart

        @NonNull
com.datastax.oss.driver.api.querybuilder.update.Update updateStart()
        Builds the beginning of a Update query to update an entity.

        This is the same as updateByPrimaryKey() ()}, but without the WHERE clause. This would typically not be executed as-is, but instead completed with a custom WHERE clause (either added with the query builder DSL, or concatenated to the built query).

      • updateByPrimaryKey

        @NonNull
com.datastax.oss.driver.api.querybuilder.update.Update updateByPrimaryKey()
        Builds a Update query to update an instance of the entity by primary key (partition key + clustering columns).

        The returned query is roughly the equivalent of: 

        
 QueryBuilder.update(keyspaceId, tableId)
     .setColumn("description", QueryBuilder.bindMarker("description"))
     ... // (other non-PK columns)
     .where(Relation.column("id").isEqualTo(QueryBuilder.bindMarker("id"))
     ... // (other PK columns)
        All non-PK properties of the entity are set, with bind markers that have the same names as the columns.

        All components of the primary key are listed in the WHERE clause as bindable values (the bind markers have the same names as the columns). They are listed in the natural order, i.e. partition key columns first, followed by clustering columns (in the order defined by the PartitionKey and ClusteringColumn annotations on the entity class).

        The keyspace and table identifiers are those of the DAO that this helper was obtained from; if the DAO was built without a specific keyspace and table, the query doesn't specify a keyspace, and the table name is inferred from the naming strategy.

      • selectByPrimaryKey

        @NonNull
com.datastax.oss.driver.api.querybuilder.select.Select selectByPrimaryKey()
        Builds a select query to fetch an instance of the entity by primary key (partition key + clustering columns).

        The returned query is roughly the equivalent of: 

        
 QueryBuilder.selectFrom(keyspaceId, tableId)
     .column("id")
     .column("name")
     .whereColumn("id").isEqualTo(QueryBuilder.bindMarker("id"));
   ...
        All mapped properties of the entity are included in the result set.

        All components of the primary key are listed in the WHERE clause as bindable values (the bind markers have the same names as the columns). They are listed in the natural order, i.e. partition key columns first, followed by clustering columns (in the order defined by the PartitionKey and ClusteringColumn annotations on the entity class).

        The keyspace and table identifiers are those of the DAO that this helper was obtained from; if the DAO was built without a specific keyspace and table, the query doesn't specify a keyspace, and the table name is inferred from the naming strategy.

      • selectStart

        @NonNull
com.datastax.oss.driver.api.querybuilder.select.Select selectStart()
        Builds the beginning of a select query to fetch one or more instances of the entity.

        This is the same as selectByPrimaryKey(), but without the WHERE clause. This would typically not be executed as-is, but instead completed with a custom WHERE clause (either added with the query builder DSL, or concatenated to the built query).

      • deleteByPrimaryKey

        @NonNull
com.datastax.oss.driver.api.querybuilder.delete.Delete deleteByPrimaryKey()
        Builds a delete query to delete an instance of the entity by primary key (partition key + clustering columns).

        The returned query is roughly the equivalent of: 

        
 Delete delete = QueryBuilder.deleteFrom(keyspaceId, tableId)
     .whereColumn("id").isEqualTo(QueryBuilder.bindMarker("id"));
        All components of the primary key are listed in the WHERE clause as bindable values (the bind markers have the same names as the columns). They are listed in the natural order, i.e. partition key columns first, followed by clustering columns (in the order defined by the PartitionKey and ClusteringColumn annotations on the entity class).

        The keyspace and table identifiers are those of the DAO that this helper was obtained from; * if the DAO was built without a specific keyspace and table, the query doesn't specify a keyspace, and the table name is inferred from the naming strategy.

      • getKeyspaceId

        @Nullable
com.datastax.oss.driver.api.core.CqlIdentifier getKeyspaceId()
        The keyspace used in the queries generated by this helper.

        This is determined by the following rules:

        • If the DAO that this helper belongs to was created with a keyspace (see DaoKeyspace), use that;
        • Otherwise, if Entity.defaultKeyspace() is set for the entity class, use that;
        • Otherwise, return null.

      • getTableId

        @NonNull
com.datastax.oss.driver.api.core.CqlIdentifier getTableId()
        The table used in the queries generated by this helper.

        This is determined by the following rules:

        • If the DAO that this helper belongs to was created with a table (see DaoTable), use that;
        • Otherwise, if the entity class is annotated with CqlName, use that;
        • Otherwise, use the name of the entity class, transformed by its NamingStrategy.

      • getEntityClass

        @NonNull
Class<EntityT> getEntityClass()
        The class of the mapped entity.