de.mguennewig.pobjects
Interface Container

All Known Implementing Classes:

AbstractContainer, ContainerWrapper, FileSystemContainer, JdbcContainer, MemoryContainer, MySQLContainer, OracleContainer, PostgreSQLContainer, SQLiteContainer, SqlServerContainer

public interface Container

Interface for database connections.

Author:

Michael Günnewig

Field Summary

static int	SUPPORTS_BOOLEAN The database supports the data type BOOLEAN natively.
static int	SUPPORTS_INHERITS The INHERITS concept is supported by the RDBMS as well as supported and used by the Container.
static int	SUPPORTS_JOIN Capability flag, which states that both outer join syntaxes are supported.
static int	SUPPORTS_LIMIT_OFFSET The keywords LIMIT and OFFSET are supported to limit result set of the query.
static int	SUPPORTS_ORACLE_JOIN Capability flag, which states that for outer joins a (+) as used by Oracle must be appended to the expression in the WHERE clause, which should be used for the join.
static int	SUPPORTS_SQL99_JOIN Capability flag, which states that [LEFT | RIGHT | FULL] OUTER JOIN in the FROM part are supported.
static int	USE_ARRAY_FOR_LOB Use an array of bytes/characters for large objects.
static int	USE_STREAM_TO_INSERT_LOB Use a stream/reader to insert large objects into the database.

Method Summary

void	beginTransaction() Starts a new transaction.
void	close()
void	commitTransaction() Commits all statements since the last beginTransaction().
Record	createObject(TableExpr te) Creates a new Record instance for the given table expression without any binding to this container.
int	deleteAll(java.lang.Class<? extends Record> tableClass) Deletes all entries within the specified table.
int	deleteAll(ClassDecl te) Deletes all entries within the specified table.
int	deleteAll(ClassDecl cl, Column fk, java.lang.Object value) Deletes all entries within the specified table whose foreign key fk equals the given value.
void	deleteObject(PObject obj) Deletes the given persistent object from the database.
boolean	deleteRecord(Record obj)
int	getCapabilities() Returns the capabilities of the DBMS.
ClassDecl	getClassDecl(java.lang.String schemaName) Returns the meta data definition for the table with the given schema name.
java.util.Iterator<ClassDecl>	getClassDecls() Returns an Iterator over all known class declarations.
Record	getData(TableExpr te) Returns a Record instance for the given table expression without reading any data from the DB.
PObjDictionary	getDictionary() Returns the used meta data dictionary.
PObject	getObject(java.lang.Class<? extends PObject> tableClass, java.lang.String id) Returns a PObject instance for the given table class without reading any data from the DB.
PObject	getObject(ClassDecl te, java.lang.String id) Returns a PObject instance for the given table expression without reading any data from the DB.
java.lang.String	getQualifiedName(SqlEntity entity) Returns the qualified name for the given SQL entity.
java.lang.String	getSchema() Returns the database schema prefix that is used to access the SQL entities.
java.lang.String	getSequenceCurrentValue(Sequence seq) Returns the current value of the given sequence.
java.lang.String	getSequenceNextValue(Sequence seq) Returns a new value of the given sequence.
TableExpr	getTableExpr(java.lang.Class<? extends Record> tableClass)
java.lang.String	insertObject(PObject obj) Inserts the given object into the database.
boolean	insertRecord(Record obj)
boolean	isStrictMode() Tests whether modified but unstored persistent objects will be denied upon a commit.
void	makePersistent(PObject obj) Creates the connection between the object and the database container.
EvalContext	newEvalContext(int numColumns)
Query	newQuery() Creates a new empty query.
Query	newQuery(java.lang.Class<? extends Record> tableClass) Creates a new query for all rows of the given table expression.
Query	newQuery(java.lang.Class<? extends Record>[] tableClasses, Predicate[] filters) Creates a new query with a filter on the given table expression.
Query	newQuery(java.lang.Class<? extends Record> tableClass, Predicate filter) Creates a new query with a filter on the given table expression.
Query	newQuery(java.lang.Class<? extends Record> tableClass, Predicate[] filters) Creates a new query with a filter on the given table expression.
Query	newQuery(TableExpr tableExpr) Creates a new query for all rows of the given table expression.
Query	newQuery(TableExpr[] tableExprs, Predicate[] filters) Creates a new query with a filter on the given table expressions.
Query	newQuery(TableExpr tableExpr, Predicate filter) Creates a new query with a filter on the given table expression.
Query	newQuery(TableExpr tableExpr, Predicate[] filters) Creates a new query with a filter on the given table expression.
void	notifyChange(PObject obj, boolean reverted) Notifies this container that the object has been changed.
void	reset() Resets the container.
void	retrieveData(PObject obj) Retrieves the data for the given persistent object from the database.
void	rollbackTransaction() Rolls back all statements since the last beginTransaction().
void	setStrictMode(boolean strictMode) Sets whether modified but unstored persistent objects will be denied upon a commit.
void	storeAll() Stores all changed objects belonging to this container.
boolean	supportsBoolean() Tests whether the database supports booleans natively.
boolean	supportsInherits() Tests whether the database supports the inheritance concept natively.
boolean	supportsLimitOffset() Tests whether the database supports limiting the result set.
boolean	supportsOracleJoin() Tests whether the database supports Oracle style joins.
boolean	supportsSQL99Join() Tests whether the database supports SQL99 style joins.
void	updateObject(PObject obj) Updates the given persistent object in the database.
boolean	useArrayForLob() Tests whether the database requires to use an byte[] or char[] instead of a large object.
boolean	useStreamToInsertLob() Tests whether the database requires to use an InputStream or Reader instead of a large object.

Field Detail

SUPPORTS_SQL99_JOIN

static final int SUPPORTS_SQL99_JOIN

Capability flag, which states that [LEFT | RIGHT | FULL] OUTER JOIN in the FROM part are supported.

This join variation will be preferred if also the Oracle version is supported.

See Also:

Constant Field Values

SUPPORTS_ORACLE_JOIN

static final int SUPPORTS_ORACLE_JOIN

Capability flag, which states that for outer joins a (+) as used by Oracle must be appended to the expression in the WHERE clause, which should be used for the join.

See Also:

SUPPORTS_ORACLE_JOIN, "Oracle Documentation", Constant Field Values

SUPPORTS_JOIN

static final int SUPPORTS_JOIN

Capability flag, which states that both outer join syntaxes are supported.

See Also:

SUPPORTS_SQL99_JOIN, SUPPORTS_ORACLE_JOIN, Constant Field Values

SUPPORTS_LIMIT_OFFSET

static final int SUPPORTS_LIMIT_OFFSET

The keywords LIMIT and OFFSET are supported to limit result set of the query.

See Also:

"PostgreSQL Documentation", Constant Field Values

SUPPORTS_INHERITS

static final int SUPPORTS_INHERITS

The INHERITS concept is supported by the RDBMS as well as supported and used by the Container.

If this flag is set, then the RDBMS has to support queries as well as data manipulation statements to affect also the inherited classes.

If this flag is not set, then a special column pclass_ is added to the base class, which will specify the instance type. The rest has then to be done by the Container, Query and EvalContext.

See Also:

"PostgreSQL Documentation", Constant Field Values

SUPPORTS_BOOLEAN

static final int SUPPORTS_BOOLEAN

The database supports the data type BOOLEAN natively.

See Also:

Constant Field Values

USE_STREAM_TO_INSERT_LOB

static final int USE_STREAM_TO_INSERT_LOB

Use a stream/reader to insert large objects into the database.

The JDBC drivers of Oracle expect to get their own Blob and Clob implementations for calls to the PreparedStatement API. If they get anything else you just run into a ClassCastException.

See Also:

Constant Field Values

USE_ARRAY_FOR_LOB

static final int USE_ARRAY_FOR_LOB

Use an array of bytes/characters for large objects.

Most JDBC drivers for SQLite do not support LOBs, but arrays of bytes or characters.

See Also:

Constant Field Values

Method Detail

getCapabilities

int getCapabilities()

Returns the capabilities of the DBMS.

See Also:

"The SUPPORTS_* constants."

supportsBoolean

boolean supportsBoolean()

Tests whether the database supports booleans natively.

See Also:

SUPPORTS_BOOLEAN

supportsInherits

boolean supportsInherits()

Tests whether the database supports the inheritance concept natively.

See Also:

SUPPORTS_INHERITS

supportsLimitOffset

boolean supportsLimitOffset()

Tests whether the database supports limiting the result set.

See Also:

SUPPORTS_LIMIT_OFFSET

supportsOracleJoin

boolean supportsOracleJoin()

Tests whether the database supports Oracle style joins.

See Also:

SUPPORTS_ORACLE_JOIN

supportsSQL99Join

boolean supportsSQL99Join()

Tests whether the database supports SQL99 style joins.

See Also:

SUPPORTS_SQL99_JOIN

useStreamToInsertLob

boolean useStreamToInsertLob()

Tests whether the database requires to use an InputStream or Reader instead of a large object.

See Also:

USE_STREAM_TO_INSERT_LOB

useArrayForLob

boolean useArrayForLob()

Tests whether the database requires to use an byte[] or char[] instead of a large object.

See Also:

USE_ARRAY_FOR_LOB

getDictionary

PObjDictionary getDictionary()

Returns the used meta data dictionary.

getSchema

java.lang.String getSchema()

Returns the database schema prefix that is used to access the SQL entities.

See Also:

getQualifiedName(SqlEntity)

getQualifiedName

java.lang.String getQualifiedName(SqlEntity entity)

Returns the qualified name for the given SQL entity.

See Also:

Module.getSchemaPrefix(), getSchema()

getTableExpr

TableExpr getTableExpr(java.lang.Class<? extends Record> tableClass)

getClassDecl

ClassDecl getClassDecl(java.lang.String schemaName)

Returns the meta data definition for the table with the given schema name.

See Also:

getClassDecls()

getClassDecls

java.util.Iterator<ClassDecl> getClassDecls()

Returns an Iterator over all known class declarations.

isStrictMode

boolean isStrictMode()

Tests whether modified but unstored persistent objects will be denied upon a commit.

Returns:

true if there will be raised an exception for an modified but unstored object upon a commit, otherwise false.

setStrictMode

void setStrictMode(boolean strictMode)

Sets whether modified but unstored persistent objects will be denied upon a commit.

See Also:

isStrictMode(), commitTransaction()

beginTransaction

void beginTransaction()
                      throws PObjSQLException

Starts a new transaction.

Throws:

java.lang.IllegalStateException - if still a transaction is not finished with either commitTransaction() or rollbackTransaction().

PObjSQLException - if the DBMS is unable to start a new transaction.

commitTransaction

void commitTransaction()
                       throws PObjSQLException

Commits all statements since the last beginTransaction().

If isStrictMode() yields false then just a warning for each dirty object is written, otherwise an exception is raised.

Throws:

PObjSQLException - if the DBMS in unable to finish the current transaction by committing it or if an modified but unstored object is detected while in strict mode.

rollbackTransaction

void rollbackTransaction()
                         throws PObjSQLException

Rolls back all statements since the last beginTransaction().

The in-memory data will be reverted also as far as possible.

Throws:

PObjSQLException - if the DBMS is unable to stop the current transaction by rolling back all made changes within it.

See Also:

PObject.revert()

reset

void reset()

Resets the container.

Use this method to forget all changes made to any object.

NOTE: Any running transaction will be rolled back.

See Also:

rollbackTransaction()

close

void close()
           throws PObjSQLException

Throws:

PObjSQLException

getSequenceCurrentValue

java.lang.String getSequenceCurrentValue(Sequence seq)
                                         throws PObjSQLException

Returns the current value of the given sequence.

Throws:

PObjSQLException - if any database error occurs.

java.lang.UnsupportedOperationException - if database does not support sequences.

getSequenceNextValue

java.lang.String getSequenceNextValue(Sequence seq)
                                      throws PObjSQLException

Returns a new value of the given sequence.

Throws:

PObjSQLException - if any database error occurs.

java.lang.UnsupportedOperationException - if database does not support sequences.

createObject

Record createObject(TableExpr te)

Creates a new Record instance for the given table expression without any binding to this container.

Throws:

java.lang.ExceptionInInitializerError - if the initialization provoked by this method fails.

java.lang.SecurityException - if a security manager denies this operation.

See Also:

getObject(ClassDecl,String), getData(TableExpr), Class.newInstance()

getData

Record getData(TableExpr te)

Returns a Record instance for the given table expression without reading any data from the DB.

Throws:

java.lang.IllegalArgumentException - if te is a class declaration with an id field.

See Also:

getObject(ClassDecl,String), TableExpr.isWritableClass()

insertRecord

boolean insertRecord(Record obj)
                     throws PObjConstraintException,
                            PObjSQLException

Throws:

PObjConstraintException

PObjSQLException

deleteRecord

boolean deleteRecord(Record obj)
                     throws PObjConstraintException,
                            PObjSQLException

Throws:

PObjConstraintException

PObjSQLException

getObject

PObject getObject(ClassDecl te,
                  java.lang.String id)

Returns a PObject instance for the given table expression without reading any data from the DB.

Throws:

java.lang.IllegalArgumentException - if te is a class declaration without an id field.

See Also:

getData(TableExpr), retrieveData(PObject)

getObject

PObject getObject(java.lang.Class<? extends PObject> tableClass,
                  java.lang.String id)

Returns a PObject instance for the given table class without reading any data from the DB.

Throws:

java.lang.IllegalArgumentException - if tableClass is not a PObject instance or its class declaration has no id field.

See Also:

getTableExpr(Class), getObject(ClassDecl,String)

insertObject

java.lang.String insertObject(PObject obj)
                              throws PObjConstraintException,
                                     PObjSQLException

Inserts the given object into the database.

Throws:

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

updateObject

void updateObject(PObject obj)
                  throws PObjConstraintException,
                         PObjSQLException

Updates the given persistent object in the database.

Throws:

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

See Also:

PObject.isPersistent()

deleteObject

void deleteObject(PObject obj)
                  throws PObjConstraintException,
                         PObjSQLException

Deletes the given persistent object from the database.

Throws:

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

See Also:

PObject.isPersistent()

makePersistent

void makePersistent(PObject obj)

Creates the connection between the object and the database container.

This method tells the object the database container and the container that this pbject is a newly created one that might be added to the DBMS.

Throws:

java.lang.IllegalStateException - if the object is already in any container, or any reference within points to an object which isn't persistent or in another container.

See Also:

ForeignKeyConstraint

notifyChange

void notifyChange(PObject obj,
                  boolean reverted)

Notifies this container that the object has been changed.

See Also:

PObject.set(Column,Object), PObject.revert()

storeAll

void storeAll()
              throws PObjConstraintException,
                     PObjSQLException

Stores all changed objects belonging to this container.

The current implementation of this method may fail for some kinds of cyclical data references involving delete and update operations, as no reordering will be done currently. The order of the made changes to the objects will be used, so that the object which got changed first will be the first stored.

Throws:

PObjConstraintException

PObjSQLException

See Also:

PObject.store()

deleteAll

int deleteAll(ClassDecl te)
              throws PObjSQLException,
                     PObjConstraintException

Deletes all entries within the specified table.

NOTE: The objects which represent a row of this table or refer to rows within it aren't updated. So the best way to ensure consistency is to finish the current active transaction before calling this method and afterwards doing a reset().

Throws:

java.lang.IllegalArgumentException - if te is null.

java.lang.IllegalStateException - if no connection to a DBMS exists.

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

deleteAll

int deleteAll(java.lang.Class<? extends Record> tableClass)
              throws PObjSQLException,
                     PObjConstraintException

Deletes all entries within the specified table.

NOTE: The objects which represent a row of this table or refer to rows within it aren't updated. So the best way to ensure consistency is to finish the current active transaction before calling this method and afterwards doing a reset().

Throws:

java.lang.IllegalArgumentException - if tableClass does not represent a database table.

java.lang.IllegalStateException - if no connection to a DBMS exists.

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

See Also:

deleteAll(ClassDecl), getTableExpr(Class)

deleteAll

int deleteAll(ClassDecl cl,
              Column fk,
              java.lang.Object value)
              throws PObjSQLException,
                     PObjConstraintException

Deletes all entries within the specified table whose foreign key fk equals the given value.

NOTE: The objects which represent a row of this table or refer to rows within it aren't updated. So the best way to ensure consistency is to finish the current active transaction before calling this method and afterwards doing a reset().

Throws:

java.lang.IllegalArgumentException - if cl is null.

java.lang.IllegalStateException - if no connection to a DBMS exists.

PObjConstraintException - if a database constraint will be violated.

PObjSQLException - if any other database error occurs.

retrieveData

void retrieveData(PObject obj)

Retrieves the data for the given persistent object from the database.

Throws:

PObjReadError - if any database error occurs during reading.

newEvalContext

EvalContext newEvalContext(int numColumns)

newQuery

Query newQuery()

Creates a new empty query.

newQuery

Query newQuery(TableExpr tableExpr)

Creates a new query for all rows of the given table expression.

newQuery

Query newQuery(TableExpr tableExpr,
               Predicate filter)

Creates a new query with a filter on the given table expression.

newQuery

Query newQuery(TableExpr tableExpr,
               Predicate[] filters)

Creates a new query with a filter on the given table expression.

newQuery

Query newQuery(TableExpr[] tableExprs,
               Predicate[] filters)

Creates a new query with a filter on the given table expressions.

newQuery

Query newQuery(java.lang.Class<? extends Record> tableClass)

Creates a new query for all rows of the given table expression.

See Also:

getTableExpr(Class), newQuery(TableExpr)

newQuery

Query newQuery(java.lang.Class<? extends Record> tableClass,
               Predicate filter)

Creates a new query with a filter on the given table expression.

See Also:

getTableExpr(Class), newQuery(TableExpr,Predicate)

newQuery

Query newQuery(java.lang.Class<? extends Record> tableClass,
               Predicate[] filters)

Creates a new query with a filter on the given table expression.

See Also:

getTableExpr(Class), newQuery(TableExpr,Predicate[])

newQuery

Query newQuery(java.lang.Class<? extends Record>[] tableClasses,
               Predicate[] filters)

Creates a new query with a filter on the given table expression.

See Also:

getTableExpr(Class), newQuery(TableExpr[],Predicate[])