org.exolab.castor.persist.spi
Interface PersistenceQuery
- MultiRSCallQuery, PostgreSQLCallQuery, ReturnedRSCallQuery, SQLEngine.SQLQuery
public interface PersistenceQuery
The persistence engine implements this interface in order to allow
queries to be performed and multiple objects to be returned. This is
an extension of
Persistence.load(Object,Object[],Object,AccessMode)
for dealing with complex
queries.
The caller takes full responsibility to assure integrity of
transactions and object caching and only relies on the engine to
assist in assuring that through the mechanisms available to it.
A query may be created once and used multiple times by calling the
execute
method. Query parameters are set each time prior
to executing the query.
See
Persistence
for information about locks, loading
objects, identities and stamps.
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:51 $ boolean | absolute(int row) - moves the result of the query to the absolute position in the
resultset
|
void | close() - Close the query and release all resources held by the query.
|
void | execute(Object conn, AccessMode accessMode) - Execute the query with the give connection and lock type.
|
void | execute(Object conn, AccessMode accessMode, boolean scrollable) - same as above, but parameterized for scrollable resultsets.
|
Object | fetch(Object[] fields, Object identity) - Loades the object.
|
int | getParameterCount() - Returns the number of parameters required for this query.
|
Class | getParameterType(int index) - Returns the type of a parameter required by this query.
|
Class | getResultType() - Returns the type of object returned by this query.
|
Object | nextIdentity(Object identity) - Returns the identity of the next object to be returned.
|
void | setParameter(int index, Object value) - Sets the value of a paramter.
|
int | size() - finds the size of the resulting resultset from the query.
|
absolute
public boolean absolute(int row)
throws PersistenceException
moves the result of the query to the absolute position in the
resultset
close
public void close()
Close the query and release all resources held by the query.
execute
public void execute(Object conn,
AccessMode accessMode)
throws QueryException,
PersistenceException
Execute the query with the give connection and lock type.
After a successful return the query results will be returned
by calling
nextIdentity(Object)
and
fetch(Object[],Object)
. The
query parameters will be reset. A new query may be issued by
providing new query parameters and calling
execute
.
conn
- An open connectionaccessMode
- The access mode (null equals shared)
execute
public void execute(Object conn,
AccessMode accessMode,
boolean scrollable)
throws QueryException,
PersistenceException
same as above, but parameterized for scrollable resultsets.
conn
- An open connectionaccessMode
- The access mode (null equals shared)scrollable
- The db cursor mode.
fetch
public Object fetch(Object[] fields,
Object identity)
throws ObjectNotFoundException,
PersistenceException
Loades the object. This method must be called immediately
after
nextIdentity(Object)
with the same identity.
If the object is locked by another transaction this method will
block until the lock is released, or a timeout occured. If a
timeout occurs or the object has been deleted by the other
transaction, this method will report an
ObjectNotFoundException
. The query may proceed to the next
identity.
This method is equivalent to
Persistence.load(Object,Object[],Object,AccessMode)
with a
known cache engine and access mode and acts on the query
results rather than issuing a new query to load the object.
fields
- The fields to load intoidentity
- The object's identity
- The object's stamp, or null
getParameterCount
public int getParameterCount()
Returns the number of parameters required for this query.
- Number of query parameters
getParameterType
public Class getParameterType(int index)
Returns the type of a parameter required by this query. May
return null if the type is unknown.
index
- The parameter index
- Type of parameter, or null
getResultType
public Class getResultType()
Returns the type of object returned by this query.
- The type of object returned by this query
nextIdentity
public Object nextIdentity(Object identity)
throws PersistenceException
Returns the identity of the next object to be returned.
Calling this method multiple time will skip objects.
When the result set has been exhuasted, this method will
return null.
identity
- The identity of the previous object,
null if this method is called for the first time
- The identity of the next object, null if the
result set has been exhausted
setParameter
public void setParameter(int index,
Object value)
Sets the value of a paramter. Will complain if the parameter
is not of the specified type.
index
- The parameter indexvalue
- The parameter value
size
public int size()
throws PersistenceException
finds the size of the resulting resultset from the query.
Intalio Inc. (C) 1999-2003. All rights reserved http://www.intalio.com