er.extensions.eof
Class ERXFetchSpecificationBatchIterator

java.lang.Object
  er.extensions.eof.ERXFetchSpecificationBatchIterator

All Implemented Interfaces:

java.util.Enumeration, java.util.Iterator

public class ERXFetchSpecificationBatchIterator
extends java.lang.Object
implements java.util.Iterator, java.util.Enumeration

The goal of the fetch specification batch iterator is to have the ability to iterate through a fetch specification that might fetch one million enterprise objects. Fetching all of the objects into a single editing context is prohibitive in the amount of memory needed and in the time taken to process all of the rows.
The iterator allows one to iterate through the fetched objects only hydrating those objects need in small bite size pieces. The iterator also allows you to swap out editing contexts between calls to nextBatch(), which will allow the garbage collector to collect the old editing context and the previous batch of enterprise objects.
For your convenience, this class also implements Iterator and Enumeration, so you can use it as such.
Be aware that the batch size is primarily intended to govern the number of objects requested from the database at once, and may differ from the number of objects returned by nextBatch(), for instance if the batch size is changed after fetching, or if filtersBatches() is set to true.

Field Summary

protected int	batchSize holds the selected batch size
protected com.webobjects.foundation.NSMutableArray	cachedBatch holds array of fetched but not-yet-returned objects; used by the Iterator and Enumeration interfaces
protected int	currentObjectFetchCount holds the number of objects fetched
static int	DefaultBatchSize holds the default batch size, any bigger than this an Oracle has a fit
protected com.webobjects.eocontrol.EOEditingContext	editingContext holds a reference to the selected editing context
protected com.webobjects.eocontrol.EOFetchSpecification	fetchSpecification holds a reference to the fetch spec to iterate over
static org.apache.log4j.Logger	log logging support
protected java.lang.String	primaryKeyAttributeName holds the name of the primary key attribute corresponding to the entity being iterated over
protected com.webobjects.foundation.NSArray	primaryKeys holds an array of primary key values to iterate through
protected boolean	shouldFilterBatches determines whether we should re-apply the original qualifier to each batch of objects fetched

Constructor Summary

ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification)
Constructs a fetch specification iterator for a given fetch specification with the default batch size.

ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext ec)
Constructs a fetch specification iterator for a given fetch specification with the default batch size.

ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.eocontrol.EOEditingContext ec, int batchSize)
Constructs a fetch specification iterator for a given fetch specification and a batch size.

ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification, com.webobjects.foundation.NSArray pkeys, com.webobjects.eocontrol.EOEditingContext ec, int batchSize)
Constructs a fetch specification iterator for a fetch specification, an optional set of pre-fetched primary keys and a batch size.

Method Summary

protected com.webobjects.foundation.NSArray	_fetchNextBatch() Fetches the next batch unconditionally.
protected boolean	_hasMoreToFetch()
int	batchCount() Gets the number of batches for a given iterator.
protected com.webobjects.eocontrol.EOFetchSpecification	batchFetchSpecificationForQualifier(com.webobjects.eocontrol.EOQualifier qualifier)
int	batchSize() Gets the batch size.
com.webobjects.foundation.NSArray	batchWithIndex(int index) Returns the batch corresponding to the given index, that is, the batch beginning at batchSize() * index.
com.webobjects.foundation.NSArray	batchWithRange(com.webobjects.foundation.NSRange requestedRange) Returns the batch corresponding to the given range.
int	count() Gets the number of objects.
int	currentBatchIndex() Gets the current batch index.
int	currentObjectFetchCount() Gets the current number of objects fetched thus far.
com.webobjects.eocontrol.EOEditingContext	editingContext() Gets the currently set editing context.
boolean	filtersBatches() If true, each batch will be filtered based on the original qualifier.
boolean	hasMoreElements() Implementation of the Enumeration interface
boolean	hasNext() Implementation of the Iterator interface
boolean	hasNextBatch() Determines if the iterator has another batch.
java.lang.Object	next() Implementation of the Iterator interface
com.webobjects.foundation.NSArray	nextBatch() Gets the next batch of enterprise objects for the given fetch specification.
java.lang.Object	nextElement() Implementation of the Enumeration interface
protected com.webobjects.foundation.NSArray	primaryKeys() Method used to fetch the primary keys of the objects for the given fetch specification.
void	remove() Implementation of the Iterator interface
void	reset() Resets the batch iterator so it will refetch its primary keys again.
void	setBatchSize(int batchSize) Sets the batch size.
void	setEditingContext(com.webobjects.eocontrol.EOEditingContext ec) Sets the editing context used to fetch objects against.
void	setFiltersBatches(boolean newValue) If set to true, each batch fetched will be filtered based on the qualifier attached to the original fetch specification.

Methods inherited from class java.lang.Object

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

Field Detail

DefaultBatchSize

public static final int DefaultBatchSize

holds the default batch size, any bigger than this an Oracle has a fit

See Also:

Constant Field Values

log

public static final org.apache.log4j.Logger log

logging support

batchSize

protected int batchSize

holds the selected batch size

editingContext

protected com.webobjects.eocontrol.EOEditingContext editingContext

holds a reference to the selected editing context

fetchSpecification

protected com.webobjects.eocontrol.EOFetchSpecification fetchSpecification

holds a reference to the fetch spec to iterate over

primaryKeyAttributeName

protected java.lang.String primaryKeyAttributeName

holds the name of the primary key attribute corresponding to the entity being iterated over

primaryKeys

protected com.webobjects.foundation.NSArray primaryKeys

holds an array of primary key values to iterate through

cachedBatch

protected com.webobjects.foundation.NSMutableArray cachedBatch

holds array of fetched but not-yet-returned objects; used by the Iterator and Enumeration interfaces

currentObjectFetchCount

protected int currentObjectFetchCount

holds the number of objects fetched

shouldFilterBatches

protected boolean shouldFilterBatches

determines whether we should re-apply the original qualifier to each batch of objects fetched

Constructor Detail

ERXFetchSpecificationBatchIterator

public ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification)

Constructs a fetch specification iterator for a given fetch specification with the default batch size. Note you will have to set an editingContext on the iterator before calling the nextBatch method.

Parameters:

fetchSpecification - to iterate through

ERXFetchSpecificationBatchIterator

public ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification,
                                          com.webobjects.eocontrol.EOEditingContext ec)

Constructs a fetch specification iterator for a given fetch specification with the default batch size. All objects will be fetched from the given editing context. Note that you can switch out different editing contexts between calls to nextBatch

Parameters:

fetchSpecification - to iterate through

ec - editing context to fetch against

ERXFetchSpecificationBatchIterator

public ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification,
                                          com.webobjects.eocontrol.EOEditingContext ec,
                                          int batchSize)

Constructs a fetch specification iterator for a given fetch specification and a batch size. All objects will be fetched from the given editing context. Note that you can switch out different editing contexts between calls to nextBatch

Parameters:

fetchSpecification - to iterate through

ec - editing context to fetch against

batchSize - number of objects to fetch in a given batch

ERXFetchSpecificationBatchIterator

public ERXFetchSpecificationBatchIterator(com.webobjects.eocontrol.EOFetchSpecification fetchSpecification,
                                          com.webobjects.foundation.NSArray pkeys,
                                          com.webobjects.eocontrol.EOEditingContext ec,
                                          int batchSize)

Constructs a fetch specification iterator for a fetch specification, an optional set of pre-fetched primary keys and a batch size. All objects will be fetched from the given editing context. Note that you can switch out different editing contexts between calls to nextBatch.

Note: if no ec is supplied a new one is initialized.

Parameters:

fetchSpecification - to iterate through

pkeys - primary keys to iterate through

ec - editing context to fetch against

batchSize - number of objects to fetch in a given batch

Method Detail

batchSize

public int batchSize()

Gets the batch size.

Returns:

number of enterprise objects to fetch a batch.

currentBatchIndex

public int currentBatchIndex()

Gets the current batch index.

Returns:

number of batches fetched thus far

batchCount

public int batchCount()

Gets the number of batches for a given iterator.

Returns:

number of objects / batch size rounded up

count

public int count()

Gets the number of objects.

Returns:

number of objects

currentObjectFetchCount

public int currentObjectFetchCount()

Gets the current number of objects fetched thus far.

Returns:

current number of objects fetched.

setBatchSize

public void setBatchSize(int batchSize)

Sets the batch size.

Parameters:

batchSize - to be set.

filtersBatches

public boolean filtersBatches()

If true, each batch will be filtered based on the original qualifier.

Returns:

whether batches will be re-filtered

See Also:

setFiltersBatches(boolean)

setFiltersBatches

public void setFiltersBatches(boolean newValue)

If set to true, each batch fetched will be filtered based on the qualifier attached to the original fetch specification. The is useful to cover the case in which the objects may have changed in important ways between the time their primary keys were retrieved and the time they were fetched. Note that when filtering is on, empty arrays may be returned from nextBatch(), and null may be returned from next() and nextElement(). Note that not all qualifiers can be applied in-memory, so this should not bet set to true if such a qualifier is being used. Defaults to false.

Parameters:

newValue - whether batches should be re-filtered

editingContext

public com.webobjects.eocontrol.EOEditingContext editingContext()

Gets the currently set editing context.

Returns:

editing context used to fetch against

setEditingContext

public void setEditingContext(com.webobjects.eocontrol.EOEditingContext ec)

Sets the editing context used to fetch objects against. It is perfectly fine to change editing contexts between fetching the next batch.

Parameters:

ec - editing context used to fetch against

hasNextBatch

public boolean hasNextBatch()

Determines if the iterator has another batch.

Returns:

if ok to call nextBatch()

_hasMoreToFetch

protected boolean _hasMoreToFetch()

nextBatch

public com.webobjects.foundation.NSArray nextBatch()

Gets the next batch of enterprise objects for the given fetch specification. Note that the editing context that is set will be used to fetch against. You can swap out a different editing context before calling this method to reduce memory consumption. (However, if you are mixing calls to this method with calls to next() or nextElement(), this method may return a partial batch of already-cached objects, in the editing context which was in place at the time they were fetched.)

Returns:

batch of enterprise objects

_fetchNextBatch

protected com.webobjects.foundation.NSArray _fetchNextBatch()

Fetches the next batch unconditionally. Subclasses can override this rather than nextBatch(), to get automatic support for the Iterator and Enumeration interfaces.

Returns:

next batch

batchWithIndex

public com.webobjects.foundation.NSArray batchWithIndex(int index)

Returns the batch corresponding to the given index, that is, the batch beginning at batchSize() * index. Note that if the batch size has been changed after fetching, the batches return by nextBatch() may not line up with the batches returned by this method. Calling this method does not affect the position of the iterator.

Parameters:

index - index of batch to retrieve

Returns:

batch of enterprise objects

batchWithRange

public com.webobjects.foundation.NSArray batchWithRange(com.webobjects.foundation.NSRange requestedRange)

Returns the batch corresponding to the given range. If the supplied range does not fall within the available range, the results returned correspond to the intersection of the two. If no items are found, the supplied range does not intersect the available range, or the supplied range has length zero, then an empty array is returned. Calling this method does not affect the position of the iterator.

Parameters:

requestedRange - range of batch to retrieve

Returns:

batch of enterprise objects

batchFetchSpecificationForQualifier

protected com.webobjects.eocontrol.EOFetchSpecification batchFetchSpecificationForQualifier(com.webobjects.eocontrol.EOQualifier qualifier)

primaryKeys

protected com.webobjects.foundation.NSArray primaryKeys()

Method used to fetch the primary keys of the objects for the given fetch specification. Note the sort orderings for the fetch specification are respected.

Returns:

array of primary keys to iterate over

reset

public void reset()

Resets the batch iterator so it will refetch its primary keys again.

hasNext

public boolean hasNext()

Implementation of the Iterator interface

Specified by:

hasNext in interface java.util.Iterator

next

public java.lang.Object next()

Implementation of the Iterator interface

Specified by:

next in interface java.util.Iterator

remove

public void remove()

Implementation of the Iterator interface

Specified by:

remove in interface java.util.Iterator

hasMoreElements

public boolean hasMoreElements()

Implementation of the Enumeration interface

Specified by:

hasMoreElements in interface java.util.Enumeration

nextElement

public java.lang.Object nextElement()

Implementation of the Enumeration interface

Specified by:

nextElement in interface java.util.Enumeration