org.apache.ojb.broker.accesslayer
Class RsIterator

java.lang.Object
  org.apache.ojb.broker.accesslayer.RsIterator

All Implemented Interfaces:

java.util.Iterator, OJBIterator

Direct Known Subclasses:

ReportQueryRsIterator, SqlBasedRsIterator

public class RsIterator

extends java.lang.Object

implements OJBIterator

RsIterator can be used to iterate over a jdbc ResultSet to retrieve persistent objects step-by-step and not all at once. In fact the PersistenceBroker::getCollectionByQuery(...) method uses a RsIterator internally to build up a Collection of objects

NOTE: OJB is very strict in handling RsIterator instances. RsIterator is bound very closely to the used PersistenceBroker instance. Thus if you do a
- PersistenceBroker.close()
- PersistenceBroker.commitTransaction()
- PersistenceBroker.abortTransaction()
call, the current RsIterator instance resources will be cleaned up automatic and invalidate current instance.

NOTE: this code uses features that only JDBC 2.0 compliant Drivers support. It will NOT work with JDBC 1.0 Drivers (e.g. SUN's JdbcOdbcDriver) If you are forced to use such a driver, you can use code from the 0.1.30 release.

Version:

$Id: RsIterator.java 365232 2005-12-21 22:36:07Z tomdz $

Author:

Thomas Mahler , Matthew Baird - added the support for extents mapped to single table - added the .size functionality - added cursor control

Nested Class Summary

static class	RsIterator.ResourceClosedException
static class	RsIterator.ResourceNotClosedException
static class	RsIterator.ResourceWrapper Wraps a RsIterator instance as WeakReference.

Constructor Summary

RsIterator(RsQueryObject queryObject, PersistenceBrokerImpl broker)
RsIterator constructor.

Method Summary

boolean	absolute(int row) Moves the cursor to the given row number in the iterator.
void	disableLifeCycleEvents() Do not fire any PBLifeCycleEvent when reading next item.
int	fullSize()
ClassDescriptor	getClassDescriptor()
boolean	hasNext() returns true if there are still more rows in the underlying ResultSet.
java.lang.Object	next() moves to the next row of the underlying ResultSet and returns the corresponding Object materialized from this row.
boolean	relative(int row) Moves the cursor a relative number of rows, either positive or negative.
void	releaseDbResources() Release all internally used Database resources of the iterator.
void	remove() removing is not supported
void	setAutoRelease(boolean autoRelease) Allows user to switch off/on automatic resource cleanup.
int	size()
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

RsIterator

public RsIterator(RsQueryObject queryObject,
                  PersistenceBrokerImpl broker)

RsIterator constructor.

Parameters:

queryObject - query object

broker - the broker we should use.

Method Detail

hasNext

public boolean hasNext()

returns true if there are still more rows in the underlying ResultSet. Returns false if ResultSet is exhausted.

Specified by:

hasNext in interface java.util.Iterator

next

public java.lang.Object next()
                      throws java.util.NoSuchElementException

moves to the next row of the underlying ResultSet and returns the corresponding Object materialized from this row.

Specified by:

next in interface java.util.Iterator

Throws:

java.util.NoSuchElementException

remove

public void remove()

removing is not supported

Specified by:

remove in interface java.util.Iterator

size

public int size()
         throws PersistenceBrokerException

Specified by:

size in interface OJBIterator

Returns:

the size of the iterator, aka the number of rows in this iterator.

Throws:

PersistenceBrokerException

fullSize

public int fullSize()
             throws PersistenceBrokerException

Specified by:

fullSize in interface OJBIterator

Returns:

the unlimited size of the iterator, fullSize() may differ from size() for PagingIterator

Throws:

PersistenceBrokerException

absolute

public boolean absolute(int row)
                 throws PersistenceBrokerException

Moves the cursor to the given row number in the iterator. If the row number is positive, the cursor moves to the given row number with respect to the beginning of the iterator. The first row is row 1, the second is row 2, and so on.

Specified by:

absolute in interface OJBIterator

Parameters:

row - the row to move to in this iterator, by absolute number

Throws:

PersistenceBrokerException

relative

public boolean relative(int row)
                 throws PersistenceBrokerException

Moves the cursor a relative number of rows, either positive or negative. Attempting to move beyond the first/last row in the iterator positions the cursor before/after the the first/last row. Calling relative(0) is valid, but does not change the cursor position.

Specified by:

relative in interface OJBIterator

Parameters:

row - the row to move to in this iterator, by relative number

Throws:

PersistenceBrokerException

releaseDbResources

public void releaseDbResources()

Release all internally used Database resources of the iterator. Clients must call this methods explicitely if the iterator is not exhausted by the client application. If the Iterator is exhauseted this method will be called implicitely.

Specified by:

releaseDbResources in interface OJBIterator

setAutoRelease

public void setAutoRelease(boolean autoRelease)

Allows user to switch off/on automatic resource cleanup. Set false to take responsibility of resource cleanup for this class, means after use it's mandatory to call releaseDbResources().
By default it's true and resource cleanup is done automatic.

toString

public java.lang.String toString()

getClassDescriptor

public ClassDescriptor getClassDescriptor()

Returns:

Returns the cld.

disableLifeCycleEvents

public void disableLifeCycleEvents()

Description copied from interface: OJBIterator

Do not fire any PBLifeCycleEvent when reading next item.

Specified by:

disableLifeCycleEvents in interface OJBIterator

See Also:

OJBIterator.disableLifeCycleEvents()