net.sourceforge.orbroker
Class Query

java.lang.Object
  net.sourceforge.orbroker.BrokerConnection
      net.sourceforge.orbroker.QueryableConnection
          net.sourceforge.orbroker.Query

public final class Query

extends net.sourceforge.orbroker.QueryableConnection

The query class. Read-only queries can use a Query object. It wraps a Connection object, and close() should be called after use, to avoid open connections, or connection pool leaks.

Author:

Nils Kilden-Pedersen

See Also:

Broker.startQuery(), Broker.startQuery(int)

Method Summary

void	addStatement(String id, String sql) Add temporary statement.
void	addStatement(String id, String sql, String resultObjectId) Add temporary statement.
void	close() Close query.
void	closeIterator(Iterator iterator) Close iterator.
Object	getParameter(String name) Get parameter.
Iterator	iterate(String statementID, int fetchSize) Return a live iterator.
List	selectMany(String statementID) Return a list of 0..n objects.
int	selectMany(String statementID, Collection resultCollection) Fill Collection with 0..n objects.
int	selectMany(String statementID, Collection resultCollection, int startRow, int rowCount) Fill Collection with 0..n objects.
List	selectMany(String statementID, int startRow, int rowCount) Return a list of 0..n objects.
Object	selectOne(String statementID) Return a single result object.
boolean	selectOne(String statementID, Object resultObject) Use supplied result object to apply values to.
Object	selectOneFromMany(String statementID, int fromRow) Return one result object from a query containing many.
void	setParameter(String name, Object value) Set named parameter.
void	setTextReplacement(String key, String value) Set a text replacement value.
void	setTextReplacements(Properties textReplacements) Set text replacement values.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

close

public void close()

Close query. Subsequent closes will be ignored.

selectMany

public final List selectMany(String statementID)
                      throws BrokerException

Return a list of 0..n objects. An empty List will be returned if result set is empty.

Parameters:

statementID - Statement id

Returns:

List of result objects

Throws:

BrokerException

selectMany

public final int selectMany(String statementID,
                            Collection resultCollection)
                     throws BrokerException

Fill Collection with 0..n objects. The supplied Collection does not have to be empty. Objects are added to Collection.

Parameters:

statementID - Statement id

resultCollection - The collection where the result will be added.

Returns:

Number of objects added to collection.

Throws:

BrokerException

iterate

public Iterator iterate(String statementID,
                        int fetchSize)

Return a live iterator. Very useful for large rows that, for memory concerns, need to be built a few at a time, controlled by the fetch size. The Iterator must be iterated with the source object active, i.e. a Query or Transaction must be open.

Parameters:

statementID - Statement id

fetchSize - Row buffer size

Returns:

Streamed Iterator of result objects.

closeIterator

public final void closeIterator(Iterator iterator)

Close iterator. Use this to close a live iterator returned by QueryableConnection.iterate(String, int). Only necessary if iterator has not been exhausted by hasNext() returning false

Parameters:

iterator - The not fully iterated iterator.

See Also:

QueryableConnection.iterate(String, int)

selectMany

public final int selectMany(String statementID,
                            Collection resultCollection,
                            int startRow,
                            int rowCount)
                     throws BrokerException

Fill Collection with 0..n objects. The supplied Collection does not have to be empty. Objects are added to Collection.

Parameters:

statementID - Statement id

resultCollection - The collection where the result will be added.

startRow - The start row to return. First row is 1.

rowCount - The number of rows to return

Returns:

Number of objects added to collection.

Throws:

BrokerException

selectMany

public final List selectMany(String statementID,
                             int startRow,
                             int rowCount)
                      throws BrokerException

Return a list of 0..n objects. An empty List will be returned if result set is empty or if startRow is greater than the result set size.

Parameters:

statementID - Statement id

startRow - The start row to return. First row is 1.

rowCount - The number of rows to return

Returns:

List of result objects

Throws:

BrokerException

selectOne

public final Object selectOne(String statementID)
                       throws BrokerException,
                              MoreThanOneRowException

Return a single result object.

Parameters:

statementID - Statement id

Returns:

the result object, or null if query returned 0 records.

Throws:

BrokerException

MoreThanOneRowException

selectOne

public final boolean selectOne(String statementID,
                               Object resultObject)
                        throws BrokerException,
                               MoreThanOneRowException

Use supplied result object to apply values to. Any constructor or factory method defined for mapping will be ignored.

Parameters:

statementID - Statement id

resultObject - result object to map to

Returns:

false if query didn't return a record.

Throws:

BrokerException

MoreThanOneRowException

selectOneFromMany

public Object selectOneFromMany(String statementID,
                                int fromRow)
                         throws BrokerException

Return one result object from a query containing many. Returns null if query is empty or returnRow is out of range.

Parameters:

statementID - Statement id

fromRow - Row to return. First row is 1.

Returns:

result object from row

Throws:

BrokerException

addStatement

public final void addStatement(String id,
                               String sql)
                        throws BrokerException,
                               ConfigurationException

Add temporary statement.

Parameters:

id - The statement id.

sql - The SQL statement

Throws:

BrokerException

ConfigurationException

addStatement

public final void addStatement(String id,
                               String sql,
                               String resultObjectId)
                        throws BrokerException,
                               ConfigurationException

Add temporary statement.

Parameters:

id - The statement id.

sql - The SQL statement

resultObjectId - The result-object id as defined in the XML configuration file.

Throws:

BrokerException

ConfigurationException

getParameter

public final Object getParameter(String name)

Get parameter. Used to retrieve OUT/INOUT parameters from stored procedures. Both input and output parameters are stored in the same context, so any parameter set using BrokerConnection.setParameter(String, Object) will be available with this method. Also if a stored procedure has an output parameter that needs to be used as input in another SQL statements, it's immediately available, i.e. there's no need to code like this: txn.setParameter("parm", txn.getParameter("parm"));

Parameters:

name - parameter name

Returns:

parameter value

setParameter

public final void setParameter(String name,
                               Object value)

Set named parameter.

Parameters:

name - parameter name

value - parameter value

setTextReplacement

public final void setTextReplacement(String key,
                                     String value)

Set a text replacement value. This will replace a {{key}} string with the value. This will override any value set on Broker.

Parameters:

key - Text replacement key

value - Text replacement value

See Also:

BrokerConnection.setTextReplacements(Properties)

setTextReplacements

public final void setTextReplacements(Properties textReplacements)

Set text replacement values. This will replace all {{key}} type properties in an sql-statement with the values. This will override any value set on Broker.

Parameters:

textReplacements - The replacement values to set.

See Also:

BrokerConnection.setTextReplacement(String, String)