-
- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
LocalEntityConnection
public interface EntityConnection extends AutoCloseable
A connection to a database, for querying and manipulatingEntity
s and running database operations specified by a singleDomain
model.executeFunction(FunctionType)
andexecuteProcedure(ProcedureType)
do not perform any transaction control butinsert(Entity)
,insert(List)
,update(Entity)
,update(List)
,delete(Key)
anddelete(Collection)
perform a commit unless they are run within a transaction. A static helper class for mass data manipulation.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
EntityConnection.CopyEntities
Copies a set of entities between a source and destination connection, performing a commit after eachEntityConnection.CopyEntities.batchSize(int)
number of inserts, unless the destination connection has an open transaction.static interface
EntityConnection.InsertEntities
Inserts entities in batches, performing a commit after eachEntityConnection.InsertEntities.batchSize(int)
number of inserts, unless the destination connection has an open transaction.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description void
beginTransaction()
Begins a transaction on this connectionvoid
close()
Performs a rollback and disconnects this connectionvoid
commitTransaction()
Performs a commit and ends the current transactionstatic EntityConnection.CopyEntities
copyEntities(EntityConnection source, EntityConnection destination, EntityType... entityTypes)
Creates a newEntityConnection.CopyEntities
instance for copying entities from source to destination, with a default batch size of 100.int
delete(Condition condition)
Deletes the entities specified by the given condition.void
delete(Key entityKey)
Deletes the entity with the given primary key.void
delete(Collection<Key> entityKeys)
Deletes the entities with the given primary keys.Entities
entities()
<C extends EntityConnection,T,R>
RexecuteFunction(FunctionType<C,T,R> functionType)
Executes the function with the given type with no arguments<C extends EntityConnection,T,R>
RexecuteFunction(FunctionType<C,T,R> functionType, T argument)
Executes the function with the given type<C extends EntityConnection,T>
voidexecuteProcedure(ProcedureType<C,T> procedureType)
Executes the procedure with the given type with no arguments<C extends EntityConnection,T>
voidexecuteProcedure(ProcedureType<C,T> procedureType, T argument)
Executes the procedure with the given type<T,R,P>
RfillReport(ReportType<T,R,P> reportType, P reportParameters)
Takes a ReportType object using a JDBC datasource and returns an initialized report result objectKey
insert(Entity entity)
Inserts the given entity, returning the primary key.List<Key>
insert(List<? extends Entity> entities)
Inserts the given entities, returning a list containing the primary keys in the same order as they were received.static EntityConnection.InsertEntities
insertEntities(EntityConnection connection, Iterator<Entity> entities)
Creates a newEntityConnection.InsertEntities
instance the given entities, with a default batch size of 100.boolean
isConnected()
boolean
isQueryCacheEnabled()
boolean
isTransactionOpen()
byte[]
readBlob(Key primaryKey, Attribute<byte[]> blobAttribute)
Reads the blob specified by the property identified byattribute
from the given entity, returns null if no blob data is found.void
rollbackTransaction()
Performs a rollback and ends the current transactionint
rowCount(Condition condition)
Selects the number of rows returned based on the given conditionList<Entity>
select(Condition condition)
Selects entities based on the given condition<T> List<T>
select(Attribute<T> attribute)
Selects ordered and distinct non-null values of the given attribute, note that the attribute must be associated with aColumnProperty
.<T> List<T>
select(Attribute<T> attribute, Condition condition)
Selects ordered and distinct non-null values of the given attribute, note that the attribute must be associated with aColumnProperty
.<T> List<Entity>
select(Attribute<T> attribute, Collection<T> values)
Selects entities based on a single attribute condition, usingvalues
OR'ed together<T> List<Entity>
select(Attribute<T> attribute, T value)
Selects entities based on a single attribute conditionEntity
select(Key key)
Selects an entity by keyList<Entity>
select(Collection<Key> keys)
Selects entities based on the givenkeys
Map<EntityType,Collection<Entity>>
selectDependencies(Collection<? extends Entity> entities)
Selects the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityTypesEntity
selectSingle(Condition condition)
Selects a single entity based on the specified condition<T> Entity
selectSingle(Attribute<T> attribute, T value)
Selects a single entityvoid
setQueryCacheEnabled(boolean queryCacheEnabled)
Controls the enabled state of the query result cache.int
update(UpdateCondition condition)
Performs an update based on the given condition, updating the attributes found in theUpdateCondition.attributeValues()
map, with the associated values.Entity
update(Entity entity)
Updates the given entity based on its attribute values.List<Entity>
update(List<? extends Entity> entities)
Updates the given entities based on their attribute values.User
user()
void
writeBlob(Key primaryKey, Attribute<byte[]> blobAttribute, byte[] blobData)
WritesblobData
in the blob field specified by the property identified byattribute
for the given entity
-
-
-
Method Detail
-
entities
Entities entities()
- Returns:
- the underlying domain entities
-
user
User user()
- Returns:
- the user being used by this connection
-
isConnected
boolean isConnected()
- 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
-
isTransactionOpen
boolean isTransactionOpen()
- 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 aSelectCondition
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:
setQueryCacheEnabled(boolean)
-
executeFunction
<C extends EntityConnection,T,R> R executeFunction(FunctionType<C,T,R> functionType) throws DatabaseException
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
-
executeFunction
<C extends EntityConnection,T,R> R executeFunction(FunctionType<C,T,R> functionType, T argument) throws DatabaseException
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
-
executeProcedure
<C extends EntityConnection,T> void executeProcedure(ProcedureType<C,T> procedureType) throws DatabaseException
Executes 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
-
executeProcedure
<C extends EntityConnection,T> void executeProcedure(ProcedureType<C,T> procedureType, T argument) throws DatabaseException
Executes 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
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
-
insert
List<Key> insert(List<? extends Entity> entities) throws DatabaseException
Inserts the given entities, returning a list containing the primary keys in the same order as they were received. Performs a commit unless a transaction is open.- Parameters:
entities
- the entities to insert- Returns:
- the primary key values of the inserted entities
- Throws:
DatabaseException
- in case of a database exception
-
update
Entity update(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 exceptionUpdateException
- in case 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
List<Entity> update(List<? extends 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 exceptionUpdateException
- in case 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
int update(UpdateCondition condition) throws DatabaseException
Performs an update based on the given condition, updating the attributes found in theUpdateCondition.attributeValues()
map, with the associated values.- Parameters:
condition
- the condition- Returns:
- the number of affected rows
- Throws:
DatabaseException
- in case of a dabase exception
-
delete
void delete(Key entityKey) throws DatabaseException
Deletes the entity with the given primary key. Performs a commit unless a transaction is open.- Parameters:
entityKey
- 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
void delete(Collection<Key> entityKeys) throws DatabaseException
Deletes the entities with the given primary keys. Performs a commit unless a transaction is open.- Parameters:
entityKeys
- 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
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(Attribute<T> attribute) throws DatabaseException
Selects ordered and distinct non-null values of the given attribute, note that the attribute must be associated with aColumnProperty
.- Type Parameters:
T
- the value type- Parameters:
attribute
- attribute- Returns:
- the values of the given attribute
- Throws:
DatabaseException
- in case of a database exceptionIllegalArgumentException
- in case the given property is not a column based attributeUnsupportedOperationException
- in case the entity is based on a select query
-
select
<T> List<T> select(Attribute<T> attribute, Condition condition) throws DatabaseException
Selects ordered and distinct non-null values of the given attribute, note that the attribute must be associated with aColumnProperty
.- Type Parameters:
T
- the value type- Parameters:
attribute
- attributecondition
- the condition, null if all values should be selected- Returns:
- the values of the given attribute
- Throws:
DatabaseException
- in case of a database exceptionIllegalArgumentException
- in case the given property is not a column based attributeUnsupportedOperationException
- in case the entity is based on a select query
-
selectSingle
<T> Entity selectSingle(Attribute<T> attribute, T value) throws DatabaseException
Selects a single entity- Type Parameters:
T
- the value type- Parameters:
attribute
- attribute to use as a conditionvalue
- the value to use in the condition- Returns:
- an entity of the type
entityType
, having the value ofattribute
asvalue
- Throws:
DatabaseException
- in case of a database exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- in case multiple entities were found
-
select
Entity select(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 exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- 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 exceptionRecordNotFoundException
- in case the entity was not foundMultipleRecordsFoundException
- in case multiple entities were found
-
select
List<Entity> select(Collection<Key> keys) throws DatabaseException
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
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
<T> List<Entity> select(Attribute<T> attribute, T value) throws DatabaseException
Selects entities based on a single attribute condition- Type Parameters:
T
- the value type- Parameters:
attribute
- the condition attributevalue
- the value to use as condition- Returns:
- entities of the type
entityType
based onattribute
andvalues
- Throws:
DatabaseException
- in case of a database exception
-
select
<T> List<Entity> select(Attribute<T> attribute, Collection<T> values) throws DatabaseException
Selects entities based on a single attribute condition, usingvalues
OR'ed together- Type Parameters:
T
- the value type- Parameters:
attribute
- the condition attributevalues
- the values to use as condition- Returns:
- entities of the type
entityType
based onattribute
andvalues
- Throws:
DatabaseException
- in case of a database exception
-
selectDependencies
Map<EntityType,Collection<Entity>> selectDependencies(Collection<? extends 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:
DatabaseException
- in case of a database exception- See Also:
ForeignKeyProperty.isSoftReference()
-
rowCount
int rowCount(Condition condition) throws DatabaseException
Selects the number of rows returned based on the given condition- Parameters:
condition
- the search condition- Returns:
- the number of rows fitting the given condition
- Throws:
DatabaseException
- in case of a database exception
-
fillReport
<T,R,P> R fillReport(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 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:
Report.fillReport(java.sql.Connection, Object)
-
writeBlob
void writeBlob(Key primaryKey, Attribute<byte[]> blobAttribute, byte[] blobData) throws DatabaseException
WritesblobData
in the blob field specified by the property identified byattribute
for the given entity- Parameters:
primaryKey
- the primary key of the entity for which to write the blob fieldblobAttribute
- the blob attributeblobData
- the blob data- Throws:
UpdateException
- in case multiple rows were affectedDatabaseException
- in case of a database exception
-
readBlob
byte[] readBlob(Key primaryKey, Attribute<byte[]> blobAttribute) throws DatabaseException
Reads the blob specified by the property identified byattribute
from the given entity, returns null if no blob data is found.- Parameters:
primaryKey
- the primary key of the entityblobAttribute
- the blob attribute- Returns:
- a byte array containing the blob data or null if no blob data is found
- Throws:
DatabaseException
- in case of a database exception
-
copyEntities
static EntityConnection.CopyEntities copyEntities(EntityConnection source, EntityConnection destination, EntityType... entityTypes)
Creates a newEntityConnection.CopyEntities
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.CopyEntities.execute()
to perform the copy operation.- Parameters:
source
- the source connectiondestination
- the destination connectionentityTypes
- the entity types to copy- Returns:
- a new
EntityConnection.CopyEntities
instance
-
insertEntities
static EntityConnection.InsertEntities insertEntities(EntityConnection connection, Iterator<Entity> entities)
Creates a newEntityConnection.InsertEntities
instance the given entities, with a default batch size of 100. Performs a commit after eachbatchSize
number of inserts, unless the destination connection has an open transaction. CallEntityConnection.InsertEntities.execute()
to perform the insert operation.- Parameters:
connection
- the entity connection to use when insertingentities
- the entities to insert- Returns:
- a new
EntityConnection.InsertEntities
instance
-
-