Interface KeyGenerator

All Known Subinterfaces:
KeyGenerator.Identity

public interface KeyGenerator
Generates primary key values for entities on insert. KeyGenerators fall into two categories, one which fetches or generates the primary key value before the row is inserted and one where the underlying database automatically sets the primary key value on insert, i.e. with a table trigger or identity columns. Implementations should override either beforeInsert() or afterInsert(). If inserted() returns true the primary key value should be included in the insert statement, meaning that beforeInsert(Entity, DatabaseConnection) should be used to populate the entity's primary key values. If inserted() returns false then it is assumed that the database generates the primary key values automatically, meaning that afterInsert() should be used to fetch the generated primary key value and populate the entity instance accordingly.
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Marker interface indicating that a key generator is based on an identity column.
  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    afterInsert(Entity entity, DatabaseConnection connection, Statement insertStatement)
    Prepares the given entity after insert, that is, fetches automatically generated primary key values and populates the entity's primary key.
    automatic(String valueSource)
    Instantiates a primary key generator which fetches automatically incremented primary key values after insert.
    default void
    beforeInsert(Entity entity, DatabaseConnection connection)
    Prepares the given entity for insert, that is, generates and fetches any required primary key values and populates the entity's primary key.
    Returns a primary key generator based on an IDENTITY type column.
    default boolean
    The default implementation returns true.
    queried(String query)
    Instantiates a primary key generator which fetches primary key values using the given query prior to insert.
    default boolean
    Specifies whether the insert statement should return the primary key column values via the resulting Statement.getGeneratedKeys() resultSet, accessible in afterInsert(Entity, DatabaseConnection, Statement).
    sequence(String sequenceName)
    Instantiates a primary key generator which fetches primary key values from a sequence prior to insert.
  • Method Details

    • inserted

      default boolean inserted()
      The default implementation returns true.
      Returns:
      true if the primary key value should be included in the insert query when entities using this key generator is inserted
    • beforeInsert

      default void beforeInsert(Entity entity, DatabaseConnection connection) throws SQLException
      Prepares the given entity for insert, that is, generates and fetches any required primary key values and populates the entity's primary key. The default implementation does nothing, override to implement.
      Parameters:
      entity - the entity about to be inserted
      connection - the connection to use
      Throws:
      SQLException - in case of an exception
    • afterInsert

      default void afterInsert(Entity entity, DatabaseConnection connection, Statement insertStatement) throws SQLException
      Prepares the given entity after insert, that is, fetches automatically generated primary key values and populates the entity's primary key. The default implementation does nothing, override to implement.
      Parameters:
      entity - the inserted entity
      connection - the connection to use
      insertStatement - the insert statement
      Throws:
      SQLException - in case of an exception
    • returnGeneratedKeys

      default boolean returnGeneratedKeys()
      Specifies whether the insert statement should return the primary key column values via the resulting Statement.getGeneratedKeys() resultSet, accessible in afterInsert(Entity, DatabaseConnection, Statement). The default implementation returns false.
      Returns:
      true if the primary key column values should be returned via the insert statement resultSet
      See Also:
    • sequence

      static KeyGenerator sequence(String sequenceName)
      Instantiates a primary key generator which fetches primary key values from a sequence prior to insert. Note that if the primary key value of the entity being inserted is already populated this key generator does nothing, that is, it does not overwrite a manually set primary key value.
      Parameters:
      sequenceName - the sequence name
      Returns:
      a sequence based primary key generator
    • queried

      static KeyGenerator queried(String query)
      Instantiates a primary key generator which fetches primary key values using the given query prior to insert. Note that if the primary key value of the entity being inserted is already populated this key generator does nothing, that is, it does not overwrite a manually set primary key value.
      Parameters:
      query - a query for retrieving the primary key value
      Returns:
      a query based primary key generator
    • automatic

      static KeyGenerator automatic(String valueSource)
      Instantiates a primary key generator which fetches automatically incremented primary key values after insert.
      Parameters:
      valueSource - the value source, whether a sequence or a table name
      Returns:
      an auto-increment based primary key generator
    • identity

      static KeyGenerator.Identity identity()
      Returns a primary key generator based on an IDENTITY type column.
      Returns:
      a generated primary key generator
      See Also: