com.goldencode.p2j.persist.orm

Class ScrollableResults<T>

java.lang.Object

com.goldencode.p2j.persist.orm.ScrollableResults<T>

Type Parameters:

T - The expected type of the row elements. Note: 1. in the case of single-column result this is clearly OK, but when a table with a non homogeneous set of columns is queried, this type is not appropriate. 2. The ScrollingResults is a very similar class that adds very little code compared to this object to which it delegates all Result API. TODO: decide whether we merge these classes

public class ScrollableResults<T>
extends java.lang.Object

This object facilitates the random access to a ResultSet by providing scrolling primitives (first, next, prev, last) and accessor to currently selected row.

The object is always aware whether the pointer of the delegate ResultSet is on a valid row by intercepting the result of all invoked methods which moves the cursor in the delegate. This also have the advantage of a bit of performance boost as it is able to detect and short-cut the call to the delegate in cases the result is false / null.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static interface	ScrollableResults.SandboxRun<T> Functional interface for passing in a piece of code that potentially throws a SQLException.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	available Tracks the 'available' flag of the inner ResultSet.
private static CentralLogger	LOG Logger
private ScrollableResults.SandboxRun<java.lang.Void>	onClose On close hook
private java.util.ArrayList<RowStructure>	rowStructure The expected structure of a query, as generated by the FqlToSqlConverter.
private java.sql.ResultSet	rs The delegate ResultSet.
private Session	session The Session to be used.
private java.sql.Statement	stmt The statement to close.

Constructor Summary

Constructors

Constructor and Description
ScrollableResults(java.sql.Statement stmt, java.sql.ResultSet rs, java.util.ArrayList<RowStructure> rowStructure, Session session) Constructs a ScrollableResults object for further use.

Method Summary

Modifier and Type	Method and Description
boolean	beforeFirst() Test whether the cursor is located before the first row in this result set.
void	close() Closes the result set by releasing all resources.
private static <T> T	execute(ScrollableResults.SandboxRun<T> code, T defVal) Internal worker method.
boolean	first() Go to result row.
java.lang.Object[]	get() Obtain the full set of values on current row.
java.lang.Object[]	get(boolean forceOnlyId) Obtain the full set of values on current row.
java.lang.Object[]	get(DmoMeta dmoInfo, java.lang.String idCol, java.lang.String[] cols) Obtain the selection of values on current row.
T	get(int i, java.lang.Class<T> tClass) Obtain the value of a i-th column of the current row.
private java.lang.Object[]	getImpl(boolean forceOnlyId) Obtain the full set of values on current row.
int	getRowNumber() Obtain the index of current row in the result set.
boolean	isFirst() Test whether the current row is the first in this result set.
boolean	isLast() Test whether the current row is the last in this result set.
boolean	last() Advance to the last result row.
boolean	next() Advance to the next result row.
ScrollableResults<T>	onClose(ScrollableResults.SandboxRun<java.lang.Void> hook) Set on close hook
boolean	previous() Go back to previous result row.
boolean	scroll(int rows) Scroll an given amount of rows, backward of forward.
boolean	setRowNumber(int row) Configures the index of current row in the result set.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

private static final CentralLogger LOG

Logger

stmt

private final java.sql.Statement stmt

The statement to close. This assumes the rs is the single result set for this statement.

rs

private final java.sql.ResultSet rs

The delegate ResultSet.

rowStructure

private final java.util.ArrayList<RowStructure> rowStructure

The expected structure of a query, as generated by the FqlToSqlConverter.

session

private final Session session

The Session to be used.

onClose

private ScrollableResults.SandboxRun<java.lang.Void> onClose

On close hook

available

private boolean available

Tracks the 'available' flag of the inner ResultSet.

Constructor Detail

ScrollableResults

public ScrollableResults(java.sql.Statement stmt,
                         java.sql.ResultSet rs,
                         java.util.ArrayList<RowStructure> rowStructure,
                         Session session)

Constructs a ScrollableResults object for further use.

Parameters:

stmt - The JDBC statement to close.

rs - The ResultSet to be used for extracting data.

rowStructure - The expected structure of a query, as generated by the FqlToSqlConverter.

session - The Session to be used.

Method Detail

onClose

public ScrollableResults<T> onClose(ScrollableResults.SandboxRun<java.lang.Void> hook)

Set on close hook

Parameters:

hook - new hook;

Returns:

this

first

public boolean first()

Go to result row.

Returns:

true if there is a result under the cursor and false otherwise (there are no more records or some error occurred).

last

public boolean last()

Advance to the last result row.

Returns:

true if there is a result under the cursor and false otherwise (there are no more records or some error occurred).

next

public boolean next()

Advance to the next result row.

Returns:

true if there is a result under the cursor and false otherwise (there are no more records or some error occurred).

previous

public boolean previous()

Go back to previous result row.

Returns:

true if there is a result under the cursor and false otherwise (there are no more records or some error occurred).

isFirst

public boolean isFirst()

Test whether the current row is the first in this result set.

Returns:

true if this is the first row of results.

isLast

public boolean isLast()

Test whether the current row is the last in this result set.

Returns:

true if this is the last row of results.

get

public java.lang.Object[] get()

Obtain the full set of values on current row. An array of primary keys or full Record will be returned.

Returns:

An array of Objects if the cursor is on a valid position. Otherwise null is returned. The type of returned elements may be both Long when an array of PKs (recids) is queried or an array of full Records. The caller is responsible for handling both cases (including hydration, if needed).

get

public java.lang.Object[] get(boolean forceOnlyId)

Obtain the full set of values on current row. An array of primary keys or full Records will be returned.

Parameters:

forceOnlyId - Indicates whether it's only the primary keys that must be returned, or if the records must be hydrated and all data found is returned.

Returns:

When forceOnlyId is false, an array of Objects if the cursor is on a valid position. If the cursor is not on a valid position then null is returned. The type of returned elements may be both Long when an array of PKs (recids) is queried or an array of full Records. The caller is responsible for handling both cases (including hydration, if needed). When forceOnlyId is true, an array of Long only with the PKs.

get

public java.lang.Object[] get(DmoMeta dmoInfo,
                              java.lang.String idCol,
                              java.lang.String[] cols)

Obtain the selection of values on current row.

Parameters:

dmoInfo - The target data description

idCol - The name of the column which holds entity's id

cols - Array of names of other columns to retrieve.

Returns:

An array of Object s if the cursor is on a valid position. Otherwise null is returned.

get

public T get(int i,
             java.lang.Class<T> tClass)

Obtain the value of a i-th column of the current row.

Parameters:

i - column number

tClass - column

Returns:

The value on i-th column of the current row if i and current row are valid and null otherwise.

getRowNumber

public int getRowNumber()

Obtain the index of current row in the result set. 0-based counter is used (ie, the first row is number 0).

Returns:

the row index, staring at 0, or -1 if there is no current row.

setRowNumber

public boolean setRowNumber(int row)

Configures the index of current row in the result set. 0-based counter is used (ie, the first row is number 0).

Parameters:

row - The 0-based index of the row to be selected under cursor. Use negative values to position the cursor form the end.

Returns:

true if there is a row selected.

beforeFirst

public boolean beforeFirst()

Test whether the cursor is located before the first row in this result set.

Returns:

true if the cursor is located before the first row in this result set.

scroll

public boolean scroll(int rows)

Scroll an given amount of rows, backward of forward.

Parameters:

rows - The number of rows to scroll. If a positive value is provided the scroll is forward and if a negative value is provided the scroll is performed backward with number of rows equals with the absolute value of rows.

Returns:

true if there is a valid row at the new location.

close

public void close()
           throws PersistenceException

Closes the result set by releasing all resources.

Throws:

PersistenceException - if some error occurs in the process.

getImpl

private java.lang.Object[] getImpl(boolean forceOnlyId)
                            throws java.sql.SQLException

Obtain the full set of values on current row. An array of primary keys or full Records will be returned.

Parameters:

forceOnlyId - Indicates whether it's only the primary keys that must be returned, or if the records must be hydrated and all data found is returned.

Returns:

When forceOnlyId is false, an array of Objects if the cursor is on a valid position. If the cursor is not on a valid position then null is returned. The type of returned elements may be both Long when an array of PKs (recids) is queried or an array of full Records. The caller is responsible for handling both cases (including hydration, if needed). When forceOnlyId is true, an array of Long only with the PKs.

Throws:

java.sql.SQLException

execute

private static <T> T execute(ScrollableResults.SandboxRun<T> code,
                             T defVal)

Internal worker method. Execute a piece of code that potentially throws a SQLException and returns the result. If the exception is throws, a default value is used for return.

Type Parameters:

T - The class type of the returned object.

Parameters:

code - The code to be executed.

defVal - The default value to be returned when a SQLException is caught.

Returns:

The result of the evaluation od code or the defVal if evaluation failed.