org.eclipse.persistence.queries
Class Cursor

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

All Implemented Interfaces:

java.io.Serializable, java.util.Enumeration, java.util.Iterator

Direct Known Subclasses:

CursoredStream, ScrollableCursor

public abstract class Cursor
extends java.lang.Object
implements java.util.Enumeration, java.util.Iterator, java.io.Serializable

Purpose: Abstract class for CursoredStream and ScrolableCursor

See Also:

Serialized Form

Field Summary

protected org.eclipse.persistence.internal.sessions.AbstractSession	executionSession The root session that executed the call for the query.
protected java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField>	fields The fields expected in the result set.
protected java.util.Map<java.lang.Object,java.lang.Object>	initiallyConformingIndex Conforming instances found in memory when building the result.
protected org.eclipse.persistence.internal.sessions.AbstractRecord	nextRow Store the next row, for 1-m joining.
protected java.util.List<java.lang.Object>	objectCollection Internal collection of objects.
CursorPolicy	policy Query policy that initialize the stream.
protected int	position Current position in the objectCollection of the stream.
ReadQuery	query Read query that initialize the stream.
protected java.sql.ResultSet	resultSet The result set (cursor) that holds the handle to the database that the results are read from.
protected Expression	selectionCriteriaClone SelectionCriteria & translation row ready for incremental conforming.
protected org.eclipse.persistence.internal.sessions.AbstractSession	session The session that executed the query for the stream.
protected int	size Cached size of the stream.
protected java.sql.Statement	statement The preparedStatement that holds the handle to the database that the results are read from.
protected org.eclipse.persistence.internal.sessions.AbstractRecord	translationRow

Constructor Summary

Cursor()
INTERNAL: Default constructor.

Cursor(org.eclipse.persistence.internal.databaseaccess.DatabaseCall call, CursorPolicy policy)
INTERNAL:

Method Summary

protected java.lang.Object	buildAndRegisterObject(org.eclipse.persistence.internal.sessions.AbstractRecord row) INTERNAL: builds and registers an object from a row for cursors.
void	clear() PUBLIC: Release all objects read in so far.
void	close() PUBLIC: Closes the stream.
protected void	finalize() Close in case not closed.
org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor	getAccessor() INTERNAL: Return the accessor associated with the cursor.
protected abstract int	getCursorSize() INTERNAL: Retrieve the size of the open cursor by executing a count on the same query as the cursor.
org.eclipse.persistence.internal.sessions.AbstractSession	getExecutionSession() INTERNAL: Returns the session the underlying call was executed on.
java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField>	getFields() INTERNAL: Return the fields for the stream.
java.util.Map<java.lang.Object,java.lang.Object>	getInitiallyConformingIndex() INTERNAL: Conforming instances found in memory when building the result.
java.util.List<java.lang.Object>	getObjectCollection() INTERNAL: Return the internal object collection that stores the objects.
int	getPageSize() INTERNAL: Return the number of items to be faulted in for the stream.
CursorPolicy	getPolicy() INTERNAL: Return the cursor policy.
abstract int	getPosition() INTERNAL: Return the position of the stream inside the object collection.
ReadQuery	getQuery() INTERNAL: Return the query associated with the stream.
java.sql.ResultSet	getResultSet() INTERNAL: Return the result set (cursor).
Expression	getSelectionCriteriaClone() INTERNAL: The clone of the selection criteria is needed for in-memory conforming each object read from the Cursor.
org.eclipse.persistence.internal.sessions.AbstractSession	getSession() INTERNAL: Return the handle to the session
protected java.sql.Statement	getStatement() INTERNAL: Return the Statement.
protected org.eclipse.persistence.internal.sessions.AbstractRecord	getTranslationRow() INTERNAL: Gets the translation row the query was executed with, used for incremental conforming.
boolean	isClosed() PUBLIC: Return if the stream is closed.
void	remove() PUBLIC: Remove is not support with cursors.
protected abstract java.lang.Object	retrieveNextObject() INTERNAL: Read the next row from the result set.
protected void	setExecutionSession(org.eclipse.persistence.internal.sessions.AbstractSession executionSession) INTERNAL: Sets the session the underlying call was executed on.
protected void	setFields(java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> fields) INTERNAL: Set the fields for the stream.
void	setInitiallyConformingIndex(java.util.Map<java.lang.Object,java.lang.Object> index) INTERNAL: Conforming instances found in memory when building the result.
void	setObjectCollection(java.util.List<java.lang.Object> collection) INTERNAL: Set the internal object collection
void	setPolicy(CursorPolicy policy) INTERNAL: Set the cursor policy.
protected void	setPosition(int value) INTERNAL: Set the current position of the stream
protected void	setResultSet(java.sql.ResultSet result) INTERNAL: Set the result set (cursor)
void	setSelectionCriteriaClone(Expression expression) INTERNAL: The clone of the selection criteria is needed for in-memory conforming each object read from the Cursor.
void	setSession(org.eclipse.persistence.internal.sessions.AbstractSession databaseSession) INTERNAL: Set the session handle
void	setSize(int size) INTERNAL: Set the cache size
void	setTranslationRow(org.eclipse.persistence.internal.sessions.AbstractRecord row) INTERNAL: Sets the translation row this query was executed with.
int	size() PUBLIC: Retrieve the size of the open cursor by executing a count on the same query as the cursor.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Enumeration

hasMoreElements, nextElement

Methods inherited from interface java.util.Iterator

hasNext, next

Field Detail

statement

protected transient java.sql.Statement statement

The preparedStatement that holds the handle to the database that the results are read from.

resultSet

protected transient java.sql.ResultSet resultSet

The result set (cursor) that holds the handle to the database that the results are read from.

session

protected transient org.eclipse.persistence.internal.sessions.AbstractSession session

The session that executed the query for the stream.

executionSession

protected transient org.eclipse.persistence.internal.sessions.AbstractSession executionSession

The root session that executed the call for the query. Knows the database platform.

fields

protected transient java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> fields

The fields expected in the result set.

size

protected int size

Cached size of the stream.

query

public transient ReadQuery query

Read query that initialize the stream.

policy

public transient CursorPolicy policy

Query policy that initialize the stream.

objectCollection

protected java.util.List<java.lang.Object> objectCollection

Internal collection of objects.

initiallyConformingIndex

protected java.util.Map<java.lang.Object,java.lang.Object> initiallyConformingIndex

Conforming instances found in memory when building the result.

selectionCriteriaClone

protected Expression selectionCriteriaClone

SelectionCriteria & translation row ready for incremental conforming.

translationRow

protected org.eclipse.persistence.internal.sessions.AbstractRecord translationRow

nextRow

protected org.eclipse.persistence.internal.sessions.AbstractRecord nextRow

Store the next row, for 1-m joining.

position

protected int position

Current position in the objectCollection of the stream.

Constructor Detail

Cursor

public Cursor()

INTERNAL: Default constructor.

Cursor

public Cursor(org.eclipse.persistence.internal.databaseaccess.DatabaseCall call,
              CursorPolicy policy)

INTERNAL:

Method Detail

close

public void close()
           throws DatabaseException

PUBLIC: Closes the stream. This should be performed whenever the user has finished with the stream.

Throws:

DatabaseException

finalize

protected void finalize()
                 throws DatabaseException

Close in case not closed.

Overrides:

finalize in class java.lang.Object

Throws:

DatabaseException

getAccessor

public org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor getAccessor()

INTERNAL: Return the accessor associated with the cursor.

getCursorSize

protected abstract int getCursorSize()
                              throws DatabaseException,
                                     QueryException

INTERNAL: Retrieve the size of the open cursor by executing a count on the same query as the cursor.

Throws:

DatabaseException

QueryException

getFields

public java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> getFields()

INTERNAL: Return the fields for the stream.

getInitiallyConformingIndex

public java.util.Map<java.lang.Object,java.lang.Object> getInitiallyConformingIndex()

INTERNAL: Conforming instances found in memory when building the result. These objects are returned first by the cursor, and a fast lookup is needed to make sure the same objects appearing in the cursor are filtered out.

getObjectCollection

public java.util.List<java.lang.Object> getObjectCollection()

INTERNAL: Return the internal object collection that stores the objects.

getPageSize

public int getPageSize()

INTERNAL: Return the number of items to be faulted in for the stream.

getPolicy

public CursorPolicy getPolicy()

INTERNAL: Return the cursor policy.

getPosition

public abstract int getPosition()

INTERNAL: Return the position of the stream inside the object collection.

getQuery

public ReadQuery getQuery()

INTERNAL: Return the query associated with the stream.

getResultSet

public java.sql.ResultSet getResultSet()

INTERNAL: Return the result set (cursor).

getSelectionCriteriaClone

public Expression getSelectionCriteriaClone()

INTERNAL: The clone of the selection criteria is needed for in-memory conforming each object read from the Cursor.

getSession

public org.eclipse.persistence.internal.sessions.AbstractSession getSession()

INTERNAL: Return the handle to the session

getExecutionSession

public org.eclipse.persistence.internal.sessions.AbstractSession getExecutionSession()

INTERNAL: Returns the session the underlying call was executed on. This root session knows the database platform.

getStatement

protected java.sql.Statement getStatement()

INTERNAL: Return the Statement.

getTranslationRow

protected org.eclipse.persistence.internal.sessions.AbstractRecord getTranslationRow()

INTERNAL: Gets the translation row the query was executed with, used for incremental conforming.

isClosed

public boolean isClosed()

PUBLIC: Return if the stream is closed.

buildAndRegisterObject

protected java.lang.Object buildAndRegisterObject(org.eclipse.persistence.internal.sessions.AbstractRecord row)

INTERNAL: builds and registers an object from a row for cursors. Behavior is different from the query version in that refreshing is not supported.

retrieveNextObject

protected abstract java.lang.Object retrieveNextObject()
                                                throws DatabaseException

INTERNAL: Read the next row from the result set.

Throws:

DatabaseException

setFields

protected void setFields(java.util.Vector<org.eclipse.persistence.internal.helper.DatabaseField> fields)

INTERNAL: Set the fields for the stream.

setInitiallyConformingIndex

public void setInitiallyConformingIndex(java.util.Map<java.lang.Object,java.lang.Object> index)

INTERNAL: Conforming instances found in memory when building the result. These objects are returned first by the cursor, and a fast lookup is needed to make sure the same objects appearing in the cursor are filtered out.

setObjectCollection

public void setObjectCollection(java.util.List<java.lang.Object> collection)

INTERNAL: Set the internal object collection

setPolicy

public void setPolicy(CursorPolicy policy)

INTERNAL: Set the cursor policy.

setPosition

protected void setPosition(int value)

INTERNAL: Set the current position of the stream

setResultSet

protected void setResultSet(java.sql.ResultSet result)

INTERNAL: Set the result set (cursor)

setSelectionCriteriaClone

public void setSelectionCriteriaClone(Expression expression)

INTERNAL: The clone of the selection criteria is needed for in-memory conforming each object read from the Cursor.

setSession

public void setSession(org.eclipse.persistence.internal.sessions.AbstractSession databaseSession)

INTERNAL: Set the session handle

setExecutionSession

protected void setExecutionSession(org.eclipse.persistence.internal.sessions.AbstractSession executionSession)

INTERNAL: Sets the session the underlying call was executed on. This root session knows the database platform.

setSize

public void setSize(int size)

INTERNAL: Set the cache size

setTranslationRow

public void setTranslationRow(org.eclipse.persistence.internal.sessions.AbstractRecord row)

INTERNAL: Sets the translation row this query was executed with. Used for incremental conforming.

size

public int size()
         throws DatabaseException

PUBLIC: Retrieve the size of the open cursor by executing a count on the same query as the cursor. If this cursor is conforming size() can only be an estimate. cursor size plus number of conforming instances found in memory will be returned. The union (actual result) may be smaller than this.

Throws:

DatabaseException

remove

public void remove()
            throws QueryException

PUBLIC: Remove is not support with cursors.

Specified by:

remove in interface java.util.Iterator

Throws:

QueryException

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.