Module is.codion.framework.db.core

Package is.codion.framework.db

Interface EntityConnection

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

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. executeFunction(FunctionType) and executeProcedure(ProcedureType) do not perform any transaction control but insert(Entity), insert(List), update(Entity), update(List), delete(Key) and delete(Collection) perform a commit unless they are run within a transaction. A static helper class for mass data manipulation.

See Also:

beginTransaction(), rollbackTransaction(), commitTransaction()

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 each EntityConnection.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 each EntityConnection.InsertEntities.batchSize(int) number of inserts, unless the destination connection has an open transaction.

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
static EntityConnection.CopyEntities	copyEntities(EntityConnection source, EntityConnection destination, EntityType... entityTypes)	Creates a new EntityConnection.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> R	executeFunction(FunctionType<C,T,R> functionType)	Executes the function with the given type with no arguments
<C extends EntityConnection,T,R> R	executeFunction(FunctionType<C,T,R> functionType, T argument)	Executes the function with the given type
<C extends EntityConnection,T> void	executeProcedure(ProcedureType<C,T> procedureType)	Executes the procedure with the given type with no arguments
<C extends EntityConnection,T> void	executeProcedure(ProcedureType<C,T> procedureType, T argument)	Executes the procedure with the given type
<T,R,P> R	fillReport(ReportType<T,R,P> reportType, P reportParameters)	Takes a ReportType object using a JDBC datasource and returns an initialized report result object
Key	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 new EntityConnection.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 by attribute from the given entity, returns null if no blob data is found.
void	rollbackTransaction()	Performs a rollback and ends the current transaction
int	rowCount(Condition condition)	Selects the number of rows returned based on the given condition
List<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 a ColumnProperty.
<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 a ColumnProperty.
<T> List<Entity>	select(Attribute<T> attribute, Collection<T> values)	Selects entities based on a single attribute condition, using values OR'ed together
<T> List<Entity>	select(Attribute<T> attribute, T value)	Selects entities based on a single attribute condition
Entity	select(Key key)	Selects an entity by key
List<Entity>	select(Collection<Key> keys)	Selects entities based on the given keys
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 entityTypes
Entity	selectSingle(Condition condition)	Selects a single entity based on the specified condition
<T> Entity	selectSingle(Attribute<T> attribute, T value)	Selects a single entity
void	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 the UpdateCondition.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)	Writes blobData in the blob field specified by the property identified by attribute 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 interface AutoCloseable

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 a SelectCondition 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 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

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

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 type

T - 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 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

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 exception

UpdateException - in case 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

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 exception

UpdateException - in case 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(UpdateCondition condition)
    throws DatabaseException

Performs an update based on the given condition, updating the attributes found in the UpdateCondition.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 exception

DeleteException - 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 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(Attribute<T> attribute)
            throws DatabaseException

Selects ordered and distinct non-null values of the given attribute, note that the attribute must be associated with a ColumnProperty.

Type Parameters:

T - the value type

Parameters:

attribute - attribute

Returns:

the values of the given attribute

Throws:

DatabaseException - in case of a database exception

IllegalArgumentException - in case the given property is not a column based attribute

UnsupportedOperationException - 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 a ColumnProperty.

Type Parameters:

T - the value type

Parameters:

attribute - attribute

condition - the condition, null if all values should be selected

Returns:

the values of the given attribute

Throws:

DatabaseException - in case of a database exception

IllegalArgumentException - in case the given property is not a column based attribute

UnsupportedOperationException - 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 condition

value - the value to use in the condition

Returns:

an entity of the type entityType, having the value of attribute as value

Throws:

DatabaseException - in case of a database exception

RecordNotFoundException - in case the entity was not found

MultipleRecordsFoundException - 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 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

select

List<Entity> select(Collection<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

<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 attribute

value - the value to use as condition

Returns:

entities of the type entityType based on attribute and values

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, using values OR'ed together

Type Parameters:

T - the value type

Parameters:

attribute - the condition attribute

values - the values to use as condition

Returns:

entities of the type entityType based on attribute and values

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

Report.fillReport(java.sql.Connection, Object)

writeBlob

void writeBlob(Key primaryKey,
               Attribute<byte[]> blobAttribute,
               byte[] blobData)
        throws DatabaseException

Writes blobData in the blob field specified by the property identified by attribute for the given entity

Parameters:

primaryKey - the primary key of the entity for which to write the blob field

blobAttribute - the blob attribute

blobData - the blob data

Throws:

UpdateException - in case multiple rows were affected

DatabaseException - in case of a database exception

readBlob

byte[] readBlob(Key primaryKey,
                Attribute<byte[]> blobAttribute)
         throws DatabaseException

Reads the blob specified by the property identified by attribute from the given entity, returns null if no blob data is found.

Parameters:

primaryKey - the primary key of the entity

blobAttribute - 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 new EntityConnection.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. Call EntityConnection.CopyEntities.execute() to perform the copy operation.

Parameters:

source - the source connection

destination - the destination connection

entityTypes - the entity types to copy

Returns:

a new EntityConnection.CopyEntities instance

insertEntities

static EntityConnection.InsertEntities insertEntities(EntityConnection connection,
                                                      Iterator<Entity> entities)

Creates a new EntityConnection.InsertEntities 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.InsertEntities.execute() to perform the insert operation.

Parameters:

connection - the entity connection to use when inserting

entities - the entities to insert

Returns:

a new EntityConnection.InsertEntities instance