org.jminor.framework.db

Interface EntityConnection

All Known Subinterfaces:

LocalEntityConnection

public interface EntityConnection

A connection to a database, for querying and manipulating Entitys and running database operations specified by a single Domain model. executeFunction(String, Object...) and executeProcedure(String, Object...) do not perform any transaction control but insert(List), update(List) and delete(List) perform a commit unless they are run within a transaction.

See Also:

beginTransaction(), rollbackTransaction(), commitTransaction()

Method Summary

Modifier and Type	Method and Description
void	beginTransaction() Begins a transaction on this connection
void	commitTransaction() Performs a commit and ends the current transaction
void	delete(EntityCondition condition) Deletes the entities specified by the given condition.
void	delete(java.util.List<Entity.Key> entityKeys) Deletes the entities according to the given primary keys.
void	disconnect() Performs a rollback and disconnects this connection
java.util.List	executeFunction(java.lang.String functionId, java.lang.Object... arguments) Executes the function with the given id
void	executeProcedure(java.lang.String procedureId, java.lang.Object... arguments) Executes the procedure with the given id
ReportResult	fillReport(ReportWrapper reportWrapper) Takes a ReportWrapper object using a JDBC datasource and returns an initialized ReportResult object
Domain	getDomain()
User	getUser()
java.util.List<Entity.Key>	insert(java.util.List<Entity> entities) Inserts the given entities, returning a list containing the primary keys of the inserted entities in the same order as they were received.
boolean	isConnected()
boolean	isTransactionOpen()
byte[]	readBlob(Entity.Key primaryKey, java.lang.String blobPropertyId) Reads the blob specified by the property identified by propertyId from the given entity
void	rollbackTransaction() Performs a rollback and ends the current transaction
java.util.Map<java.lang.String,java.util.Collection<Entity>>	selectDependencies(java.util.Collection<Entity> entities) Returns the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityIds
java.util.List<Entity>	selectMany(EntitySelectCondition condition) Selects entities according to the specified condition
java.util.List<Entity>	selectMany(java.util.List<Entity.Key> keys) Returns entities according to keys
java.util.List<Entity>	selectMany(java.lang.String entityId, java.lang.String propertyId, java.lang.Object... values) Selects entities according to one property (propertyId), using values as a condition
int	selectRowCount(EntityCondition condition) Selects the number of rows returned according to the given condition
Entity	selectSingle(Entity.Key key) Selects a single entity by key
Entity	selectSingle(EntitySelectCondition condition) Selects a single entity according to the specified condition, throws a DatabaseException if the condition results in more than one entity
Entity	selectSingle(java.lang.String entityId, java.lang.String propertyId, java.lang.Object value) Selects a single entity
java.util.List<java.lang.Object>	selectValues(java.lang.String propertyId, EntityCondition condition) Selects ordered and distinct non-null values of the given property, note that the given property must be of type ColumnProperty.
java.util.List<Entity>	update(java.util.List<Entity> entities) Updates the given entities according to their properties.
void	writeBlob(Entity.Key primaryKey, java.lang.String blobPropertyId, byte[] blobData) Writes blobData in the blob field specified by the property identified by propertyId for the given entity

Method Detail

getDomain

Domain getDomain()

Returns:

the underlying domain model

getUser

User getUser()

Returns:

the user being used by this connection

isConnected

boolean isConnected()

Returns:

true if the connection has been established and is valid

disconnect

void disconnect()

Performs a rollback and disconnects this connection

isTransactionOpen

boolean isTransactionOpen()

Returns:

true if a transaction is open, false otherwise

beginTransaction

void beginTransaction()

Begins a transaction on this connection

Throws:

java.lang.IllegalStateException - if a transaction is already open

rollbackTransaction

void rollbackTransaction()

Performs a rollback and ends the current transaction

Throws:

java.lang.IllegalStateException - in case a transaction is not open

commitTransaction

void commitTransaction()

Performs a commit and ends the current transaction

Throws:

java.lang.IllegalStateException - in case a transaction is not open

executeFunction

java.util.List executeFunction(java.lang.String functionId,
                               java.lang.Object... arguments)
                        throws DatabaseException

Executes the function with the given id

Parameters:

functionId - the function ID

arguments - the arguments, if any

Returns:

the function return arguments

Throws:

DatabaseException - in case anything goes wrong during the execution

executeProcedure

void executeProcedure(java.lang.String procedureId,
                      java.lang.Object... arguments)
               throws DatabaseException

Executes the procedure with the given id

Parameters:

procedureId - the procedure ID

arguments - the arguments, if any

Throws:

DatabaseException - in case anything goes wrong during the execution

insert

java.util.List<Entity.Key> insert(java.util.List<Entity> entities)
                           throws DatabaseException

Inserts the given entities, returning a list containing the primary keys of the inserted entities 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

java.util.List<Entity> update(java.util.List<Entity> entities)
                       throws DatabaseException

Updates the given entities according to their properties. 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

delete

void delete(java.util.List<Entity.Key> entityKeys)
     throws DatabaseException

Deletes the entities according to 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

delete

void delete(EntityCondition 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

Throws:

DatabaseException - in case of a database exception

selectValues

java.util.List<java.lang.Object> selectValues(java.lang.String propertyId,
                                              EntityCondition condition)
                                       throws DatabaseException

Selects ordered and distinct non-null values of the given property, note that the given property must be of type ColumnProperty.

Parameters:

propertyId - the ID of the property

condition - the condition

Returns:

the values in the given column (Property)

Throws:

DatabaseException - in case of a database exception

java.lang.IllegalArgumentException - in case the given property is not a column based property

java.lang.UnsupportedOperationException - in case the entity is based on a select query

selectSingle

Entity selectSingle(java.lang.String entityId,
                    java.lang.String propertyId,
                    java.lang.Object value)
             throws DatabaseException

Selects a single entity

Parameters:

entityId - the entity type

propertyId - the ID of the property to use as a condition

value - the value to use in the condition

Returns:

an entity of the type entityId, having the value of propertyId 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

selectSingle

Entity selectSingle(Entity.Key key)
             throws DatabaseException

Selects a single 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(EntitySelectCondition condition)
             throws DatabaseException

Selects a single entity according to the specified condition, throws a DatabaseException if the condition results in more than one entity

Parameters:

condition - the condition specifying the entity to select

Returns:

the entities according to 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

selectMany

java.util.List<Entity> selectMany(java.util.List<Entity.Key> keys)
                           throws DatabaseException

Returns entities according to keys

Parameters:

keys - the keys used in the condition

Returns:

entities according to keys

Throws:

DatabaseException - in case of a database exception

selectMany

java.util.List<Entity> selectMany(EntitySelectCondition condition)
                           throws DatabaseException

Selects entities according to the specified condition

Parameters:

condition - the condition specifying which entities to select

Returns:

entities according to the given condition

Throws:

DatabaseException - in case of a database exception

selectMany

java.util.List<Entity> selectMany(java.lang.String entityId,
                                  java.lang.String propertyId,
                                  java.lang.Object... values)
                           throws DatabaseException

Selects entities according to one property (propertyId), using values as a condition

Parameters:

entityId - the entity type

propertyId - the ID of the condition property

values - the property values to use as condition

Returns:

entities of the type entityId according to propertyId and values

Throws:

DatabaseException - in case of a database exception

selectDependencies

java.util.Map<java.lang.String,java.util.Collection<Entity>> selectDependencies(java.util.Collection<Entity> entities)
                                                                         throws DatabaseException

Returns the entities that depend on the given entities via (non-soft) foreign keys, mapped to corresponding entityIds

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

selectRowCount

int selectRowCount(EntityCondition condition)
            throws DatabaseException

Selects the number of rows returned according to 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

ReportResult fillReport(ReportWrapper reportWrapper)
                 throws DatabaseException,
                        ReportException

Takes a ReportWrapper object using a JDBC datasource and returns an initialized ReportResult object

Parameters:

reportWrapper - the wrapper containing the report to fill

Returns:

an initialized ReportResult object

Throws:

DatabaseException - in case of a database exception

ReportException - in case of a report exception

See Also:

ReportWrapper.fillReport(java.sql.Connection)

writeBlob

void writeBlob(Entity.Key primaryKey,
               java.lang.String blobPropertyId,
               byte[] blobData)
        throws DatabaseException

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

Parameters:

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

blobPropertyId - the ID of the blob property

blobData - the blob data

Throws:

DatabaseException - in case of a database exception

readBlob

byte[] readBlob(Entity.Key primaryKey,
                java.lang.String blobPropertyId)
         throws DatabaseException

Reads the blob specified by the property identified by propertyId from the given entity

Parameters:

primaryKey - the primary key of the entity

blobPropertyId - the ID of the blob property

Returns:

a byte array containing the blob data

Throws:

DatabaseException - in case of a database exception