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

Interface EntityConnection

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
HttpEntityConnection, LocalEntityConnection
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:

  • Field Details

    • DEFAULT_QUERY_TIMEOUT_SECONDS

      static final int DEFAULT_QUERY_TIMEOUT_SECONDS
      The default query timeout in seconds
      See Also:

  • Method Details

    • entities

      Entities entities()
      Returns:
      the underlying domain entities

    • 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

    • startTransaction

      void startTransaction()
      Starts a transaction on this connection.

      NOTE: A transaction should ALWAYS be used in conjunction with a try/catch block,
      in order for the transaction to be properly ended in case of an exception.
      A transaction should always be started OUTSIDE the try/catch block. 

       
 EntityConnection connection = connectionProvider().connection();

 connection.startTransaction(); // Very important, should NOT be inside the try block
 try {
     connection.insert(entity);

     connection.commitTransaction();
 }
 catch (DatabaseException e) {
     connection.rollbackTransaction();
     throw e;
 }
 catch (Exception e) {          // Very important to catch Exception
     connection.rollbackTransaction();
     throw new RuntimeException(e);
 }
      Throws:
      IllegalStateException - if a transaction is already open
      See Also:

    • rollbackTransaction

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

    • commitTransaction

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

    • 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(FunctionType<C,T,R> functionType) throws 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:
      DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T, R> R execute(FunctionType<C,T,R> functionType, T argument) throws 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:
      DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T> void execute(ProcedureType<C,T> procedureType) throws 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:
      DatabaseException - in case anything goes wrong during the execution

    • execute

      <C extends EntityConnection, T> void execute(ProcedureType<C,T> procedureType, T argument) throws 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:
      DatabaseException - in case anything goes wrong during the execution

    • insert

      Entity.Key insert(Entity entity) throws 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:
      DatabaseException - in case of a database exception

    • insertSelect

      Entity insertSelect(Entity entity) throws 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:
      DatabaseException - in case of a database exception

    • insert

      Collection<Entity.Key> insert(Collection<Entity> entities) throws 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:
      DatabaseException - in case of a database exception

    • insertSelect

      Collection<Entity> insertSelect(Collection<Entity> entities) throws 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:
      DatabaseException - in case of a database exception

    • update

      void update(Entity entity) throws 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:
      DatabaseException - in case of a database exception
      UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      RecordModifiedException - in case the entity has been modified or deleted by another user

    • updateSelect

      Entity updateSelect(Entity entity) throws 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:
      DatabaseException - in case of a database exception
      UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      RecordModifiedException - in case the entity has been modified or deleted by another user

    • update

      void update(Collection<Entity> entities) throws 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:
      DatabaseException - in case of a database exception
      UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      RecordModifiedException - in case an entity has been modified or deleted by another user

    • updateSelect

      Collection<Entity> updateSelect(Collection<Entity> entities) throws 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:
      DatabaseException - in case of a database exception
      UpdateException - in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rows
      RecordModifiedException - in case an entity has been modified or deleted by another user

    • update

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

    • delete

      void delete(Entity.Key key) throws 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:
      DatabaseException - in case of a database exception
      DeleteException - in case no row or multiple rows were deleted

    • delete

      void delete(Collection<Entity.Key> keys) throws 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:
      DatabaseException - in case of a database exception
      DeleteException - in case the number of deleted rows does not match the number of keys

    • delete

      int delete(Condition condition) throws 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:
      DatabaseException - in case of a database exception

    • select

      <T> List<T> select(Column<T> column) throws 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:
      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(Column<T> column, Condition condition) throws 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:
      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(Column<T> column, EntityConnection.Select select) throws 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:
      DatabaseException - in case of a database exception
      IllegalArgumentException - in case the column and select condition entity types don't match
      UnsupportedOperationException - in case the entity uses a custom column clause or if the column represents an aggregate value

    • select

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

    • selectSingle

      Entity selectSingle(Condition condition) throws 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:
      DatabaseException - in case of a database exception
      RecordNotFoundException - in case the entity was not found
      MultipleRecordsFoundException - in case multiple entities were found

    • selectSingle

      Entity selectSingle(EntityConnection.Select select) throws 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:
      DatabaseException - in case of a database exception
      RecordNotFoundException - in case the entity was not found
      MultipleRecordsFoundException - in case multiple entities were found

    • select

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

    • select

      List<Entity> select(Condition condition) throws 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:
      DatabaseException - in case of a database exception

    • select

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

    • dependencies

      Map<EntityType,Collection<Entity>> dependencies(Collection<Entity> entities) throws 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
      DatabaseException - in case of a database exception
      See Also:

    • count

      int count(EntityConnection.Count count) throws 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:
      DatabaseException - in case of a database exception

    • report

      <T, R, P> R report(ReportType<T,R,P> reportType, P reportParameters) throws DatabaseException, 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:
      DatabaseException - in case of a database exception
      ReportException - in case of a report exception
      See Also:

    • transaction

      static void transaction(EntityConnection connection, EntityConnection.Transactional transactional) throws DatabaseException
      Executes the given EntityConnection.Transactional instance within a transaction on the given connection, committing on success and rolling back on exception. Any DatabaseExceptions and RuntimeExceptions encountered are rethrown, other exceptions are rethrown as RuntimeExceptions. Note that nesting transactions will cause an IllegalStateException to be thrown, causing the outer transaction to be rolled back.
      Parameters:
      connection - the connection to use
      transactional - the transactional to run
      Throws:
      DatabaseException - in case of a database exception
      RuntimeException - in case of exceptions other than DatabaseException

    • transaction

      static <T> T transaction(EntityConnection connection, EntityConnection.TransactionalResult<T> transactional) throws DatabaseException
      Executes the given EntityConnection.TransactionalResult instance within a transaction on the given connection, committing on success and rolling back on exception. Any DatabaseExceptions and RuntimeExceptions encountered are rethrown, other exceptions are rethrown as RuntimeExceptions.
      Type Parameters:
      T - the result type
      Parameters:
      connection - the connection to use
      transactional - the transactional to run
      Returns:
      the result
      Throws:
      DatabaseException - in case of a database exception
      RuntimeException - in case of exceptions other than DatabaseException

    • batchCopy

      static EntityConnection.BatchCopy.Builder batchCopy(EntityConnection source, EntityConnection destination)
      Creates a new EntityConnection.BatchCopy.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.BatchCopy.Builder.execute() to perform the copy operation.
      Parameters:
      source - the source connection
      destination - the destination connection
      Returns:
      a new EntityConnection.BatchCopy.Builder instance

    • batchInsert

      static EntityConnection.BatchInsert.Builder batchInsert(EntityConnection connection, Iterator<Entity> entities)
      Creates a new EntityConnection.BatchInsert instance based on the given iterator, 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.BatchInsert.execute() to perform the insert operation.
      Parameters:
      connection - the entity connection to use when inserting
      entities - the entities to insert
      Returns:
      a new EntityConnection.BatchInsert.Builder instance