Package org.eclipse.persistence.queries

Class 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

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      Cursor()
      INTERNAL: Default constructor.
      Cursor​(org.eclipse.persistence.internal.databaseaccess.DatabaseCall call, CursorPolicy policy)
      INTERNAL:

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      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

        asIterator, hasMoreElements, nextElement

      • Methods inherited from interface java.util.Iterator

        forEachRemaining, 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

      • getAccessor

        public org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor getAccessor()
        INTERNAL: Return the accessor associated with the cursor.

      • 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.