org.jminor.framework.db
Interface EntityConnection


public interface EntityConnection

Defines the database methods the database layer offers.


Method Summary
 void beginTransaction()
          Begins a transaction on this connection
 void commitTransaction()
          Performs a commit and ends the current transaction
 void delete(EntityCriteria criteria)
          Deletes the entities specified by the given criteria Performs a commit unless a transaction is open.
 void delete(List<Entity.Key> entityKeys)
          Deletes the entities according to the given primary keys.
 void disconnect()
          Disconnects this connection
 List<?> executeFunction(String functionID, Object... arguments)
          Executes the function with the given id
 void executeProcedure(String procedureID, 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
 PoolableConnection getPoolableConnection()
           
 User getUser()
           
 List<Entity.Key> insert(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()
           
 boolean isValid()
           
 byte[] readBlob(Entity.Key primaryKey, 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
 List<Entity> selectAll(String entityID)
          Selects all the entities of the given type
 Map<String,Collection<Entity>> selectDependentEntities(Collection<Entity> entities)
          Returns the entities that depend on the given entities via foreign keys, mapped to corresponding entityIDs
 List<Entity> selectMany(EntitySelectCriteria criteria)
          Selects entities according to the specified criteria
 List<Entity> selectMany(List<Entity.Key> keys)
          Returns entities according to keys
 List<Entity> selectMany(String entityID, String propertyID, Object... values)
          Selects entities according to one property (propertyID), using values as a condition
 List<Object> selectPropertyValues(String entityID, String propertyID, boolean order)
          Selects distinct non-null values of the given property of the given entity
 int selectRowCount(EntityCriteria criteria)
          Selects the number of rows returned according to the given criteria
 Entity selectSingle(Entity.Key key)
          Selects a single entity by key
 Entity selectSingle(EntitySelectCriteria criteria)
          Selects a single entity according to the specified criteria, throws a DatabaseException if the criteria results in more than one entity
 Entity selectSingle(String entityID, String propertyID, Object value)
          Selects a single entity
 List<Entity> update(List<Entity> entities)
          Updates the given entities according to their properties.
 void writeBlob(Entity.Key primaryKey, String blobPropertyID, String dataDescription, byte[] blobData)
          Writes blobData in the blob field specified by the property identified by propertyID for the given entity
 

Method Detail

getUser

User getUser()
Returns:
the user being used by this connection

isConnected

boolean isConnected()
Returns:
true if a connection has been made

disconnect

void disconnect()
Disconnects this connection


isValid

boolean isValid()
Returns:
true if this connection is valid

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

executeFunction

List<?> executeFunction(String functionID,
                        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 anyhing goes wrong during the execution

executeProcedure

void executeProcedure(String procedureID,
                      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 anyhing goes wrong during the execution

insert

List<Entity.Key> insert(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. If the primary key value of a entity is specified the id generation is disregarded. 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 db exception

update

List<Entity> update(List<Entity> entities)
                    throws DatabaseException
Updates the given entities according to their properties. Performs a commit unless a transaction is open.

Parameters:
entities - the entities to update
Returns:
the updated entities
Throws:
DatabaseException - in case of a db exception
RecordModifiedException - in case an entity has been modified by another user

delete

void delete(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 db exception

delete

void delete(EntityCriteria criteria)
            throws DatabaseException
Deletes the entities specified by the given criteria Performs a commit unless a transaction is open.

Parameters:
criteria - the criteria specifying the entities to delete
Throws:
DatabaseException - in case of a db exception

selectPropertyValues

List<Object> selectPropertyValues(String entityID,
                                  String propertyID,
                                  boolean order)
                                  throws DatabaseException
Selects distinct non-null values of the given property of the given entity

Parameters:
entityID - the class of the Entity
propertyID - the ID of the property
order - if true then the result is ordered
Returns:
the values in the given column (Property) in the given table (Entity)
Throws:
DatabaseException - in case of a db exception

selectSingle

Entity selectSingle(String entityID,
                    String propertyID,
                    Object value)
                    throws DatabaseException
Selects a single entity

Parameters:
entityID - the Class of the entity to select
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:
RecordNotFoundException - in case the entity was not found
DatabaseException - in case of a db exception

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 of the type entityID, having the key key
Throws:
RecordNotFoundException - in case the entity was not found
DatabaseException - in case of a db exception

selectSingle

Entity selectSingle(EntitySelectCriteria criteria)
                    throws DatabaseException
Selects a single entity according to the specified criteria, throws a DatabaseException if the criteria results in more than one entity

Parameters:
criteria - the criteria specifying the entity to select
Returns:
the entities according to the given criteria
Throws:
RecordNotFoundException - in case the entity was not found
DatabaseException - if an exception occurs

selectMany

List<Entity> selectMany(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 db exception

selectMany

List<Entity> selectMany(EntitySelectCriteria criteria)
                        throws DatabaseException
Selects entities according to the specified criteria

Parameters:
criteria - the criteria specifying which entities to select
Returns:
entities according to the given criteria
Throws:
DatabaseException - in case of a db exception

selectMany

List<Entity> selectMany(String entityID,
                        String propertyID,
                        Object... values)
                        throws DatabaseException
Selects entities according to one property (propertyID), using values as a condition

Parameters:
entityID - the Class of the entities to select
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 db exception

selectAll

List<Entity> selectAll(String entityID)
                       throws DatabaseException
Selects all the entities of the given type

Parameters:
entityID - the Class of the entities to select
Returns:
all entities of the given type
Throws:
DatabaseException - in case of a db exception

selectDependentEntities

Map<String,Collection<Entity>> selectDependentEntities(Collection<Entity> entities)
                                                       throws DatabaseException
Returns the entities that depend on the given entities via foreign keys, mapped to corresponding entityIDs

Parameters:
entities - the entities for which to retrieve dependencies
Returns:
the entities that depend on entities
Throws:
DatabaseException - in case of a db exception

selectRowCount

int selectRowCount(EntityCriteria criteria)
                   throws DatabaseException
Selects the number of rows returned according to the given criteria

Parameters:
criteria - the search criteria
Returns:
the number of rows fitting the given criteria
Throws:
DatabaseException - in case of a db 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:
ReportException - in case of a report exception
DatabaseException - in case of a db exception
See Also:
ReportWrapper.fillReport(java.sql.Connection)

writeBlob

void writeBlob(Entity.Key primaryKey,
               String blobPropertyID,
               String dataDescription,
               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
dataDescription - the value to insert into the blob description column
blobData - the blob data
Throws:
DatabaseException - in case of a db exception

readBlob

byte[] readBlob(Entity.Key primaryKey,
                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 db exception

getPoolableConnection

PoolableConnection getPoolableConnection()
Returns:
the underlying poolable connection