org.apache.ojb.broker.accesslayer
Class RsIterator

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

All Implemented Interfaces:

Iterator, OJBIterator

Direct Known Subclasses:

ReportQueryRsIterator, SqlBasedRsIterator

public class RsIterator
extends 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.1 2007-08-24 22:17:30 ewestfal 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

private boolean	advancedJDBCSupport
private PBLifeCycleEvent	afterLookupEvent
private boolean	autoRelease Flag that indicates if the automatic resource cleanup should be done or not.
private boolean	disableLifeCycleEvents if true do not fire PBLifeCycleEvent.
private boolean	hasNext return value of the previously called hasNext from m_rs
private static String	INFO_MSG
private boolean	JDBCSupportAssessed
protected Logger	logger
private PersistenceBrokerImpl	m_broker reference to the PersistenceBroker
private MaterializationCache	m_cache
private int	m_current_row
private boolean	m_hasCalledCheck flag that indicates wether hasNext on m_rs has allready been called
private boolean	m_inBatchedMode prefetch relationship: inBatchedMode true prevents releasing of DbResources IN_LIMIT defines the max number of values of sql (IN) , -1 for no limits
private Class	m_itemProxyClass the proxy class to be used or null
private Class	m_itemTopLevelClass the top-level class of the item objects
private RsQueryObject	m_queryObject the underlying query object
private Map	m_row this container holds the values of the current ro during materialisation
private ResultSetAndStatement	m_rsAndStmt the underlying resultset
private RsIterator.ResourceWrapper	resourceListener
private boolean	resourcesAreReleased Tracks whether or not the resources that are used by this class have been released.

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.
private boolean	absoluteAdvanced(int row) absolute for advancedJDBCSupport
private boolean	absoluteBasic(int row) absolute for basicJDBCSupport
protected void	autoReleaseDbResources() Internally used by this class to close used resources as soon as possible.
protected int	countedSize() Answer the counted size
void	disableLifeCycleEvents() Do not fire any PBLifeCycleEvent when reading next item.
protected void	finalize() safety just in case someone leaks.
int	fullSize()
protected PBLifeCycleEvent	getAfterLookupEvent()
protected PersistenceBrokerInternal	getBroker()
protected MaterializationCache	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 Class	getItemProxyClass()
protected Object	getObjectFromResultSet() returns a fully materialized Object from the current row of the underlying resultset.
private Collection	getOwnerObjects() read all objects of this iterator.
protected 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 Map	getRow()
protected ResultSetAndStatement	getRsAndStmt()
protected Class	getTopLevelClass()
boolean	hasNext() returns true if there are still more rows in the underlying ResultSet.
protected boolean	isHasCalledCheck()
protected boolean	isInBatchedMode()
Object	next() moves to the next row of the underlying ResultSet and returns the corresponding Object materialized from this row.
private void	prefetchRelationships(Query query) prefetch defined relationships requires JDBC level 2.0, does not work with Arrays
boolean	relative(int row) Moves the cursor a relative number of rows, either positive or negative.
(package private) void	release(boolean removeResourceListener)
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(MaterializationCache cache)
protected void	setHasCalledCheck(boolean hasCalledCheck)
protected void	setHasNext(boolean hasNext)
protected void	setInBatchedMode(boolean inBatchedMode)
protected void	setItemProxyClass(Class itemProxyClass)
protected void	setQueryObject(RsQueryObject queryObject)
protected void	setRow(Map row)
protected void	setRsAndStmt(ResultSetAndStatement rsAndStmt)
int	size()
private boolean	supportsAdvancedJDBCCursorControl() with a new batch of JDBC 3.0 drivers coming out we can't just check for begins with 2, we need to check the actual version and see if it's greater than or equal to 2.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected Logger logger

INFO_MSG

private static final String INFO_MSG

See Also:

Constant Field Values

afterLookupEvent

private PBLifeCycleEvent afterLookupEvent

m_cache

private MaterializationCache m_cache

m_broker

private PersistenceBrokerImpl m_broker

reference to the PersistenceBroker

m_rsAndStmt

private ResultSetAndStatement m_rsAndStmt

the underlying resultset

m_queryObject

private RsQueryObject m_queryObject

the underlying query object

m_itemProxyClass

private Class m_itemProxyClass

the proxy class to be used or null

m_itemTopLevelClass

private Class m_itemTopLevelClass

the top-level class of the item objects

m_row

private Map m_row

this container holds the values of the current ro during materialisation

m_hasCalledCheck

private boolean m_hasCalledCheck

flag that indicates wether hasNext on m_rs has allready been called

m_inBatchedMode

private boolean m_inBatchedMode

prefetch relationship: inBatchedMode true prevents releasing of DbResources IN_LIMIT defines the max number of values of sql (IN) , -1 for no limits

hasNext

private boolean hasNext

return value of the previously called hasNext from m_rs

advancedJDBCSupport

private boolean advancedJDBCSupport

JDBCSupportAssessed

private boolean JDBCSupportAssessed

m_current_row

private int m_current_row

resourcesAreReleased

private boolean resourcesAreReleased

Tracks whether or not the resources that are used by this class have been released.

autoRelease

private boolean autoRelease

Flag that indicates if the automatic resource cleanup should be done or not. Default is true.

resourceListener

private RsIterator.ResourceWrapper resourceListener

disableLifeCycleEvents

private boolean disableLifeCycleEvents

if true do not fire PBLifeCycleEvent.

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 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 Iterator

next

public Object next()
            throws NoSuchElementException

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

Specified by:

next in interface Iterator

Throws:

NoSuchElementException

remove

public void remove()

removing is not supported

Specified by:

remove in interface Iterator

getOwnerObjects

private Collection getOwnerObjects()

read all objects of this iterator. objects will be placed in cache

prefetchRelationships

private void prefetchRelationships(Query query)

prefetch defined relationships requires JDBC level 2.0, does not work with Arrays

getIdentityFromResultSet

protected Identity getIdentityFromResultSet()
                                     throws PersistenceBrokerException

returns an Identity object representing the current resultset row

Throws:

PersistenceBrokerException

getObjectFromResultSet

protected 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 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

supportsAdvancedJDBCCursorControl

private boolean supportsAdvancedJDBCCursorControl()

with a new batch of JDBC 3.0 drivers coming out we can't just check for begins with 2, we need to check the actual version and see if it's greater than or equal to 2.

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

absoluteBasic

private boolean absoluteBasic(int row)

absolute for basicJDBCSupport

Parameters:

row -

absoluteAdvanced

private boolean absoluteAdvanced(int row)

absolute for advancedJDBCSupport

Parameters:

row -

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

release

void release(boolean removeResourceListener)

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.

Overrides:

finalize in class Object

toString

public String toString()

Overrides:

toString in class Object

getClassDescriptor

public ClassDescriptor getClassDescriptor()

Returns:

Returns the cld.

setBroker

protected void setBroker(PersistenceBrokerImpl broker)

getBroker

protected PersistenceBrokerInternal 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(Class itemProxyClass)

getItemProxyClass

protected Class getItemProxyClass()

setRow

protected void setRow(Map row)

getRow

protected Map getRow()

setCache

protected void setCache(MaterializationCache cache)

getCache

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

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