ProgressiveResults (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.persist.ProgressiveResults

All Implemented Interfaces:

Results
```
final class ProgressiveResults
extends java.lang.Object
implements Results
```
An implementation of the Results interface which is backed by Results sets of progressively increasing size.
This results object is best used in queries which start at the beginning of a result set and scroll forward sequentially. While non-linear access to records is possible, it is not the best choice for random access to results. In fact certain operations currently are disallowed, such as testing whether the current position is the last available. Thus, the associated methods throw UnsupportedOperationException in the current implementation.
This implementation is designed to balance the need for an immediate initial result with the need for fast access to a large number of results.
To accomplish this, results are retrieved in brackets. The initial fetch retrieves a bracket containing a single record. Each subsequent bracket fetch retrieves a maximum size which is calculated by raising a base number to a power one higher than that applied to the previous bracket. So, for a base number of 10, the first bracket would have maximum 10^0 (or 1) record. The second bracket (if any) would have maximum 10^1 (or 10) records. The third, 10^2 (or 100), and so on. The default base value is 10.
The exponential progression of bracket sizes ensures that the first result is retrieved as quickly as possible, and subsequent brackets are retrieved with reasonable efficiency. Thus, queries which fall to the smaller end of the spectrum will benefit from the quick retrieval of the first few brackets, while the up front expense of retrieving larger brackets will be amortized more evenly for those queries which process larger data sets.
Note that currently, this progression is (effectively) not capped, which presumes a reasonable JDBC fetch size to prevent a JDBC driver from caching too many records and overrunning memory.
When considered end-to-end, in order of increasing size, all brackets together form the virtualized set of results to a database query. This object keeps track of the virtual index position as it moves through the various brackets. Methods which accept an absolute row index expect this value to represent the absolute offset of the target row in this overall, virtualized result set, such that the bracketing implementation is an implementation detail which is transparent to users of this class.
Only the most recently created result set bracket is retained. Once all records in a bracket have been retrieved and the walk proceeds to the next record, the current bracket is discarded and a new one is retrieved. Users of this class which require the ability to perform non-linear, non first-to-last access must instantiate this class in scrolling mode. In this mode, a cache of visited records is maintained. If a previously accessed record must be re-retrieved, it is pulled from the cache. Accordingly, scrolling instances may have a higher memory requirement.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`ProgressiveResults.Locator` A descriptor object used to locate results brackets and store information used to access them.

Field Summary

Fields
Modifier and Type	Field and Description
`private java.lang.Integer`	`actualMaxExponent` Actual maximum exponent in use
`private static int`	`ANALYZE_EXPONENT` The exponent used to get the average size of records
`private java.lang.Object[]`	`args` Substitution parameters, if any, to be applied to the query
`private static int`	`BASE` Base value used for exponential bracket size progression
`private int`	`bracket` Index of the active delegate
`private java.util.List<java.lang.Object[]>`	`cache` Cached results (scrolling mode only); arrays of DMOs or IDs
`private int`	`checkedCount` Numbers of records used to compute the size
`private boolean`	`closed` Flag indicates results are closed
`private Results`	`delegate` Result set to which record retrieval work is delegated
`private java.lang.String[]`	`entities` Names of entities involved in the query associated with these results
`private static int`	`FALLBACK_MAX_EXPONENT` Maximum exponent to which BASE can be raised in case we didn`t manage to analyze the optimal max exponent based on row size.
`private java.lang.String`	`hql` HQL query string used to select records
`private int`	`lastValidBracket` Index of the most recent valid bracket
`private int`	`lastValidPosition` Most recent valid "real" position in the virtualized result set
`private static CentralLogger`	`LOG` Logger
`private static long`	`MAX_RESULTS_SIZE` Maximum memory allocated for a bracket
`private static int`	`MIN_CHECKED_THRESHOLD` Minimum number of records that needs to be computed in order to set the maximum exponent.
`private Persistence`	`persistence` Object which provides persistence services
`private Persistence.Context`	`persistenceContext` The persistence context.
`private int`	`position` Current "real" position in the overall, virtualized result set
`private boolean`	`projection` Flag indicating whether these results are for a projection query
`private DataRelation`	`relation` The recursive DATA-RELATION the query is to FILL for
`private java.util.ArrayList<VirtualResultsListener>`	`resultsChangeListeners` List of results change listeners
`private long`	`totalCheckedSize` The sum of some records used to compute the size of the brackets

Constructor Summary

Constructors
Constructor and Description
`ProgressiveResults(Persistence persistence, java.lang.String hql, java.lang.Object[] args, boolean scrolling, java.lang.String[] entities, boolean projection, DataRelation relation)` Convenience constructor which sets all variables required for record retrieval.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addResultsChangeListener(VirtualResultsListener listener)` Register results change listener.
`private boolean`	`advanceCache(Results results, int row)` Sequentially retrieve records and store them in the cache until either there are no more records, or until the current position has reached `row`.
`private void`	`analyzeRow(java.lang.Object[] result)` Calculates the size of a row in bytes.
`void`	`cleanup()` Close an open result set, if any, and clear the cache, if any.
`private void`	`closeDelegate()` Close the delegate result set, if any.
`private void`	`fireResultsChanged()` Notify all listeners about changes in obtained results.
`boolean`	`first()` Move to the first result row.
`java.lang.Object[]`	`get()` Get the array of objects at the current result row.
`java.lang.Object`	`get(int column)` Get the object at the current result row, at the specified column.
`java.lang.Long`	`getID(int column)` Get the primary key ID at the current result row, at the specified column.
`private int`	`getMaxExponent()` Calculate the largest exponent in regard to the row size analysis we done to determine the optimal size for the brackets.
`private Results`	`getResults(int bracket)` Access the delegate result set object for the given bracket index.
`private Results`	`getResults(ProgressiveResults.Locator locator)` Access the delegate result set object defined by the given locator.
`int`	`getRowNumber()` Get the row number currently under the cursor.
`boolean`	`isFirst()` Is the cursor on the first row in the result set?
`boolean`	`isLast()` Indicate whether the current record is the last row in the overall, virtualized result set.
`boolean`	`isResultSetCached()` Indicate whether the full result set is cached in this object.
`boolean`	`last()` Move to the last result row.
`private ProgressiveResults.Locator`	`locateBracket(int bracket)` Generate a descriptor object which is used to locate the bracket at the given index among all results brackets.
`private ProgressiveResults.Locator`	`locateRow(int row)` Generate a descriptor object which is used to locate the bracket containing the specified row and the row's location within the bracket.
`private boolean`	`moveTo(int row)` Attempt to move to a specific row offset within the virtualized result set, and report whether a record exists at that row.
`private boolean`	`moveTo(int row, boolean force)` Attempt to move to a specific row offset within the virtualized result set, and report whether a record exists at that row.
`boolean`	`next()` Move cursor to the next result row.
`boolean`	`previous()` Move cursor to the previous result row.
`void`	`reset()` Reset the cursor to its natural starting position, before the first result row.
`boolean`	`scroll(int rows)` Scroll the cursor ahead by the specified number of rows.
`void`	`sessionClosing()` Respond to a session closing event by caching a batch of this results object's records.
`boolean`	`setRowNumber(int row)` Set the row number currently under the cursor.

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

Methods inherited from interface com.goldencode.p2j.persist.Results
addRow, deleteRow, get, getNumberOfLoadedRows, isAutoFetch

- Field Detail
  - LOG
```
private static final CentralLogger LOG
```
    Logger
  - BASE
```
private static final int BASE
```
    Base value used for exponential bracket size progression
    
    See Also:
    
    Constant Field Values
  - FALLBACK_MAX_EXPONENT
```
private static final int FALLBACK_MAX_EXPONENT
```
    Maximum exponent to which BASE can be raised in case we didn`t manage to analyze the optimal max exponent based on row size.
    
    See Also:
    
    Constant Field Values
  - MAX_RESULTS_SIZE
```
private static final long MAX_RESULTS_SIZE
```
    Maximum memory allocated for a bracket
    
    See Also:
    
    Constant Field Values
  - ANALYZE_EXPONENT
```
private static final int ANALYZE_EXPONENT
```
    The exponent used to get the average size of records
    
    See Also:
    
    Constant Field Values
  - MIN_CHECKED_THRESHOLD
```
private static final int MIN_CHECKED_THRESHOLD
```
    Minimum number of records that needs to be computed in order to set the maximum exponent. This should be at most 2 ^ ANALYZE_EXPONENT.
    
    See Also:
    
    Constant Field Values
  - persistence
```
private final Persistence persistence
```
    Object which provides persistence services
  - hql
```
private final java.lang.String hql
```
    HQL query string used to select records
  - args
```
private final java.lang.Object[] args
```
    Substitution parameters, if any, to be applied to the query
  - cache
```
private final java.util.List<java.lang.Object[]> cache
```
    Cached results (scrolling mode only); arrays of DMOs or IDs
  - entities
```
private final java.lang.String[] entities
```
    Names of entities involved in the query associated with these results
  - projection
```
private final boolean projection
```
    Flag indicating whether these results are for a projection query
  - relation
```
private final DataRelation relation
```
    The recursive DATA-RELATION the query is to FILL for
  - delegate
```
private Results delegate
```
    Result set to which record retrieval work is delegated
  - position
```
private int position
```
    Current "real" position in the overall, virtualized result set
  - lastValidPosition
```
private int lastValidPosition
```
    Most recent valid "real" position in the virtualized result set
  - bracket
```
private int bracket
```
    Index of the active delegate
  - lastValidBracket
```
private int lastValidBracket
```
    Index of the most recent valid bracket
  - resultsChangeListeners
```
private java.util.ArrayList<VirtualResultsListener> resultsChangeListeners
```
    List of results change listeners
  - closed
```
private boolean closed
```
    Flag indicates results are closed
  - totalCheckedSize
```
private long totalCheckedSize
```
    The sum of some records used to compute the size of the brackets
  - checkedCount
```
private int checkedCount
```
    Numbers of records used to compute the size
  - actualMaxExponent
```
private java.lang.Integer actualMaxExponent
```
    Actual maximum exponent in use
  - persistenceContext
```
private final Persistence.Context persistenceContext
```
    The persistence context. Needed for notifying when this object is cleaned up so that the session can be closed.
- Constructor Detail
  - ProgressiveResults
```
ProgressiveResults(Persistence persistence,
                   java.lang.String hql,
                   java.lang.Object[] args,
                   boolean scrolling,
                   java.lang.String[] entities,
                   boolean projection,
                   DataRelation relation)
```
    Convenience constructor which sets all variables required for record retrieval.
    
    Parameters:
    
    persistence - Object which provides persistence services.
    
    hql - HQL query string used to select records.
    
    args - Substitution parameters, if any, to be applied to the query.
    
    scrolling - true to allow results to be scrollable. If false, it will only be possible to move forward through results, beginning at the first result; random access will be disallowed.
    
    entities - Names of entities associated with these results.
    
    projection - Flag indicating whether these results are for a projection query.
    
    relation - The recursive DATA-RELATION the query is to FILL for.
- Method Detail
  - first
```
public boolean first()
```
    Move to the first result row. If a previous move has taken us beyond the first row, we must be in scrolling mode to be able to go back.
    
    Specified by:
    
    first in interface Results
    
    Returns:
    
    true if there are any results.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if moving to the first record would scroll backwards, and this object is not set to scrolling mode.
  - last
```
public boolean last()
```
    Move to the last result row. This can be a very expensive operation for a large result set, as we must scroll through each record to reach the end. If we are already at the final record, this method does not change the position, but does report success.
    
    Specified by:
    
    last in interface Results
    
    Returns:
    
    true if there are any results.
  - next
```
public boolean next()
```
    Move cursor to the next result row.
    
    Specified by:
    
    next in interface Results
    
    Returns:
    
    true if there is a result under the cursor after the move.
  - previous
```
public boolean previous()
```
    Move cursor to the previous result row.
    
    Specified by:
    
    previous in interface Results
    
    Returns:
    
    true if there is a result under the cursor after the move.
  - isFirst
```
public boolean isFirst()
```
    Is the cursor on the first row in the result set?
    
    Specified by:
    
    isFirst in interface Results
    
    Returns:
    
    true if the cursor is on the first row.
  - isLast
```
public boolean isLast()
```
    Indicate whether the current record is the last row in the overall, virtualized result set.
    This method is not supported by this implementation.
    
    Specified by:
    
    isLast in interface Results
    
    Returns:
    
    true if the cursor is on the last row, else false.
    
    Throws:
    
    java.lang.UnsupportedOperationException - always.
  - get
```
public java.lang.Object[] get()
```
    Get the array of objects at the current result row.
    
    Specified by:
    
    get in interface Results
    
    Returns:
    
    Object array or null.
  - get
```
public java.lang.Object get(int column)
```
    Get the object at the current result row, at the specified column.
    
    Specified by:
    
    get in interface Results
    
    Parameters:
    
    column - Zero-based index column of the desired object.
    
    Returns:
    
    Object at column or null.
  - isResultSetCached
```
public boolean isResultSetCached()
```
    Indicate whether the full result set is cached in this object.
    
    Specified by:
    
    isResultSetCached in interface Results
    
    Returns:
    
    true if all results are contained this object; false if not or if unknown (such as for a scrolling or cursored result set. Default return value is false.
  - getID
```
public java.lang.Long getID(int column)
```
    Get the primary key ID at the current result row, at the specified column.
    
    Specified by:
    
    getID in interface Results
    
    Parameters:
    
    column - Zero-based index column of the desired ID.
    
    Returns:
    
    ID of the record or null if there is no record at the current position.
  - getRowNumber
```
public int getRowNumber()
```
    Get the row number currently under the cursor.
    
    Specified by:
    
    getRowNumber in interface Results
    
    Returns:
    
    Zero-based index of the current row, or -1 if the cursor is not currently on a result.
  - setRowNumber
```
public boolean setRowNumber(int row)
```
    Set the row number currently under the cursor.
    
    Specified by:
    
    setRowNumber in interface Results
    
    Parameters:
    
    row - Zero-based index of the row to be set as the current row.
    
    Returns:
    
    true if there is a row at the specified row number; else false.
  - scroll
```
public boolean scroll(int rows)
```
    Scroll the cursor ahead by the specified number of rows. If the number is negative, the cursor is moved backward. This may put the cursor off the end (either end) of the query's results.
    
    Specified by:
    
    scroll in interface Results
    
    Parameters:
    
    rows - Number of rows to jump ahead or back.
    
    Returns:
    
    true if there is a row at the new location; else false.
  - reset
```
public void reset()
```
    Reset the cursor to its natural starting position, before the first result row. Only valid for scrolling queries.
    
    Specified by:
    
    reset in interface Results
    
    Throws:
    
    java.lang.UnsupportedOperationException - if invoked on a non-scrolling results instance.
  - sessionClosing
```
public void sessionClosing()
```
    Respond to a session closing event by caching a batch of this results object's records. Only the current record and all remaining records within the current bracket are cached. If no records have yet been retrieved, or if the last record retrieved was the last in its bracket, then no records are cached.
    
    Specified by:
    
    sessionClosing in interface Results
  - cleanup
```
public void cleanup()
```
    Close an open result set, if any, and clear the cache, if any. Reset state variables to their defaults.
    
    Specified by:
    
    cleanup in interface Results
  - addResultsChangeListener
```
public void addResultsChangeListener(VirtualResultsListener listener)
```
    Register results change listener. This listener will be notified about changes in obtained results.
    
    Parameters:
    
    listener - Listener to add.
  - locateRow
```
private ProgressiveResults.Locator locateRow(int row)
```
    Generate a descriptor object which is used to locate the bracket containing the specified row and the row's location within the bracket.
    The object returned does not reflect the state of records or whether the target record actually exists in the result set. Rather, this method calculates where the record should be located based upon the bracketing algorithm in use.
    
    Parameters:
    
    row - 0-based index of the target record in the virtualized result set (i.e., the record's "real" position among the full result set of the query, ignoring bracketing).
    
    Returns:
    
    A descriptor object which allows the target record to be located within the appropriate bracket of results.
  - locateBracket
```
private ProgressiveResults.Locator locateBracket(int bracket)
```
    Generate a descriptor object which is used to locate the bracket at the given index among all results brackets.
    The object returned does not reflect the state of records or whether the target bracket actually exists. Rather, this method calculates the parameters required to request the records which would comprise the bracket, according to the bracketing algorithm in use.
    The Locator object returned will contain the specified bracket, an offset of 0, the size of the bracket, and its row will reflect the zero-based offset (in the virtualized result set) of the row which starts the target bracket.
    
    Parameters:
    
    bracket - 0-based index of the target bracket in the virtualized result set.
    
    Returns:
    
    A descriptor object which allows the target bracket to be created.
  - moveTo
```
private boolean moveTo(int row)
```
    Attempt to move to a specific row offset within the virtualized result set, and report whether a record exists at that row.
    This method updates the internal state variables which track the current virtualized row index and bracket index. Both are set to their default values if the target row does not exist.
    
    Parameters:
    
    row - 0-based index of the target record in the virtualized result set (i.e., the record's "real" position among the full result set of the query, ignoring bracketing).
    
    Returns:
    
    true if there is a row at the specified row number; else false.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if a backwards move is requested for a non-scrolling results object.
  - moveTo
```
private boolean moveTo(int row,
                       boolean force)
```
    Attempt to move to a specific row offset within the virtualized result set, and report whether a record exists at that row.
    This method updates the internal state variables which track the current virtualized row index and bracket index. Both are set to their default values if the target row does not exist.
    
    Parameters:
    
    row - 0-based index of the target record in the virtualized result set (i.e., the record's "real" position among the full result set of the query, ignoring bracketing).
    
    force - Force move even if the target row matches the current row. Allows to initialize delegate in some cases.
    
    Returns:
    
    true if there is a row at the specified row number; else false.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if a backwards move is requested for a non-scrolling results object.
  - advanceCache
```
private boolean advanceCache(Results results,
                             int row)
```
    Sequentially retrieve records and store them in the cache until either there are no more records, or until the current position has reached row.
    
    Parameters:
    
    results - Delegate results object from which to retrieve records.
    
    row - Target row index. Retrieval halts when the current record position reaches this row.
    
    Returns:
    
    true if the last attempt to retrieve a record was successful; false if we reached the end of the delegate result set bracket before reaching our target row.
    
    Throws:
    
    java.lang.IllegalStateException - if the current position is not at the last record in the cache.
  - getResults
```
private Results getResults(int bracket)
                    throws PersistenceException
```
    Access the delegate result set object for the given bracket index. If the bracket does not yet exist, it is created if possible.
    
    Parameters:
    
    bracket - 0-based index of the target bracket.
    
    Returns:
    
    Delegate Results for the given bracket, or null if no such bracket exists.
    
    Throws:
    
    PersistenceException
  - getResults
```
private Results getResults(ProgressiveResults.Locator locator)
                    throws PersistenceException
```
    Access the delegate result set object defined by the given locator. If the bracket does not yet exist, create it if possible.
    
    Parameters:
    
    locator - Descriptor of the target bracket.
    
    Returns:
    
    Delegate Results for the given bracket, or null if no such bracket exists.
    
    Throws:
    
    PersistenceException - if there is an error retrieving a result set.
  - closeDelegate
```
private void closeDelegate()
```
    Close the delegate result set, if any.
  - fireResultsChanged
```
private void fireResultsChanged()
```
    Notify all listeners about changes in obtained results.
  - getMaxExponent
```
private int getMaxExponent()
```
    Calculate the largest exponent in regard to the row size analysis we done to determine the optimal size for the brackets. This is a heuristic, so it won't guarantee that the brackets won't exceed MAX_RESULTS_SIZE. However, this is an effort to avoid retrieving a lot of records at once to trigger OOM.
    
    Returns:
    
    The maximum exponent that should be used in regard to the row size analysis done.
  - analyzeRow
```
private void analyzeRow(java.lang.Object[] result)
```
    Calculates the size of a row in bytes.
    
    Parameters:
    
    result - The row that should be analyzed.

Class ProgressiveResults

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.goldencode.p2j.persist.Results

Field Detail

LOG

BASE

FALLBACK_MAX_EXPONENT

MAX_RESULTS_SIZE

ANALYZE_EXPONENT

MIN_CHECKED_THRESHOLD

persistence

hql

args

cache

entities

projection

relation

delegate

position

lastValidPosition

bracket

lastValidBracket

resultsChangeListeners

closed

totalCheckedSize

checkedCount

actualMaxExponent

persistenceContext

Constructor Detail

ProgressiveResults

Method Detail

first

last

next

previous

isFirst

isLast

get

get

isResultSetCached

getID

getRowNumber

setRowNumber

scroll

reset

sessionClosing

cleanup

addResultsChangeListener

locateRow

locateBracket

moveTo

moveTo

advanceCache

getResults

getResults

closeDelegate

fireResultsChanged

getMaxExponent

analyzeRow