CursoredStream (EclipseLink 2.6.3, API Reference)

java.lang.Object
- org.eclipse.persistence.queries.Cursor
- - org.eclipse.persistence.queries.CursoredStream

All Implemented Interfaces:

java.io.Serializable, java.util.Enumeration, java.util.Iterator
```
public class CursoredStream
extends Cursor
```
Purpose: Stream class which is used to deal with large collections returned from TOPLink queries more efficiently.
Responsibilities: Wraps a database result set cursor to provide a stream on the resulting selected objects.

See Also:
Serialized Form
Author:

Yvon Lavoie

Since:

TOPLink/Java 1.0

Field Summary

Fields
Modifier and Type Field and Description

protected int marker
Marker for backing up.
- Fields inherited from class org.eclipse.persistence.queries.Cursor
  executionSession, fields, initiallyConformingIndex, nextRow, objectCollection, policy, position, query, resultSet, selectionCriteriaClone, session, size, statement, translationRow

Fields
Modifier and Type	Field and Description
`protected int`	`marker` Marker for backing up.

Constructor Summary

Constructors
Constructor and Description
`CursoredStream()` INTERNAL: Initialize the state of the stream
`CursoredStream(org.eclipse.persistence.internal.databaseaccess.DatabaseCall call, CursoredStreamPolicy policy)` INTERNAL: Initialize the state of the stream

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`atEnd()` PUBLIC: Return whether the cursored stream is at its end.
`int`	`available()` PUBLIC: Returns the number of objects that can be read from this input without blocking.
`Expression`	`buildCountDistinctExpression(java.util.List includeFields, ExpressionBuilder builder)` INTERNAL: Must build the count on the primary key fields, not * as * is not allowed if there was a distinct.
`void`	`clear()` PUBLIC: Release all objects read in so far.
`protected java.util.List<java.lang.Object>`	`copy(int startIndex, int endIndex)` INTERNAL: Answer a list of the elements of the receiver's collection from startIndex to endIndex.
`protected int`	`getCursorSize()` INTERNAL: Retrieve the size of the open cursor by executing a count on the same query as the cursor.
`protected int`	`getInitialReadSize()` INTERNAL: Return the threshold for the stream.
`protected int`	`getMarker()` INTERNAL: Return the marker used for mark() & reset() operations.
`int`	`getPageSize()` INTERNAL: Return the page size for the stream.
`int`	`getPosition()` INTERNAL: Return the position of the stream inside the object collection
`boolean`	`hasMoreElements()` PUBLIC: Return whether the cursored stream has any more elements.
`boolean`	`hasNext()` PUBLIC: Return whether the cursored stream has any more elements.
`void`	`mark(int readAheadLimit)` PUBLIC: Mark the present position in the stream.
`boolean`	`markSupported()` PUBLIC: Tests if this input stream supports the `mark` and `reset` methods.
`java.lang.Object`	`next()` PUBLIC: Return the next object from the collection, if beyond the read limit read from the cursor.
`java.util.List<java.lang.Object>`	`next(int numberOfElements)` PUBLIC: Return a Vector of at most numberOfElements of the next objects from the collection.
`java.lang.Object`	`nextElement()` PUBLIC: Return the next object from the collection, if beyond the read limit read from the cursor.
`java.util.Vector`	`nextElements(int numberOfElements)` PUBLIC: Return a Vector of at most numberOfElements of the next objects from the collection.
`java.lang.Object`	`peek()` PUBLIC: Return the next object in the stream, without incrementing the stream's position.
`java.lang.Object`	`read()` PUBLIC: This method differs slightly from conventional read() operation on a Java stream.
`java.util.List<java.lang.Object>`	`read(int number)` PUBLIC: This method differs slightly from conventional read() operation on a Java stream.
`void`	`releasePrevious()` PUBLIC: Release all objects read in so far.
`void`	`reset()` PUBLIC: Repositions this stream to the position at the time the mark method was last called on this stream.
`protected java.lang.Object`	`retrieveNextObject()` INTERNAL: Read the next row from the result set.
`protected java.lang.Object`	`retrieveNextPage()` INTERNAL: Retrieve and add the next page size of rows to the vector.
`protected void`	`setLimits()` INTERNAL: Initialize the stream size and position
`protected void`	`setMarker(int value)` INTERNAL: Set the marker used for mark() & reset() operations

Methods inherited from class org.eclipse.persistence.queries.Cursor
buildAndRegisterObject, close, finalize, getAccessor, getExecutionSession, getFields, getInitiallyConformingIndex, getObjectCollection, getPolicy, getQuery, getResultSet, getSelectionCriteriaClone, getSession, getStatement, getTranslationRow, isClosed, remove, setExecutionSession, setFields, setInitiallyConformingIndex, setObjectCollection, setPolicy, setPosition, setResultSet, setSelectionCriteriaClone, setSession, setSize, setTranslationRow, size

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

- Field Detail
  - marker
```
protected int marker
```
    Marker for backing up.
- Constructor Detail
  - CursoredStream
```
public CursoredStream()
```
    INTERNAL: Initialize the state of the stream
  - CursoredStream
```
public CursoredStream(org.eclipse.persistence.internal.databaseaccess.DatabaseCall call,
              CursoredStreamPolicy policy)
```
    INTERNAL: Initialize the state of the stream
- Method Detail
  - atEnd
```
public boolean atEnd()
              throws DatabaseException
```
    PUBLIC: Return whether the cursored stream is at its end.
    
    Throws:
    
    DatabaseException
  - available
```
public int available()
              throws DatabaseException
```
    PUBLIC: Returns the number of objects that can be read from this input without blocking.
    
    Throws:
    
    DatabaseException
  - buildCountDistinctExpression
```
public Expression buildCountDistinctExpression(java.util.List includeFields,
                                      ExpressionBuilder builder)
```
    INTERNAL: Must build the count on the primary key fields, not * as * is not allowed if there was a distinct. This require a manually defined operator. added for CR 2900
  - copy
```
protected java.util.List<java.lang.Object> copy(int startIndex,
                                    int endIndex)
                                         throws QueryException
```
    INTERNAL: Answer a list of the elements of the receiver's collection from startIndex to endIndex.
    
    Throws:
    
    QueryException
  - getCursorSize
```
protected int getCursorSize()
                     throws DatabaseException,
                            QueryException
```
    INTERNAL: Retrieve the size of the open cursor by executing a count on the same query as the cursor.
    
    Specified by:
    
    getCursorSize in class Cursor
    
    Throws:
    
    DatabaseException
    
    QueryException
  - getInitialReadSize
```
protected int getInitialReadSize()
```
    INTERNAL: Return the threshold for the stream.
  - getMarker
```
protected int getMarker()
```
    INTERNAL: Return the marker used for mark() & reset() operations.
  - getPageSize
```
public int getPageSize()
```
    INTERNAL: Return the page size for the stream.
    
    Overrides:
    
    getPageSize in class Cursor
  - getPosition
```
public int getPosition()
```
    INTERNAL: Return the position of the stream inside the object collection
    
    Specified by:
    
    getPosition in class Cursor
  - hasMoreElements
```
public boolean hasMoreElements()
```
    PUBLIC: Return whether the cursored stream has any more elements.
  - hasNext
```
public boolean hasNext()
```
    PUBLIC: Return whether the cursored stream has any more elements.
  - mark
```
public void mark(int readAheadLimit)
```
    PUBLIC: Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point.
    
    Parameters:
    readAheadLimit - Limit on the number of characters that may be read while still preserving the mark. Because the stream's input comes from the database, there is no actual limit, so this argument is ignored.
  - markSupported
```
public boolean markSupported()
```
    PUBLIC: Tests if this input stream supports the mark and reset methods. The markSupported method of InputStream returns false.
  - nextElement
```
public java.lang.Object nextElement()
```
    PUBLIC: Return the next object from the collection, if beyond the read limit read from the cursor.
    
    Returns:
    the next object in stream
  - next
```
public java.lang.Object next()
```
    PUBLIC: Return the next object from the collection, if beyond the read limit read from the cursor.
    
    Returns:
    the next object in stream
  - nextElements
```
public java.util.Vector nextElements(int numberOfElements)
```
    PUBLIC: Return a Vector of at most numberOfElements of the next objects from the collection. If there aren't that many objects left to read, just return what is available.
    
    Returns:
    the next objects in stream
  - next
```
public java.util.List<java.lang.Object> next(int numberOfElements)
```
    PUBLIC: Return a Vector of at most numberOfElements of the next objects from the collection. If there aren't that many objects left to read, just return what is available.
    
    Returns:
    the next objects in stream
  - peek
```
public java.lang.Object peek()
                      throws DatabaseException
```
    PUBLIC: Return the next object in the stream, without incrementing the stream's position.
    
    Throws:
    
    DatabaseException
  - read
```
public java.lang.Object read()
                      throws DatabaseException,
                             QueryException
```
    PUBLIC: This method differs slightly from conventional read() operation on a Java stream. This method return the next object in the collection rather than specifying the number of bytes to be read in. Return the next object from the collection, if beyond the read limit read from the cursor
    
    Returns:
    - next object in stream
    
    Throws:
    
    DatabaseException - if read pass end of stream
    
    QueryException
  - read
```
public java.util.List<java.lang.Object> read(int number)
                                      throws DatabaseException
```
    PUBLIC: This method differs slightly from conventional read() operation on a Java stream. This method returns the next number of objects in the collection in a vector. Return the next object from the collection, if beyond the read limit read from the cursor
    
    Parameters:
    number - - number of objects to be returned
    
    Returns:
    - vector containing next number of objects
    
    Throws:
    
    DatabaseException - if read pass end of stream
  - clear
```
public void clear()
```
    PUBLIC: Release all objects read in so far. This should be performed when reading in a large collection of objects in order to preserve memory.
    
    Overrides:
    
    clear in class Cursor
  - releasePrevious
```
public void releasePrevious()
```
    PUBLIC: Release all objects read in so far. This should be performed when reading in a large collection of objects in order to preserve memory.
  - reset
```
public void reset()
```
    PUBLIC: Repositions this stream to the position at the time the mark method was last called on this stream.
  - retrieveNextObject
```
protected java.lang.Object retrieveNextObject()
                                       throws DatabaseException
```
    Description copied from class: Cursor
    
    INTERNAL: Read the next row from the result set.
    
    Specified by:
    
    retrieveNextObject in class Cursor
    
    Throws:
    
    DatabaseException
  - retrieveNextPage
```
protected java.lang.Object retrieveNextPage()
                                     throws DatabaseException
```
    INTERNAL: Retrieve and add the next page size of rows to the vector. Return the last object, or null if at end.
    
    Throws:
    
    DatabaseException
  - setLimits
```
protected void setLimits()
```
    INTERNAL: Initialize the stream size and position
  - setMarker
```
protected void setMarker(int value)
```
    INTERNAL: Set the marker used for mark() & reset() operations

Class CursoredStream

Field Summary

Fields inherited from class org.eclipse.persistence.queries.Cursor

Constructor Summary

Method Summary

Methods inherited from class org.eclipse.persistence.queries.Cursor

Methods inherited from class java.lang.Object

Field Detail

marker

Constructor Detail

CursoredStream

CursoredStream

Method Detail

atEnd

available

buildCountDistinctExpression

copy

getCursorSize

getInitialReadSize

getMarker

getPageSize

getPosition

hasMoreElements

hasNext

mark

markSupported

nextElement

next

nextElements

next

peek

read

read

clear

releasePrevious

reset

retrieveNextObject

retrieveNextPage

setLimits

setMarker