ERXFetchSpecificationBatchIterator (Project Wonder Reference Documentation)

java.lang.Object
- er.extensions.eof.ERXFetchSpecificationBatchIterator<E>

Type Parameters:

E - the type of elements returned by this iterator

All Implemented Interfaces:

Enumeration<E>, Iterator<E>
```
public class ERXFetchSpecificationBatchIterator<E>
extends Object
implements Iterator<E>, Enumeration<E>
```
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

Fields
Modifier and Type	Field and Description
`protected int`	`batchSize` holds the selected batch size
`protected NSMutableArray<E>`	`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
`protected String`	`primaryKeyAttributeName` holds the name of the primary key attribute corresponding to the entity being iterated over
`protected 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

Constructors
Constructor and Description
`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, 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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected NSArray<E>`	`_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.
`NSArray<E>`	`batchWithIndex(int index)` Returns the batch corresponding to the given index, that is, the batch beginning at `batchSize()` * index.
`NSArray<E>`	`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.
`E`	`next()` Implementation of the Iterator interface
`NSArray<E>`	`nextBatch()` Gets the next batch of enterprise objects for the given fetch specification.
`E`	`nextElement()` Implementation of the Enumeration interface
`protected 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.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Iterator
forEachRemaining

- 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
  - 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 String primaryKeyAttributeName
```
    holds the name of the primary key attribute corresponding to the entity being iterated over
  - primaryKeys
```
protected NSArray primaryKeys
```
    holds an array of primary key values to iterate through
  - cachedBatch
```
protected NSMutableArray<E> 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,
                                          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 NSArray<E> 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 NSArray<E> _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 NSArray<E> 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 NSArray<E> 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 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 Iterator<E>
  - next
```
public E next()
```
    Implementation of the Iterator interface
    
    Specified by:
    
    next in interface Iterator<E>
  - remove
```
public void remove()
```
    Implementation of the Iterator interface
    
    Specified by:
    
    remove in interface Iterator<E>
  - hasMoreElements
```
public boolean hasMoreElements()
```
    Implementation of the Enumeration interface
    
    Specified by:
    
    hasMoreElements in interface Enumeration<E>
  - nextElement
```
public E nextElement()
```
    Implementation of the Enumeration interface
    
    Specified by:
    
    nextElement in interface Enumeration<E>
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class ERXFetchSpecificationBatchIterator<E>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Field Detail

DefaultBatchSize

batchSize

editingContext

fetchSpecification

primaryKeyAttributeName

primaryKeys

cachedBatch

currentObjectFetchCount

shouldFilterBatches

Constructor Detail

ERXFetchSpecificationBatchIterator

ERXFetchSpecificationBatchIterator

ERXFetchSpecificationBatchIterator

ERXFetchSpecificationBatchIterator

Method Detail

batchSize

currentBatchIndex

batchCount

count

currentObjectFetchCount

setBatchSize

filtersBatches

setFiltersBatches

editingContext

setEditingContext

hasNextBatch

_hasMoreToFetch

nextBatch

_fetchNextBatch

batchWithIndex

batchWithRange

batchFetchSpecificationForQualifier

primaryKeys

reset

hasNext

next

remove

hasMoreElements

nextElement

toString