Module is.codion.framework.db.core
Package is.codion.framework.db

Interface EntityConnection

All Superinterfaces:
AutoCloseable
public interface EntityConnection extends AutoCloseable
A connection to a database, for querying and manipulating Entitys and running database operations specified by a single Domain model. execute(FunctionType) and execute(ProcedureType) do not perform any transaction control whereas the select, insert, update and delete methods perform a commit unless they are run within a transaction. A static helper class for mass data manipulation.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    EntityConnection.Copy
    Copies a set of entities between a source and destination connection, performing a commit after each batchSize number of inserts, unless the destination connection has an open transaction.
    static interface 
    EntityConnection.Count
    A class encapsulating count query parameters.
    static interface 
    EntityConnection.Insert
    Inserts entities in batches, performing a commit after each batchSize number of inserts, unless the destination connection has an open transaction.
    static interface 
    EntityConnection.Select
    A class encapsulating select query parameters.
    static interface 
    EntityConnection.Update
    A class encapsulating a where clause along with columns and their associated values for update.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_QUERY_TIMEOUT_SECONDS
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    beginTransaction()
    Begins a transaction on this connection
    void
    close()
    Performs a rollback and disconnects this connection
    void
    commitTransaction()
    Performs a commit and ends the current transaction
    boolean
    connected()
     
    static EntityConnection.Copy.Builder
    copyEntities(EntityConnection source, EntityConnection destination)
    Creates a new EntityConnection.Copy.Builder instance for copying entities from source to destination, with a default batch size of 100.
    int
    count(EntityConnection.Count count)
    Counts the number of rows returned based on the given count conditions
    int
    delete(is.codion.framework.domain.entity.condition.Condition condition)
    Deletes the entities specified by the given condition.
    void
    delete(is.codion.framework.domain.entity.Entity.Key key)
    Deletes the entity with the given primary key.
    void
    delete(Collection<is.codion.framework.domain.entity.Entity.Key> keys)
    Deletes the entities with the given primary keys.
    Map<is.codion.framework.domain.entity.EntityType,Collection<is.codion.framework.domain.entity.Entity>>
    dependencies(Collection<? extends is.codion.framework.domain.entity.Entity> entities)
    Selects the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityTypes
    is.codion.framework.domain.entity.Entities
    entities()
     
    <C extends EntityConnection, T, R>
    R
    execute(is.codion.common.db.operation.FunctionType<C,T,R> functionType)
    Executes the function with the given type with no arguments
    <C extends EntityConnection, T, R>
    R
    execute(is.codion.common.db.operation.FunctionType<C,T,R> functionType, T argument)
    Executes the function with the given type
    <C extends EntityConnection, T>
    void
    execute(is.codion.common.db.operation.ProcedureType<C,T> procedureType)
    Executes the procedure with the given type with no arguments
    <C extends EntityConnection, T>
    void
    execute(is.codion.common.db.operation.ProcedureType<C,T> procedureType, T argument)
    Executes the procedure with the given type
    is.codion.framework.domain.entity.Entity.Key
    insert(is.codion.framework.domain.entity.Entity entity)
    Inserts the given entity, returning the primary key.
    Collection<is.codion.framework.domain.entity.Entity.Key>
    insert(Collection<? extends is.codion.framework.domain.entity.Entity> entities)
    Inserts the given entities, returning the primary keys.
    static EntityConnection.Insert.Builder
    insertEntities(EntityConnection connection, Iterator<is.codion.framework.domain.entity.Entity> entities)
    Creates a new EntityConnection.Insert instance the given entities, with a default batch size of 100.
    is.codion.framework.domain.entity.Entity
    insertSelect(is.codion.framework.domain.entity.Entity entity)
    Inserts the given entity, returning the inserted entity.
    Collection<is.codion.framework.domain.entity.Entity>
    insertSelect(Collection<? extends is.codion.framework.domain.entity.Entity> entities)
    Inserts the given entities, returning the inserted entities.
    boolean
    isQueryCacheEnabled()
     
    <T, R, P> R
    report(is.codion.common.db.report.ReportType<T,R,P> reportType, P reportParameters)
    Takes a ReportType object using a JDBC datasource and returns an initialized report result object
    void
    rollbackTransaction()
    Performs a rollback and ends the current transaction
    List<is.codion.framework.domain.entity.Entity>
    select(EntityConnection.Select select)
    Selects entities based on the given select
    <T> List<T>
    select(is.codion.framework.domain.entity.attribute.Column<T> column)
    Selects ordered and distinct non-null values of the given column.
    <T> List<T>
    select(is.codion.framework.domain.entity.attribute.Column<T> column, EntityConnection.Select select)
    Selects distinct non-null values of the given column.
    <T> List<T>
    select(is.codion.framework.domain.entity.attribute.Column<T> column, is.codion.framework.domain.entity.condition.Condition condition)
    Selects distinct non-null values of the given column.
    List<is.codion.framework.domain.entity.Entity>
    select(is.codion.framework.domain.entity.condition.Condition condition)
    Selects entities based on the given condition
    is.codion.framework.domain.entity.Entity
    select(is.codion.framework.domain.entity.Entity.Key key)
    Selects an entity by key
    Collection<is.codion.framework.domain.entity.Entity>
    select(Collection<is.codion.framework.domain.entity.Entity.Key> keys)
    Selects entities based on the given keys
    is.codion.framework.domain.entity.Entity
    selectSingle(EntityConnection.Select select)
    Selects a single entity based on the specified select
    is.codion.framework.domain.entity.Entity
    selectSingle(is.codion.framework.domain.entity.condition.Condition condition)
    Selects a single entity based on the specified condition
    void
    setQueryCacheEnabled(boolean queryCacheEnabled)
    Controls the enabled state of the query result cache.
    boolean
    transactionOpen()
     
    int
    update(EntityConnection.Update update)
    Performs an update based on the given update, updating the columns found in the EntityConnection.Update.columnValues() map, with the associated values.
    void
    update(is.codion.framework.domain.entity.Entity entity)
    Updates the given entity based on its attribute values.
    void
    update(Collection<? extends is.codion.framework.domain.entity.Entity> entities)
    Updates the given entities based on their attribute values.
    is.codion.framework.domain.entity.Entity
    updateSelect(is.codion.framework.domain.entity.Entity entity)
    Updates the given entity based on its attribute values.
    Collection<is.codion.framework.domain.entity.Entity>
    updateSelect(Collection<? extends is.codion.framework.domain.entity.Entity> entities)
    Updates the given entities based on their attribute values.
    is.codion.common.user.User
    user()
     

  • Field Details

    • DEFAULT_QUERY_TIMEOUT_SECONDS

      static final int DEFAULT_QUERY_TIMEOUT_SECONDS
      See Also:

  • Method Details

    • entities

      is.codion.framework.domain.entity.Entities entities()
      Returns:
      the underlying domain entities

    • user

      is.codion.common.user.User user()
      Returns:
      the user being used by this connection

    • connected

      boolean connected()
      Returns:
      true if the connection has been established and is valid

    • close

      void close()
      Performs a rollback and disconnects this connection
      Specified by:
      close in interface AutoCloseable

    • transactionOpen

      boolean transactionOpen()
      Returns:
      true if a transaction is open, false otherwise

    • beginTransaction

      void beginTransaction()
      Begins a transaction on this connection
      Throws:
      IllegalStateException - if a transaction is already open

    • rollbackTransaction

      void rollbackTransaction()
      Performs a rollback and ends the current transaction
      Throws:
      IllegalStateException - in case a transaction is not open

    • commitTransaction

      void commitTransaction()
      Performs a commit and ends the current transaction
      Throws:
      IllegalStateException - in case a transaction is not open

    • setQueryCacheEnabled

      void setQueryCacheEnabled(boolean queryCacheEnabled)
      Controls the enabled state of the query result cache. Queries are cached on a EntityConnection.Select basis, but never when selecting for update. The cache is cleared when disabled.
      Parameters:
      queryCacheEnabled - the result cache state

    • isQueryCacheEnabled

      boolean isQueryCacheEnabled()
      Returns:
      true if the query cache is enabled
      See Also:

    • execute

      <C extends EntityConnection, T, R> R execute(is.codion.common.db.operation.FunctionType<C,T,R> functionType) throws is.codion.common.db.exception.DatabaseException
      Executes the function with the given type with no arguments
      Type Parameters:
      C - the connection type
      T - the argument type
      R - the return value type
      Parameters:
      functionType - the function type
      Returns:
      the function return value
      Throws:
      is.codion.common.db.exception.DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T, R> R execute(is.codion.common.db.operation.FunctionType<C,T,R> functionType, T argument) throws is.codion.common.db.exception.DatabaseException
      Executes the function with the given type
      Type Parameters:
      C - the connection type
      T - the argument type
      R - the return value type
      Parameters:
      functionType - the function type
      argument - the function argument
      Returns:
      the function return value
      Throws:
      is.codion.common.db.exception.DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T> void execute(is.codion.common.db.operation.ProcedureType<C,T> procedureType) throws is.codion.common.db.exception.DatabaseException
      Executes the procedure with the given type with no arguments
      Type Parameters:
      C - the connection type
      T - the procedure argument type
      Parameters:
      procedureType - the procedure type
      Throws:
      is.codion.common.db.exception.DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T> void execute(is.codion.common.db.operation.ProcedureType<C,T> procedureType, T argument) throws is.codion.common.db.exception.DatabaseException
      Executes the procedure with the given type
      Type Parameters:
      C - the connection type
      T - the argument type
      Parameters:
      procedureType - the procedure type
      argument - the procedure argument
      Throws:
      is.codion.common.db.exception.DatabaseException - in case anything goes wrong during the execution

    • insert

      is.codion.framework.domain.entity.Entity.Key insert(is.codion.framework.domain.entity.Entity entity) throws is.codion.common.db.exception.DatabaseException
      Inserts the given entity, returning the primary key. Performs a commit unless a transaction is open.
      Parameters:
      entity - the entity to insert
      Returns:
      the primary key of the inserted entity
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • insertSelect

      is.codion.framework.domain.entity.Entity insertSelect(is.codion.framework.domain.entity.Entity entity) throws is.codion.common.db.exception.DatabaseException
      Inserts the given entity, returning the inserted entity. Performs a commit unless a transaction is open.
      Parameters:
      entity - the entity to insert
      Returns:
      the inserted entity
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • insert

      Collection<is.codion.framework.domain.entity.Entity.Key> insert(Collection<? extends is.codion.framework.domain.entity.Entity> entities) throws is.codion.common.db.exception.DatabaseException
      Inserts the given entities, returning the primary keys. Performs a commit unless a transaction is open.
      Parameters:
      entities - the entities to insert
      Returns:
      the primary keys of the inserted entities
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • insertSelect

      Collection<is.codion.framework.domain.entity.Entity> insertSelect(Collection<? extends is.codion.framework.domain.entity.Entity> entities) throws is.codion.common.db.exception.DatabaseException
      Inserts the given entities, returning the inserted entities. Performs a commit unless a transaction is open.
      Parameters:
      entities - the entities to insert
      Returns:
      the inserted entities
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • update

      void update(is.codion.framework.domain.entity.Entity entity) throws is.codion.common.db.exception.DatabaseException
      Updates the given entity based on its attribute values. Throws an exception if the given entity is unmodified. Performs a commit unless a transaction is open.
      Parameters:
      entity - the entity to update
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      is.codion.common.db.exception.RecordModifiedException - in case the entity has been modified or deleted by another user

    • updateSelect

      is.codion.framework.domain.entity.Entity updateSelect(is.codion.framework.domain.entity.Entity entity) throws is.codion.common.db.exception.DatabaseException
      Updates the given entity based on its attribute values. Returns the updated entity. Throws an exception if the given entity is unmodified. Performs a commit unless a transaction is open.
      Parameters:
      entity - the entity to update
      Returns:
      the updated entity
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      is.codion.common.db.exception.RecordModifiedException - in case the entity has been modified or deleted by another user

    • update

      void update(Collection<? extends is.codion.framework.domain.entity.Entity> entities) throws is.codion.common.db.exception.DatabaseException
      Updates the given entities based on their attribute values. Throws an exception if any of the given entities is unmodified. Performs a commit unless a transaction is open.
      Parameters:
      entities - the entities to update
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      is.codion.common.db.exception.RecordModifiedException - in case an entity has been modified or deleted by another user

    • updateSelect

      Collection<is.codion.framework.domain.entity.Entity> updateSelect(Collection<? extends is.codion.framework.domain.entity.Entity> entities) throws is.codion.common.db.exception.DatabaseException
      Updates the given entities based on their attribute values. Returns the updated entities, in no particular order. Throws an exception if any of the given entities is unmodified. Performs a commit unless a transaction is open.
      Parameters:
      entities - the entities to update
      Returns:
      the updated entities, in no particular order
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      is.codion.common.db.exception.RecordModifiedException - in case an entity has been modified or deleted by another user

    • update

      int update(EntityConnection.Update update) throws is.codion.common.db.exception.DatabaseException
      Performs an update based on the given update, updating the columns found in the EntityConnection.Update.columnValues() map, with the associated values.
      Parameters:
      update - the update to perform
      Returns:
      the number of affected rows
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • delete

      void delete(is.codion.framework.domain.entity.Entity.Key key) throws is.codion.common.db.exception.DatabaseException
      Deletes the entity with the given primary key. Performs a commit unless a transaction is open.
      Parameters:
      key - the primary key of the entity to delete
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.DeleteException - in case no row or multiple rows were deleted

    • delete

      void delete(Collection<is.codion.framework.domain.entity.Entity.Key> keys) throws is.codion.common.db.exception.DatabaseException
      Deletes the entities with the given primary keys. This method respects the iteration order of the given collection by first deleting all entities of the first entityType encountered, then all entities of the next entityType encountered and so on. This allows the deletion of multiple entities forming a master detail hierarchy, by having the detail entities appear before their master entities in the collection. Performs a commit unless a transaction is open.
      Parameters:
      keys - the primary keys of the entities to delete
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.DeleteException - in case the number of deleted rows does not match the number of keys

    • delete

      int delete(is.codion.framework.domain.entity.condition.Condition condition) throws is.codion.common.db.exception.DatabaseException
      Deletes the entities specified by the given condition. Performs a commit unless a transaction is open.
      Parameters:
      condition - the condition specifying the entities to delete
      Returns:
      the number of deleted rows
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • select

      <T> List<T> select(is.codion.framework.domain.entity.attribute.Column<T> column) throws is.codion.common.db.exception.DatabaseException
      Selects ordered and distinct non-null values of the given column.
      Type Parameters:
      T - the value type
      Parameters:
      column - column
      Returns:
      the values of the given column
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      IllegalArgumentException - in case the given column has not associated with a table column
      UnsupportedOperationException - in case the entity uses a custom column clause or if the column represents an aggregate value

    • select

      <T> List<T> select(is.codion.framework.domain.entity.attribute.Column<T> column, is.codion.framework.domain.entity.condition.Condition condition) throws is.codion.common.db.exception.DatabaseException
      Selects distinct non-null values of the given column. The result is ordered by the selected column.
      Type Parameters:
      T - the value type
      Parameters:
      column - column
      condition - the condition
      Returns:
      the values of the given column
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      IllegalArgumentException - in case the given column is not associated with a table column
      UnsupportedOperationException - in case the entity uses a custom column clause or if the column represents an aggregate value

    • select

      <T> List<T> select(is.codion.framework.domain.entity.attribute.Column<T> column, EntityConnection.Select select) throws is.codion.common.db.exception.DatabaseException
      Selects distinct non-null values of the given column. If the select provides no order by clause the result is ordered by the selected column.
      Type Parameters:
      T - the value type
      Parameters:
      column - column
      select - the select to perform
      Returns:
      the values of the given column
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      IllegalArgumentException - in case the given column is not associated with a table column
      UnsupportedOperationException - in case the entity uses a custom column clause or if the column represents an aggregate value

    • select

      is.codion.framework.domain.entity.Entity select(is.codion.framework.domain.entity.Entity.Key key) throws is.codion.common.db.exception.DatabaseException
      Selects an entity by key
      Parameters:
      key - the key of the entity to select
      Returns:
      an entity having the key key
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.RecordNotFoundException - in case the entity was not found
      is.codion.common.db.exception.MultipleRecordsFoundException - in case multiple entities were found

    • selectSingle

      is.codion.framework.domain.entity.Entity selectSingle(is.codion.framework.domain.entity.condition.Condition condition) throws is.codion.common.db.exception.DatabaseException
      Selects a single entity based on the specified condition
      Parameters:
      condition - the condition specifying the entity to select
      Returns:
      the entities based on the given condition
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.RecordNotFoundException - in case the entity was not found
      is.codion.common.db.exception.MultipleRecordsFoundException - in case multiple entities were found

    • selectSingle

      is.codion.framework.domain.entity.Entity selectSingle(EntityConnection.Select select) throws is.codion.common.db.exception.DatabaseException
      Selects a single entity based on the specified select
      Parameters:
      select - the select to perform
      Returns:
      the entities based on the given select
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.exception.RecordNotFoundException - in case the entity was not found
      is.codion.common.db.exception.MultipleRecordsFoundException - in case multiple entities were found

    • select

      Collection<is.codion.framework.domain.entity.Entity> select(Collection<is.codion.framework.domain.entity.Entity.Key> keys) throws is.codion.common.db.exception.DatabaseException
      Selects entities based on the given keys
      Parameters:
      keys - the keys used in the condition
      Returns:
      entities based on keys
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • select

      List<is.codion.framework.domain.entity.Entity> select(is.codion.framework.domain.entity.condition.Condition condition) throws is.codion.common.db.exception.DatabaseException
      Selects entities based on the given condition
      Parameters:
      condition - the condition specifying which entities to select
      Returns:
      entities based to the given condition
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • select

      List<is.codion.framework.domain.entity.Entity> select(EntityConnection.Select select) throws is.codion.common.db.exception.DatabaseException
      Selects entities based on the given select
      Parameters:
      select - the select to perform
      Returns:
      entities based to the given select
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • dependencies

      Map<is.codion.framework.domain.entity.EntityType,Collection<is.codion.framework.domain.entity.Entity>> dependencies(Collection<? extends is.codion.framework.domain.entity.Entity> entities) throws is.codion.common.db.exception.DatabaseException
      Selects the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityTypes
      Parameters:
      entities - the entities for which to retrieve dependencies, must be of same type
      Returns:
      the entities that depend on entities
      Throws:
      IllegalArgumentException - in case the entities are not of the same type
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      See Also:
      • ForeignKeyDefinition.soft()

    • count

      int count(EntityConnection.Count count) throws is.codion.common.db.exception.DatabaseException
      Counts the number of rows returned based on the given count conditions
      Parameters:
      count - the count conditions
      Returns:
      the number of rows fitting the given count conditions
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception

    • report

      <T, R, P> R report(is.codion.common.db.report.ReportType<T,R,P> reportType, P reportParameters) throws is.codion.common.db.exception.DatabaseException, is.codion.common.db.report.ReportException
      Takes a ReportType object using a JDBC datasource and returns an initialized report result object
      Type Parameters:
      T - the report type
      R - the report result type
      P - the report parameters type
      Parameters:
      reportType - the report to fill
      reportParameters - the report parameters, if any
      Returns:
      the filled result object
      Throws:
      is.codion.common.db.exception.DatabaseException - in case of a database exception
      is.codion.common.db.report.ReportException - in case of a report exception
      See Also:
      • Report.fill(java.sql.Connection, Object)

    • copyEntities

      static EntityConnection.Copy.Builder copyEntities(EntityConnection source, EntityConnection destination)
      Creates a new EntityConnection.Copy.Builder instance for copying entities from source to destination, with a default batch size of 100. Performs a commit after each {code batchSize} number of inserts, unless the destination connection has an open transaction. Call EntityConnection.Copy.Builder.execute() to perform the copy operation.
      Parameters:
      source - the source connection
      destination - the destination connection
      Returns:
      a new EntityConnection.Copy.Builder instance

    • insertEntities

      static EntityConnection.Insert.Builder insertEntities(EntityConnection connection, Iterator<is.codion.framework.domain.entity.Entity> entities)
      Creates a new EntityConnection.Insert instance the given entities, with a default batch size of 100. Performs a commit after each batchSize number of inserts, unless the destination connection has an open transaction. Call EntityConnection.Insert.execute() to perform the insert operation.
      Parameters:
      connection - the entity connection to use when inserting
      entities - the entities to insert
      Returns:
      a new EntityConnection.Insert.Builder instance