Module is.codion.framework.domain

Package is.codion.framework.domain.entity

Interface KeyGenerator

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 record 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 isInserted() returns true the primary key value should be included in the insert statement, meaning that beforeInsert(Entity, List, DatabaseConnection) should be used to populate the entity's primary key values. If isInserted() 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.

Method Summary

Modifier and Type	Method	Description
default void	afterInsert(Entity entity, List<ColumnProperty<?>> primaryKeyProperties, 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.
static KeyGenerator	automatic(String valueSource)	Instantiates a primary key generator which fetches automatically incremented primary key values after insert.
default void	beforeInsert(Entity entity, List<ColumnProperty<?>> primaryKeyProperties, 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.
static KeyGenerator	identity()	Instantiates a primary key generator based on an IDENTITY type column.
static KeyGenerator	increment(String tableName, String columnName)	Instantiates a primary key generator which fetches the current maximum primary key value and increments it by one prior to insert.
default boolean	isInserted()	The default implementation returns true.
static KeyGenerator	queried(String query)	Instantiates a primary key generator which fetches primary key values using the given query prior to insert.
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, List, DatabaseConnection, Statement).
static KeyGenerator	sequence(String sequenceName)	Instantiates a primary key generator which fetches primary key values from a sequence prior to insert.

Method Detail

isInserted

default boolean isInserted()

The default implementation returns true.

Returns:

true if the primary key value should be included in the insert query when entities of this type are inserted

beforeInsert

default void beforeInsert(Entity entity,
                          List<ColumnProperty<?>> primaryKeyProperties,
                          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

primaryKeyProperties - the primary key properties of the entity about to be inserted

connection - the connection to use

Throws:

SQLException - in case of an exception

afterInsert

default void afterInsert(Entity entity,
                         List<ColumnProperty<?>> primaryKeyProperties,
                         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

primaryKeyProperties - the primary key properties of the entity about to be inserted

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, List, 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:

Statement.getGeneratedKeys(), Connection.prepareStatement(String, int)

increment

static KeyGenerator increment(String tableName,
                              String columnName)

Instantiates a primary key generator which fetches the current maximum primary key value and increments it by one 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:

tableName - the table name

columnName - the primary key column name

Returns:

an incrementing primary key generator

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()

Instantiates a primary key generator based on an IDENTITY type column.

Returns:

a generated primary key generator

See Also:

Statement.getGeneratedKeys()