org.exolab.castor.persist.spi

Interface PersistenceQuery

Known Implementing Classes:
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.

Version:
$Revision: 1.1.1.1 $ $Date: 2003/03/03 07:08:51 $

Author:
Assaf Arkin

See Also:
Persistence

Method Summary

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.

Method Details

absolute

public boolean absolute(int row)
            throws PersistenceException
moves the result of the query to the absolute position in the resultset

Parameters:

Throws:
PersistenceException - A persistence error occured


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.

Parameters:
conn - An open connection
accessMode - The access mode (null equals shared)

Throws:
QueryException - An invalid query
PersistenceException - An error reported by the persistence engine


execute

public void execute(Object conn,
                    AccessMode accessMode,
                    boolean scrollable)
            throws QueryException,
                   PersistenceException
same as above, but parameterized for scrollable resultsets.

Parameters:
conn - An open connection
accessMode - The access mode (null equals shared)
scrollable - The db cursor mode.

Throws:
QueryException - An invalid query
PersistenceException - An error reported by the persistence engine


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.

Parameters:
fields - The fields to load into
identity - The object's identity

Returns:
The object's stamp, or null

Throws:
ObjectNotFoundException - The object was not found in persistent storage
PersistenceException - A persistence error occured

See Also:
Persistence.load(Object,Object[],Object,AccessMode)


getParameterCount

public int getParameterCount()
Returns the number of parameters required for this query.

Returns:
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.

Parameters:
index - The parameter index

Returns:
Type of parameter, or null


getResultType

public Class getResultType()
Returns the type of object returned by this query.

Returns:
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.

Parameters:
identity - The identity of the previous object, null if this method is called for the first time

Returns:
The identity of the next object, null if the result set has been exhausted

Throws:
PersistenceException - An error reported by the persistence engine


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.

Parameters:
index - The parameter index
value - 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