- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
HttpEntityConnection
,LocalEntityConnection
A connection to a database, for querying and manipulating
Entity
s 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.-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
Copies a set of entities between a source and destination connection, performing a commit after eachbatchSize
number of inserts, unless the destination connection has an open transaction.static interface
Inserts entities in batches, performing a commit after eachbatchSize
number of inserts, unless the destination connection has an open transaction.static interface
A class encapsulating count query parameters.static interface
A class encapsulating select query parameters.static interface
A class encapsulating a where clause along with columns and their associated values for update. -
Field Summary
-
Method Summary
Modifier and TypeMethodDescriptionbatchCopy
(EntityConnection source, EntityConnection destination) Creates a newEntityConnection.BatchCopy.Builder
instance for copying entities from source to destination, with a default batch size of 100.batchInsert
(EntityConnection connection, Iterator<Entity> entities) Creates a newEntityConnection.BatchInsert
instance based on the given iterator, with a default batch size of 100.void
close()
Performs a rollback and disconnects this connectionvoid
Performs a commit and ends the current transactionboolean
int
count
(EntityConnection.Count count) Counts the number of rows returned based on the given count conditionsint
Deletes the entities specified by the given condition.void
delete
(Entity.Key key) Deletes the entity with the given primary key.void
delete
(Collection<Entity.Key> keys) Deletes the entities with the given primary keys.dependencies
(Collection<Entity> entities) Selects the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityTypesentities()
<C extends EntityConnection,
T, R>
Rexecute
(FunctionType<C, T, R> functionType) Executes the function with the given type with no arguments<C extends EntityConnection,
T, R>
Rexecute
(FunctionType<C, T, R> functionType, T argument) Executes the function with the given type<C extends EntityConnection,
T>
voidexecute
(ProcedureType<C, T> procedureType) Executes the procedure with the given type with no arguments<C extends EntityConnection,
T>
voidexecute
(ProcedureType<C, T> procedureType, T argument) Executes the procedure with the given typeInserts the given entity, returning the primary key.insert
(Collection<Entity> entities) Inserts the given entities, returning the primary keys.insertSelect
(Entity entity) Inserts the given entity, returning the inserted entity.insertSelect
(Collection<Entity> entities) Inserts the given entities, returning the inserted entities.boolean
<T,
R, P> R report
(ReportType<T, R, P> reportType, P reportParameters) Takes a ReportType object using a JDBC datasource and returns an initialized report result objectvoid
Performs a rollback and ends the current transactionselect
(EntityConnection.Select select) Selects entities based on the given select<T> List<T>
Selects ordered and distinct non-null values of the given column.<T> List<T>
select
(Column<T> column, EntityConnection.Select select) Selects distinct non-null values of the given column.<T> List<T>
Selects distinct non-null values of the given column.Selects entities based on the given conditionselect
(Entity.Key key) Selects an entity by keyselect
(Collection<Entity.Key> keys) Selects entities based on the givenkeys
selectSingle
(EntityConnection.Select select) Selects a single entity based on the specified selectselectSingle
(Condition condition) Selects a single entity based on the specified conditionvoid
setQueryCacheEnabled
(boolean queryCacheEnabled) Controls the enabled state of the query result cache.void
Starts a transaction on this connection.boolean
int
update
(EntityConnection.Update update) Performs an update based on the given update, updating the columns found in theEntityConnection.Update.values()
map, using the associated value.void
Updates the given entity based on its attribute values.void
update
(Collection<Entity> entities) Updates the given entities based on their attribute values.updateSelect
(Entity entity) Updates the given entity based on its attribute values.updateSelect
(Collection<Entity> entities) Updates the given entities based on their attribute values.user()
-
Field Details
-
DEFAULT_QUERY_TIMEOUT_SECONDS
static final int DEFAULT_QUERY_TIMEOUT_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 interfaceAutoCloseable
-
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
-
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 aEntityConnection.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 executeR> (FunctionType<C, T, throws DatabaseExceptionR> functionType) Executes the function with the given type with no arguments- Type Parameters:
C
- the connection typeT
- the argument typeR
- 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 executeR> (FunctionType<C, T, throws DatabaseExceptionR> functionType, T argument) Executes the function with the given type- Type Parameters:
C
- the connection typeT
- the argument typeR
- the return value type- Parameters:
functionType
- the function typeargument
- 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 DatabaseExceptionExecutes the procedure with the given type with no arguments- Type Parameters:
C
- the connection typeT
- 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 DatabaseExceptionExecutes the procedure with the given type- Type Parameters:
C
- the connection typeT
- the argument type- Parameters:
procedureType
- the procedure typeargument
- the procedure argument- Throws:
DatabaseException
- in case anything goes wrong during the execution
-
insert
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
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
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
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
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 exceptionUpdateException
- in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rowsRecordModifiedException
- in case the entity has been modified or deleted by another user
-
updateSelect
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 exceptionUpdateException
- in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rowsRecordModifiedException
- in case the entity has been modified or deleted by another user
-
update
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 exceptionUpdateException
- in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rowsRecordModifiedException
- in case an entity has been modified or deleted by another user
-
updateSelect
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 exceptionUpdateException
- in case of an unmodified entity or if there is a mismatch between expected and actual number of updated rowsRecordModifiedException
- in case an entity has been modified or deleted by another user
-
update
Performs an update based on the given update, updating the columns found in theEntityConnection.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
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 exceptionDeleteException
- in case no row or multiple rows were deleted
-
delete
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 exceptionDeleteException
- in case the number of deleted rows does not match the number of keys
-
delete
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
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 exceptionIllegalArgumentException
- in case the given column has not associated with a table columnUnsupportedOperationException
- in case the entity uses a custom column clause or if the column represents an aggregate value
-
select
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
- columncondition
- the condition- Returns:
- the values of the given column
- Throws:
DatabaseException
- in case of a database exceptionIllegalArgumentException
- in case the given column is not associated with a table columnUnsupportedOperationException
- in case the entity uses a custom column clause or if the column represents an aggregate value
-
select
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
- columnselect
- the select to perform- Returns:
- the values of the given column
- Throws:
DatabaseException
- in case of a database exceptionIllegalArgumentException
- in case the given column is not associated with a table columnUnsupportedOperationException
- in case the entity uses a custom column clause or if the column represents an aggregate value
-
select
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 exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- in case multiple entities were found
-
selectSingle
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 exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- in case multiple entities were found
-
selectSingle
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 exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- in case multiple entities were found
-
select
Selects entities based on the givenkeys
- Parameters:
keys
- the keys used in the condition- Returns:
- entities based on
keys
- Throws:
DatabaseException
- in case of a database exception
-
select
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
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 typeDatabaseException
- in case of a database exception- See Also:
-
count
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, R reportP> (ReportType<T, R, throws DatabaseException, ReportExceptionP> reportType, P reportParameters) Takes a ReportType object using a JDBC datasource and returns an initialized report result object- Type Parameters:
T
- the report typeR
- the report result typeP
- the report parameters type- Parameters:
reportType
- the report to fillreportParameters
- the report parameters, if any- Returns:
- the filled result object
- Throws:
DatabaseException
- in case of a database exceptionReportException
- in case of a report exception- See Also:
-
batchCopy
static EntityConnection.BatchCopy.Builder batchCopy(EntityConnection source, EntityConnection destination) Creates a newEntityConnection.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. CallEntityConnection.BatchCopy.Builder.execute()
to perform the copy operation.- Parameters:
source
- the source connectiondestination
- the destination connection- Returns:
- a new
EntityConnection.BatchCopy.Builder
instance
-
batchInsert
static EntityConnection.BatchInsert.Builder batchInsert(EntityConnection connection, Iterator<Entity> entities) Creates a newEntityConnection.BatchInsert
instance based on the given iterator, with a default batch size of 100. Performs a commit after eachbatchSize
number of inserts, unless the destination connection has an open transaction. CallEntityConnection.BatchInsert.execute()
to perform the insert operation.- Parameters:
connection
- the entity connection to use when insertingentities
- the entities to insert- Returns:
- a new
EntityConnection.BatchInsert.Builder
instance
-