de.aristaflow.adept2.core.transactionmanager

Class ResultSetRemoteIterator<T>

java.lang.Object

de.aristaflow.adept2.core.transactionmanager.ResultSetRemoteIterator<T>

Type Parameters:

T - The type of the elements that are retrieved from the encapsulated result set.

All Implemented Interfaces:

RemoteIterator<java.util.List<T>>

public abstract class ResultSetRemoteIterator<T>
extends java.lang.Object
implements RemoteIterator<java.util.List<T>>

This remote iterator encapsulates a result set. It just access the result set when iterating but does not cache anything internally. Therefore no real consistency checking can take place. Since the elements of a result set are specific, retrieving one element from the result set has to be provided by subclasses.

The cursor of the underlying result set is positioned at the first element to be retrieved next in forward-only mode. Therefore in forward direction (the only possible direction) retrieve the element before advancing. In scrollable mode (non forward-only) the result set is positioned at the last element which has been retrieved (except the first element).

Author:

Ulrich Kreher

Constructor Summary

Constructors

Constructor and Description
ResultSetRemoteIterator(ManagedResultSet resultSet, long aliveTime) Creates a new remote iterator for the designated result set to be alive for the designated time.
ResultSetRemoteIterator(ManagedResultSet resultSet, long aliveTime, java.lang.String[] recTables) Creates a new remote iterator for the designated result set to be alive for the designated time dropping the designated recursion tables when dropping this iterator.

Method Summary

Modifier and Type	Method and Description
void	drop() Explicitly drops this iterator which allows to release occupied memory and resources.
java.util.List<T>	getAll() Gets all elements of this iterator at once.
java.util.List<T>	getNext(int count) Gets the next specified amount of elements of this iterator.
java.util.List<T>	getNext(int count, int start) Gets the next specified amount of elements of this iterator starting at the designated index (0-based).
protected abstract T	getObject(java.sql.ResultSet resSet) Gets the current object of the designated result set.
java.util.List<T>	getPrevious(int count) Gets the previous specified amount of elements of this iterator.
long	getRemainingAliveTime() Gets the time in milliseconds this iterator will still be valid and does allow access to the underlying data.
boolean	isForwardOnly() Gets whether this iterator only allows iterating in forward direction, that is calls to RemoteIterator.getNext(int) but not to RemoteIterator.getNext(int, int) and RemoteIterator.getPrevious(int).
boolean	isSnapshot() Gets whether this iterator is a snapshot and therefore its contents is not subject of change while iterating.
long	keepAlive(long aliveTime) Keeps this iterator alive for the designated time span (in milliseconds).

Methods inherited from class java.lang.Object

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

Constructor Detail

ResultSetRemoteIterator

public ResultSetRemoteIterator(ManagedResultSet resultSet,
                               long aliveTime)
                        throws DataSourceException

Creates a new remote iterator for the designated result set to be alive for the designated time.

Parameters:

resultSet - The result set for which to create a remote iterator. This must not be null. The result set has to be managed by a TxManager.

aliveTime - The time in milliseconds the created remote iterator is alive.

Throws:

DataSourceException - If positioning the result set or retrieving the scroll behaviour of the result set fails, a DataSourceException will be thrown.

ResultSetRemoteIterator

public ResultSetRemoteIterator(ManagedResultSet resultSet,
                               long aliveTime,
                               java.lang.String[] recTables)
                        throws DataSourceException

Creates a new remote iterator for the designated result set to be alive for the designated time dropping the designated recursion tables when dropping this iterator.

Parameters:

resultSet - The result set for which to create a remote iterator. This must not be null. The result set has to be managed by a TxManager.

aliveTime - The time in milliseconds the created remote iterator is alive.

recTables - The recursion tables to drop together with this iterator. null if there are no such tables.

Throws:

DataSourceException - If positioning the result set or retrieving the scroll behaviour of the result set fails, a DataSourceException will be thrown.

Method Detail

getNext

public java.util.List<T> getNext(int count)
                          throws DataSourceException,
                                 DataConsistencyException

Description copied from interface: RemoteIterator

Gets the next specified amount of elements of this iterator. The returned data will be consistent within the returned list (but not necessarily with respect to previous or later retrievals) due to the usage of synchronisation.

Specified by:

getNext in interface RemoteIterator<java.util.List<T>>

Parameters:

count - The amount of elements to retrieve in forward direction. This has to be > 0.

Returns:

The next n elements of this iterator, where n is the specified count. In case of an insufficient amount of next elements remaining only the available elements will be returned. If there are no more next elements, null will be returned.

Throws:

DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

DataConsistencyException - If there are problems retrieving any of the next elements via the identifying attribute of the elements (for instance the primary key of a specific element identifying the next position) is not available any more, a DataConsistencyException will be thrown.

getNext

public java.util.List<T> getNext(int count,
                                 int start)
                          throws DataSourceException,
                                 DataConsistencyException

Description copied from interface: RemoteIterator

Gets the next specified amount of elements of this iterator starting at the designated index (0-based). The returned data will be consistent within the returned list (but not necessarily with respect to previous or later retrievals) due to the usage of synchronisation.
Afterwards the cursor to the current element will be set to the index start + count, that is, getNext(n) will be the same as calling getNext(n, start + count).

Specified by:

getNext in interface RemoteIterator<java.util.List<T>>

Parameters:

count - The amount of elements to retrieve in forward direction. This has to be > 0.

start - The index of the element from which to retrieve the next count elements. 0 is the index of the first element. This has to be >= 0 and it must not be bigger than the amounts of elements in this iterator.

Returns:

The next n elements of this iterator, where n is the specified count. In case of an insufficient amount of next elements remaining only the available elements will be returned. If there are no more next elements, null will be returned.

Throws:

DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

DataConsistencyException - If there are problems retrieving any of the next elements via the identifying attribute of the elements (for instance the primary key of a specific element identifying the next position) is not available any more, a DataConsistencyException will be thrown.

getPrevious

public java.util.List<T> getPrevious(int count)
                              throws DataSourceException,
                                     DataConsistencyException

Description copied from interface: RemoteIterator

Gets the previous specified amount of elements of this iterator. The returned data will be consistent within the returned list (but not necessarily with respect to previous or later retrievals) due to the usage of synchronisation.

Specified by:

getPrevious in interface RemoteIterator<java.util.List<T>>

Parameters:

count - The amount of elements to retrieve in backward direction. This has to be > 0.

Returns:

The previous n elements of this iterator, where n is the specified count. The order corresponds to the one in the underlying data structure, that is previous elements in the returned list are also previous elements in the data structure. In case of an insufficient amount of previous elements remaining only the available elements will be returned. If there are no more previous elements, null will be returned.

Throws:

DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

DataConsistencyException - If there are problems retrieving any of the previous next elements via the identifying attribute of the elements (for instance the primary key of a specific element identifying the next position) is not available any more or if this iterator is forward only, a DataConsistencyException will be thrown.

getAll

public java.util.List<T> getAll()
                         throws DataSourceException,
                                DataConsistencyException

Description copied from interface: RemoteIterator

Gets all elements of this iterator at once. The returned data will be consistent (does not contain elements of different versions) due to the usage of synchronisation. Note that calling this method may take a lot of time.
Calling this method will reset the iterator before the first element if this iterator is not forward only. If this iterator is forward only and does not cache retrieved elements internally, this method will not work but throw a DataSourceException since the already returned elements may not be retrieved any more.

Specified by:

getAll in interface RemoteIterator<java.util.List<T>>

Returns:

All elements of this iterator at once.

Throws:

DataSourceException - If there are problems accessing the underlying data source or this iterator is forward only and currently not positioned before the first element, a DataSourceException will be thrown.

DataConsistencyException - If there are problems retrieving any of the elements via the identifying attribute of the elements (for instance the primary key of a specific element identifying the next position) is not available any more, a DataConsistencyException will be thrown.

isSnapshot

public boolean isSnapshot()

Description copied from interface: RemoteIterator

Gets whether this iterator is a snapshot and therefore its contents is not subject of change while iterating. However, the contents may be outdated while iterating.

Specified by:

isSnapshot in interface RemoteIterator<java.util.List<T>>

Returns:

Whether this iterator is a snapshot providing stable but maybe outdated data.

isForwardOnly

public boolean isForwardOnly()

Description copied from interface: RemoteIterator

Gets whether this iterator only allows iterating in forward direction, that is calls to RemoteIterator.getNext(int) but not to RemoteIterator.getNext(int, int) and RemoteIterator.getPrevious(int). This can be restricted by the underlying data structure, for instance a ResultSet.

Specified by:

isForwardOnly in interface RemoteIterator<java.util.List<T>>

Returns:

Whether this iterator only allows iterating in forward direction.

getRemainingAliveTime

public long getRemainingAliveTime()

Description copied from interface: RemoteIterator

Gets the time in milliseconds this iterator will still be valid and does allow access to the underlying data. Afterwards the iterator will be dropped automatically to save memory and resources.
A negative value indicates a dropped iterator. Such an iterator cannot be kept alive. Note that this alive time does not need to correspond to the original alive time requested

Specified by:

getRemainingAliveTime in interface RemoteIterator<java.util.List<T>>

Returns:

The time this iterator remains valid and can be used. Afterwards the iterator will be dropped. Long.MIN_VALUE for an already dropped remote iterator.

keepAlive

public long keepAlive(long aliveTime)
               throws DataSourceException

Keeps this iterator alive for the designated time span (in milliseconds). This allows to continue using this iterator. However, note that extending the usage time significantly impacts resource occupation.
Note that extending the time need not be successful. The underlying iterator implementation may not be able to extend the alive time of all used resource, for instance pooled database connections.

A 0 or a negative value is equal to dropping this iterator. This implementation only allows extensions of alive times by 5 minutes.

Specified by:

keepAlive in interface RemoteIterator<java.util.List<T>>

Parameters:

aliveTime - The time in milliseconds to keep this iterator alive that is not to drop it automatically.

Returns:

The relative time this iterator will be kept alive longer. 0 indicates immediate dropping. A negative value represents the failure of extending the alive time, check RemoteIterator.getRemainingAliveTime() in this case whether extending the keep alive time has been successful or not.

Throws:

DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

drop

public void drop()
          throws DataSourceException

Description copied from interface: RemoteIterator

Explicitly drops this iterator which allows to release occupied memory and resources. Dropping will be done implicitly after the alive time has elapsed.
This method may be called several times. Implementors have to take care of this.

Specified by:

drop in interface RemoteIterator<java.util.List<T>>

Throws:

DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

getObject

protected abstract T getObject(java.sql.ResultSet resSet)
                        throws java.sql.SQLException,
                               DataSourceException

Gets the current object of the designated result set. The result set must not be manipulated and the cursor must not be moved.

Parameters:

resSet - The result set to retrieve the current position as Java object.

Returns:

The Java object representing the contents of the result set at the current position.

Throws:

java.sql.SQLException - If there are problems retrieving the current element from the result set, a SQLException will be thrown.

DataSourceException - If there are other problems when accessing the result set or retrieving additional information, a DataSourceException will be thrown.