org.apache.ojb.broker.accesslayer
Class RsIterator

java.lang.Object
  extended byorg.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,v 1.58 2004/02/10 15:18:53 arminw Exp $
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.
 
Field Summary
protected  Logger logger
           
 
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.
protected  void autoReleaseDbResources()
          Internally used by this class to close used resources as soon as possible.
protected  int countedSize()
          Answer the counted size
protected  void finalize()
          safety just in case someone leaks.
 int fullSize()
           
protected  PBLifeCycleEvent getAfterLookupEvent()
           
protected  PersistenceBrokerImpl getBroker()
           
protected  InternalCache getCache()
           
 ClassDescriptor getClassDescriptor()
           
protected  JdbcConnectionDescriptor getConnectionDescriptor()
           
protected  DescriptorRepository getDescriptorRepository()
          Return the DescriptorRepository
protected  boolean getHasNext()
           
protected  Identity getIdentityFromResultSet()
          returns an Identity object representing the current resultset row
protected  java.lang.Class getItemProxyClass()
           
protected  java.lang.Object getObjectFromResultSet()
          returns a fully materialized Object from the current row of the underlying resultset.
protected  java.lang.Object getProxyFromResultSet()
          Reads primary key information from current RS row and generates a corresponding Identity, and returns a proxy from the Identity.
protected  RsQueryObject getQueryObject()
           
protected  java.util.Map getRow()
           
protected  ResultSetAndStatement getRsAndStmt()
           
protected  java.lang.Class getTopLevelClass()
           
 boolean hasNext()
          returns true if there are still more rows in the underlying ResultSet.
protected  boolean isHasCalledCheck()
           
protected  boolean isInBatchedMode()
           
 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
protected  void setAfterLookupEvent(PBLifeCycleEvent afterLookupEvent)
           
 void setAutoRelease(boolean autoRelease)
          Allows user to switch off/on automatic resource cleanup.
protected  void setBroker(PersistenceBrokerImpl broker)
           
protected  void setCache(InternalCache cache)
           
protected  void setHasCalledCheck(boolean hasCalledCheck)
           
protected  void setHasNext(boolean hasNext)
           
protected  void setInBatchedMode(boolean inBatchedMode)
           
protected  void setItemProxyClass(java.lang.Class itemProxyClass)
           
protected  void setQueryObject(RsQueryObject queryObject)
           
protected  void setRow(java.util.Map row)
           
protected  void setRsAndStmt(ResultSetAndStatement rsAndStmt)
           
 int size()
           
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

logger

protected Logger logger
Constructor Detail

RsIterator

public RsIterator(RsQueryObject queryObject,
                  PersistenceBrokerImpl broker)
RsIterator constructor.

Parameters:
queryObject - query object
broker - the broker we should use.
Method Detail

getTopLevelClass

protected java.lang.Class getTopLevelClass()

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

getIdentityFromResultSet

protected Identity getIdentityFromResultSet()
                                     throws PersistenceBrokerException
returns an Identity object representing the current resultset row

Throws:
PersistenceBrokerException

getObjectFromResultSet

protected java.lang.Object getObjectFromResultSet()
                                           throws PersistenceBrokerException
returns a fully materialized Object from the current row of the underlying resultset. Works as follows: - read Identity from the primary key values of current row - check if Object is in cache - return cached object or read it from current row and put it in cache

Throws:
PersistenceBrokerException

getProxyFromResultSet

protected java.lang.Object getProxyFromResultSet()
                                          throws PersistenceBrokerException
Reads primary key information from current RS row and generates a corresponding Identity, and returns a proxy from the Identity.

Throws:
PersistenceBrokerException - if there was an error creating the proxy class

countedSize

protected int countedSize()
                   throws PersistenceBrokerException
Answer the counted size

Returns:
int
Throws:
PersistenceBrokerException

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

autoReleaseDbResources

protected void autoReleaseDbResources()
Internally used by this class to close used resources as soon as possible.


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.


getDescriptorRepository

protected DescriptorRepository getDescriptorRepository()
Return the DescriptorRepository


getConnectionDescriptor

protected JdbcConnectionDescriptor getConnectionDescriptor()

finalize

protected void finalize()
safety just in case someone leaks.


toString

public java.lang.String toString()

getClassDescriptor

public ClassDescriptor getClassDescriptor()
Returns:
Returns the cld.

setBroker

protected void setBroker(PersistenceBrokerImpl broker)

getBroker

protected PersistenceBrokerImpl getBroker()

setRsAndStmt

protected void setRsAndStmt(ResultSetAndStatement rsAndStmt)

getRsAndStmt

protected ResultSetAndStatement getRsAndStmt()

setQueryObject

protected void setQueryObject(RsQueryObject queryObject)

getQueryObject

protected RsQueryObject getQueryObject()

setItemProxyClass

protected void setItemProxyClass(java.lang.Class itemProxyClass)

getItemProxyClass

protected java.lang.Class getItemProxyClass()

setRow

protected void setRow(java.util.Map row)

getRow

protected java.util.Map getRow()

setCache

protected void setCache(InternalCache cache)

getCache

protected InternalCache getCache()

setAfterLookupEvent

protected void setAfterLookupEvent(PBLifeCycleEvent afterLookupEvent)

getAfterLookupEvent

protected PBLifeCycleEvent getAfterLookupEvent()

setHasCalledCheck

protected void setHasCalledCheck(boolean hasCalledCheck)

isHasCalledCheck

protected boolean isHasCalledCheck()

setHasNext

protected void setHasNext(boolean hasNext)

getHasNext

protected boolean getHasNext()

setInBatchedMode

protected void setInBatchedMode(boolean inBatchedMode)

isInBatchedMode

protected boolean isInBatchedMode()


Authors: Thomas Mahler and others. (C) 2000 - 2003 Apache Software Foundation
All rights reserved. Published under the Apache License.
http://db.apache.org/ojb
Version: 1.0.rc5, 2003-12-14