to.etc.webapp.query

Interface QDataContext

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

JdbcDataContext, QAbstractDataContext, TestDataContextMock, TestDataContextStub

public interface QDataContext
extends AutoCloseable

Generalized thingy representing a database connection, and state associated with objects. Equals the "DataContext" or "Hibernate Session". This is a controlled resource.

Author:

Frits Jalvingh Created on Jun 25, 2008

Method Summary

Modifier and Type	Method and Description
void	addCommitAction(IRunnable cx) Add an action which should be executed after a succesful commit on this context.
void	addListener(IQDataContextListener qDataContextListener) Add a listener to keep track of the events on an instance.
void	attach(Object o) If the object was from an earlier database session reattach it to another, live session.
void	close() This will close and fully discard all resources belonging to this context, provided ignoreClose is not true.
void	commit()
void	delete(Object o) Cause the object to be deleted from the database.
<T> T	find(Class<T> clz, Object pk) Load the persistent object with the specified type and primary key from the database.
<T> T	find(ICriteriaTableDef<T> metatable, Object pk)
<T> T	get(Class<T> clz, Object pk) Load the persistent object with the specified type and primary key from the database.
Connection	getConnection()
QDataContextFactory	getFactory() Returns the context source which created this DataContext.
<T> T	getInstance(Class<T> clz, Object pk) Load the persistent object with the specified type and primary key from the database.
<T> T	getInstance(ICriteriaTableDef<T> clz, Object pk)
boolean	inTransaction()
<T> T	original(T copy) EXPERIMENTAL INTERFACE This retrieves the "original" copy of the specified instance (which must be loaded inside this data context).
<R> List<R>	query(Class<R> resultInterface, QSelection<?> sel) Query a selection, and return the result in the specified proxied interface.
<T> List<T>	query(QCriteria<T> q) Execute the query specified by q and return a list of results.
List<Object[]>	query(QSelection<?> sel) Issue a selection query, where multiple fields or projections on fields are selected from a base class.
<R> R	queryOne(Class<R> resultInterface, QSelection<?> sel) Query a selection, and return the result in the specified proxied interface.
<T> T	queryOne(QCriteria<T> q) Execute the query specified by q, and expect and return at most 1 result.
Object[]	queryOne(QSelection<?> q) Execute the selection query specified by q, and expect and return at most 1 result.
void	refresh(Object o) EXPERIMENTAL/NOT FINAL Refresh with latest content in the database.
void	rollback()
void	save(Object o) Cause the object to be inserted in the database.
void	setIgnoreClose(boolean on) When ignoreClose is set to T the close call must be silently ignored.
void	setKeepOriginals() EXPERIMENTAL Sets the context so that it creates "before" copies.
void	startTransaction()

Method Detail

getFactory

@Nonnull
QDataContextFactory getFactory()

Returns the context source which created this DataContext. This context source is used to get query listeners to execute when a query is done.

Returns:

setIgnoreClose

void setIgnoreClose(boolean on)

When ignoreClose is set to T the close call must be silently ignored. Ugly, but for a lot of reasons (all having to do with the very strained object model around the ViewPoint database code) this is the least invasive method to allow for per-conversation shared contexts. Please do not replace this with any kind of wrapper/proxy based solution; it will not work.

Parameters:

on -

close

void close()

This will close and fully discard all resources belonging to this context, provided ignoreClose is not true. A closed context cannot be reused anymore and should be discarded.

Specified by:

close in interface AutoCloseable

query

@Nonnull
<T> List<T> query(@Nonnull
                           QCriteria<T> q)
                    throws Exception

Execute the query specified by q and return a list of results. Before and after the query execution all registered listeners will be called.

Type Parameters:

T - The return type for this query, a persistent class type

Parameters:

q - The selection criteria

Returns:

Throws:

Exception

queryOne

@Nullable
<T> T queryOne(@Nonnull
                         QCriteria<T> q)
                  throws Exception

Execute the query specified by q, and expect and return at most 1 result. If the query has no result this will return null. If more than one result is obtained this will throw an IllegalStateException.

Type Parameters:

T -

Parameters:

q -

Returns:

Throws:

Exception

query

@Nonnull
List<Object[]> query(@Nonnull
                              QSelection<?> sel)
                       throws Exception

Issue a selection query, where multiple fields or projections on fields are selected from a base class.

Parameters:

sel -

Returns:

Throws:

Exception

query

@Nonnull
<R> List<R> query(@Nonnull
                           Class<R> resultInterface,
                           @Nonnull
                           QSelection<?> sel)
                    throws Exception

Query a selection, and return the result in the specified proxied interface. Members in the interface must be annotated with QFld annotations to define the order in the result set.

Parameters:

resultInterface -

sel -

Returns:

Throws:

Exception

queryOne

@Nullable
Object[] queryOne(@Nonnull
                            QSelection<?> q)
                     throws Exception

Execute the selection query specified by q, and expect and return at most 1 result. If the query has no result this will return null. If more than one result is obtained this will throw an IllegalStateException.

Type Parameters:

T -

Parameters:

q -

Returns:

Throws:

Exception

queryOne

@Nullable
<R> R queryOne(@Nonnull
                         Class<R> resultInterface,
                         @Nonnull
                         QSelection<?> sel)
                  throws Exception

Query a selection, and return the result in the specified proxied interface. Members in the interface must be annotated with QFld annotations to define the order in the result set.

Parameters:

resultInterface -

sel -

Returns:

Throws:

Exception

find

@Nullable
<T> T find(@Nonnull
                     Class<T> clz,
                     @Nonnull
                     Object pk)
              throws Exception

Load the persistent object with the specified type and primary key from the database. This will execute an actual select in the database if the object is not yet cached, ensuring that the object actually exists. If the object does not exist this will return null.

Type Parameters:

T - The object type.

Parameters:

clz - The persistent class for which an instance is being sought.

pk - The PK for the instance required.

Returns:

Null if the instance does not exist, the actual and fully initialized instance (or proxy) otherwise.

Throws:

Exception

get

@Nonnull
<T> T get(@Nonnull
                   Class<T> clz,
                   @Nonnull
                   Object pk)
            throws Exception

Load the persistent object with the specified type and primary key from the database. This will execute an actual select in the database if the object is not yet cached, ensuring that the object actually exists. If the object does not exist this will raise QNotFoundException.

Type Parameters:

T - The object type.

Parameters:

clz - The persistent class for which an instance is being sought.

pk - The PK for the instance required.

Returns:

The actual and fully initialized instance (or proxy).

Throws:

Exception

find

@Nullable
<T> T find(@Nonnull
                     ICriteriaTableDef<T> metatable,
                     @Nonnull
                     Object pk)
              throws Exception

Throws:

Exception

original

@Nullable
<T> T original(@Nonnull
                         T copy)

EXPERIMENTAL INTERFACE This retrieves the "original" copy of the specified instance (which must be loaded inside this data context). The original copy contains the field instances as they were before the record was loaded.

Parameters:

copy -

Returns:

setKeepOriginals

void setKeepOriginals()

EXPERIMENTAL Sets the context so that it creates "before" copies. Can only be used before any data is loaded. If the context does not support before copies this throws Exception.

getInstance

@Nonnull
<T> T getInstance(@Nonnull
                           Class<T> clz,
                           @Nonnull
                           Object pk)
                    throws Exception

Load the persistent object with the specified type and primary key from the database. This will return an object always even if the object does not exist in the database! This should only be used when you need an instance representing a given primary key that you know exists. This usually returns a proxy, meaning that nonexistent objects will throw exceptions as soon as properties other than it's primary key are accessed. To get an object and be sure it is present in the database use find(Class, Object).

Type Parameters:

T - The object type

Parameters:

clz - The persistent class for which an instance is being sought.

pk - The PK for the instance required.

Returns:

Always returns an instance; it can be invalid when it does not really exist on the backing store.

Throws:

Exception

getInstance

@Nonnull
<T> T getInstance(@Nonnull
                           ICriteriaTableDef<T> clz,
                           @Nonnull
                           Object pk)
                    throws Exception

Throws:

Exception

attach

void attach(@Nonnull
            Object o)
     throws Exception

If the object was from an earlier database session reattach it to another, live session.

Parameters:

o -

Throws:

Exception

save

void save(@Nonnull
          Object o)
   throws Exception

Cause the object to be inserted in the database.

Parameters:

o -

Throws:

Exception

refresh

void refresh(@Nonnull
             Object o)
      throws Exception

EXPERIMENTAL/NOT FINAL Refresh with latest content in the database.

Parameters:

o -

Throws:

Exception

delete

void delete(@Nonnull
            Object o)
     throws Exception

Cause the object to be deleted from the database.

Parameters:

o -

Throws:

Exception

startTransaction

void startTransaction()
               throws Exception

Throws:

Exception

commit

void commit()
     throws Exception

Throws:

Exception

rollback

void rollback()
       throws Exception

Throws:

Exception

inTransaction

boolean inTransaction()
               throws Exception

Throws:

Exception

getConnection

@Nonnull
Connection getConnection()
                           throws Exception

Throws:

Exception

addCommitAction

void addCommitAction(@Nonnull
                     IRunnable cx)

Add an action which should be executed after a succesful commit on this context.

Parameters:

cx -

addListener

void addListener(@Nonnull
                 IQDataContextListener qDataContextListener)

Add a listener to keep track of the events on an instance.

Parameters:

testDataListener -