org.apache.ojb.broker.accesslayer
Class RsIterator

java.lang.Object
  extended by 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()
Overrides:
toString in class java.lang.Object

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()


(C) 2002 - 2006 Apache Software Foundation
All rights reserved. Published under the Apache License 2.0.
http://db.apache.org/ojb
Version: 1.0.4, 2005-12-30