de.aristaflow.adept2.model.common.collection

Interface RemoteIterator<T extends java.util.List<?>>

Type Parameters:

T - A collection type that is provided by this iterator. All of these collections have to be sorted, otherwise the iterator does not have a well-defined order for iterating.

All Known Implementing Classes:

CachingRemoteIterator, EmptyRemoteIterator, MemoryBasedCopyingRemoteIterator, ResultSetRemoteIterator

@ServerSideProxyAllow
public interface RemoteIterator<T extends java.util.List<?>>

A RemoteIterator allows to retrieve parts of collections instead of whole collections. This shortens the retrieval time since such collections need not be fully created before the method corresponding requesting method can return. Additionally, less data needs to be transfered initially to a client. However, partial retrieval may lead to inconsistencies in case the underlying data of the iterator is changed while iterating. For instance, some elements of the original result may be removed while iterating, other elements may be added at an arbitrary position in the collection and therefore missed when iterating.
Since iterators occupy resources while they are being used (for instance keeping a database connection open or holding data directly in memory), they have an alive time. As soon as the time passed, the iterator will be dropped which releases all occupied resources. Afterwards the iterator will not be usable any more; data retrieval methods will throw an IllegalStateException on server side itself) and all methods will throw a ServiceConnectionException on client side. If this alive time is insufficient, users may try to extend the remaining alive time. However, this does not need to succeed since the underlying resources of the iterator may not be able to extend their alive time, for instance pooled database connections.
To improve resource handling, users may drop an iterator any time and should do so as early as possible.

Implementations of remote iterators may perform internal optimisations which are most adequate for the corresponding purpose. For instance, iterators may be lazy and provide only the necessary data (which requires an open connection to the corresponding data source), they may be eager and provide all data at once (although this is not advised since this contradicts to the original purpose of an iterator of not providing all data at once). Implementations may also be in-between that is prefetching some results but not all. Additionally, already retrieved results may be cached but this is also not required. However, caching is an easy way to detect inconsistencies in partial data already returned with partial data retrieved later.
To prevent inconsistencies, a remote iterator may be based on a snapshot of the data. Such an iterator returns exactly the temporal state of the data when requesting the iterator. This can be done by either retrieving the complete data eagerly or by support of the underlying data source, for instance temporal databases or the restrictive usage of database transactions which prevents concurrent write accesses to the underlying data.

Usually the configuration parameters for an iterator (alive time, whether to use a snapshot,...) are provided as parameters to the method returning the iterator. However, the iterator itself may have other values set. This should be checked by the user. Especially the alive time can differ due to restrictions on the resources used by the iterator implementation for instance using time-restricted pooled database connections.

Method Summary

Modifier and Type	Method and Description
void	drop() Explicitly drops this iterator which allows to release occupied memory and resources.
T	getAll() Gets all elements of this iterator at once.
T	getNext(int count) Gets the next specified amount of elements of this iterator.
T	getNext(int count, int start) Gets the next specified amount of elements of this iterator starting at the designated index (0-based).
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 getNext(int) but not to getNext(int, int) and 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).

Method Detail

getNext

T getNext(int count)
   throws DataSourceException,
          DataConsistencyException

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.

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.

java.lang.IllegalArgumentException - If count is non-positive (<= 0), an IllegalArgumentException will be thrown.

java.lang.IllegalStateException - If this iterator has been dropped (explicitly or implicitly), an IllegalStateException will be thrown on server side.

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

getNext

T getNext(int count,
          int start)
   throws DataSourceException,
          DataConsistencyException

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

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.

java.lang.IllegalArgumentException - If count is non-positive (<= 0) or start is negative (< 0) or it refers to an index that is bigger than the amount of elements of this iterator, an IllegalArgumentException will be thrown. A forward only iterator will be reset to the last element, a non-forward only iterator will be reset to the first element.

java.lang.IllegalStateException - If this iterator has been dropped (explicitly or implicitly), an IllegalStateException will be thrown on server side.

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

java.lang.UnsupportedOperationException - If this iterator is forward only, an UnsupportedOperationException will be thrown.

getPrevious

T getPrevious(int count)
       throws DataSourceException,
              DataConsistencyException

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.

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.

java.lang.IllegalArgumentException - If this iterator does not have any previous elements or count is non-positive (<= 0), an IllegalArgumentException will be thrown.

java.lang.IllegalStateException - If this iterator has been dropped (explicitly or implicitly), an IllegalStateException will be thrown on server side.

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

java.lang.UnsupportedOperationException - If this iterator is forward only, an UnsupportedOperationException will be thrown.

getAll

T getAll()
  throws DataSourceException,
         DataConsistencyException

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.

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.

java.lang.IllegalStateException - If this iterator has been dropped (explicitly or implicitly), an IllegalStateException will be thrown on server side.

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

isSnapshot

boolean isSnapshot()
            throws DataSourceException

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.

Returns:

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

Throws:

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

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

isForwardOnly

boolean isForwardOnly()
               throws DataSourceException

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

Returns:

Whether this iterator only allows iterating in forward direction.

Throws:

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

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

getRemainingAliveTime

long getRemainingAliveTime()

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

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.

Throws:

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

keepAlive

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.

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

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

drop

@ServerSideProxyRemove
void drop()
                          throws DataSourceException

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.

Throws:

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

ServiceConnectionException - If this iterator has been dropped (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.