EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.queries
Class CursoredStream

java.lang.Object
  extended by org.eclipse.persistence.queries.Cursor
      extended by 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
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
 
Constructor Summary
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
 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:
- - throws exception if read pass end of stream
DatabaseException
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:
- - throws exception if read pass end of stream
DatabaseException

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


EclipseLink 2.2.0, build 'v20110202-r8913' API Reference