Class ResultSetCursor<T extends PersistentDomainObject<T>>

java.lang.Object
org.tentackle.persist.ResultSetCursor<T>
Type Parameters:
T - the retrieved type
All Implemented Interfaces:
AutoCloseable, org.tentackle.misc.ScrollableResource<T>

public class ResultSetCursor<T extends PersistentDomainObject<T>> extends Object implements org.tentackle.misc.ScrollableResource<T>
A cursor streaming PDOs from a query result.

The same class serves local and remote sessions: for a local session the cursor wraps a ResultSetWrapper, for a remote session it forwards all calls to a RemoteResultSetCursor on the server, which in turn wraps a local cursor there. The application code is the same in both cases.

A local cursor may carry a JoinedSelect to load eager relations along with their root PDOs. Since several rows make up a single PDO then, the query must be sorted by the root's ID and the cursor supports forward navigation only: setRow(int), scroll(int), last(), previous() and afterLast() throw a PersistenceException.

A cursor must be closed. If it becomes unreachable before, it is closed by a Cleaner and a warning is logged.

Author:
harald
  • Constructor Details

    • ResultSetCursor

      public ResultSetCursor(T pdo, ResultSetWrapper rs, JoinedSelect<T> js)
      Creates a cursor for a local session.
      Parameters:
      pdo - the PDO proxy
      rs - the result set
      js - the join configuration, null if no joins
    • ResultSetCursor

      public ResultSetCursor(T pdo, ResultSetWrapper rs)
      Creates a cursor for a local session.
      Parameters:
      pdo - the PDO proxy
      rs - the result set
    • ResultSetCursor

      public ResultSetCursor(DomainContext context, RemoteResultSetCursor<T> remoteCursor)
      Creates a cursor for a remote session.
      Parameters:
      context - the domain context
      remoteCursor - the remote cursor
  • Method Details

    • getResultSet

      public ResultSetWrapper getResultSet()
      Gets the result set.
      Returns:
      the result set, null if closed
      Throws:
      org.tentackle.session.PersistenceException - if session is remote
    • getJoinedSelect

      public JoinedSelect<T> getJoinedSelect()
      Gets the join configuration.
      Returns:
      the join configuration, null if no joins
      Throws:
      org.tentackle.session.PersistenceException - if session is remote
    • getRemoteCursor

      public RemoteResultSetCursor<T> getRemoteCursor()
      Gets the remote cursor.
      Returns:
      the remote cursor, null if closed
      Throws:
      org.tentackle.session.PersistenceException - if session is local
    • getSession

      public org.tentackle.session.Session getSession()
      Gets the session.
      Returns:
      the session
    • getDomainContext

      public DomainContext getDomainContext()
      Gets the domain context.
      Returns:
      the context
    • close

      public void close()
      Closes the cursor.
      The cursor is opened in its constructor. Closing an already closed cursor is allowed.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
    • isClosed

      public boolean isClosed()
      Returns whether the cursor is closed.
      Specified by:
      isClosed in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if closed
    • getRow

      public int getRow()
      Gets the current row.
      Row numbers start at 1.
      Specified by:
      getRow in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the current row, 0 if before first row
    • setRow

      public boolean setRow(int row)
      Sets the cursor to a given row.
      Row numbers start at 1.
      Specified by:
      setRow in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Parameters:
      row - the row number (must be ≥ 0)
      Returns:
      true if done, false if no such row and the cursor is now before the first row or after the last row
      Throws:
      org.tentackle.session.PersistenceException - if row < 0 or the cursor has joins
    • first

      public boolean first()
      Rewinds the cursor to the first row.
      Specified by:
      first in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if rewound, false if cursor is empty
    • last

      public boolean last()
      Positions the cursor on the last row.
      Specified by:
      last in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if positioned, false if cursor is empty
      Throws:
      org.tentackle.session.PersistenceException - if the cursor has joins
    • next

      public boolean next()
      Moves the cursor to the next row.
      If there are no more rows the current row remains unchanged.
      Specified by:
      next in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if moved, false if no more rows
    • previous

      public boolean previous()
      Moves the cursor to the previous row.
      If there is no previous row, the cursor is positioned before the first row.
      Specified by:
      previous in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if moved, false if already at or before the first row
      Throws:
      org.tentackle.session.PersistenceException - if the cursor has joins
    • scroll

      public boolean scroll(int rows)
      Moves the cursor a given number of rows.
      Specified by:
      scroll in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Parameters:
      rows - the number of rows to move, negative to move backwards
      Returns:
      true if moved, false if no such row and the cursor is now positioned before the first row or after the last row
      Throws:
      org.tentackle.session.PersistenceException - if the cursor has joins
    • beforeFirst

      public void beforeFirst()
      Positions the cursor before the first row.
      Works even for empty cursors.
      Specified by:
      beforeFirst in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
    • afterLast

      public void afterLast()
      Positions the cursor after the last row.
      Works even for empty cursors.
      Specified by:
      afterLast in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Throws:
      org.tentackle.session.PersistenceException - if the cursor has joins
    • isBeforeFirst

      public boolean isBeforeFirst()
      Checks whether the cursor is before the first row.
      Specified by:
      isBeforeFirst in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if before first
    • isAfterLast

      public boolean isAfterLast()
      Checks whether the cursor is after the last row.
      Specified by:
      isAfterLast in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      true if after last
    • get

      public T get()
      Gets the PDO of the current row.

      For cursors with joins, the PDO is assembled from all consecutive rows belonging to it. Hence, the underlying result set is advanced up to the first row of the next PDO.

      Specified by:
      get in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the PDO, null if invalid row or no such PDO
    • toList

      public List<T> toList()
      Returns the PDOs of this cursor as a list.
      The cursor is rewound to the first row before. For remote sessions, the list is created on the server and transferred in a single round trip.
      Specified by:
      toList in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the list
    • toListAndClose

      public List<T> toListAndClose()
      Returns the PDOs of this cursor as a list and closes this cursor.
      Specified by:
      toListAndClose in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the list
    • setFetchSize

      public void setFetchSize(int rows)
      Sets the fetch size.
      This is the number of rows the cursor will fetch from the server in one batch. A fetch size of 0 means server default.
      Specified by:
      setFetchSize in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Parameters:
      rows - the fetch size
    • getFetchSize

      public int getFetchSize()
      Gets the fetch size.
      Specified by:
      getFetchSize in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the fetch size
    • setFetchDirection

      public void setFetchDirection(int direction)
      Sets the fetch direction.
      This is only a hint to the JDBC driver.
      Parameters:
      direction - the direction, see ResultSet.setFetchDirection(int)
    • getFetchDirection

      public int getFetchDirection()
      Gets the fetch direction.
      Returns:
      the direction, see ResultSet.getFetchDirection()
    • fetch

      public ResultSetCursor.FetchList<T> fetch()
      Fetches the next PDOs up to the fetch size.
      This method is provided to minimize the number of round trips, especially for remote cursors. The cursor is closed when its end is reached, and the returned list is marked as closed.

      If the fetch size is not set (< 1), all PDOs from the first row on are returned and the cursor is closed. Notice that for local sessions, the fetch size is only a hint to the JDBC driver, which may ignore it and report 0.

      Specified by:
      fetch in interface org.tentackle.misc.ScrollableResource<T extends PersistentDomainObject<T>>
      Returns:
      the list of PDOs, null if the cursor is already closed or no more PDOs found
    • toList

      protected void toList(List<T> list)
      Rewinds the cursor and adds all PDOs to a list.
      Parameters:
      list - the list
    • configureRemoteObject

      protected void configureRemoteObject(T pdo)
      Configures a remotely retrieved PDO.
      Attaches the PDO to the local domain context and session.
      Parameters:
      pdo - the PDO
    • assertSessionIsRemote

      protected void assertSessionIsRemote()
      Asserts that session is remote.
      Throws:
      org.tentackle.session.PersistenceException - if session is local
    • assertSessionIsLocal

      protected void assertSessionIsLocal()
      Asserts that session is local.
      Throws:
      org.tentackle.session.PersistenceException - if session is remote
    • assertNoJoins

      protected void assertNoJoins()
      Asserts that there are no joins in the query.
      Throws:
      org.tentackle.session.PersistenceException - if the cursor has joins