CachingRemoteIterator (AristaFlow Business Process Platform API)

java.lang.Object
- de.aristaflow.adept2.model.common.collection.CachingRemoteIterator<T>

Type Parameters:

T - The type of the elements that are retrieved from the cached iterator.

All Implemented Interfaces:

RemoteIterator<java.util.List<T>>
```
public class CachingRemoteIterator<T>
extends java.lang.Object
implements RemoteIterator<java.util.List<T>>
```
This iterator implements a cache for the underlying iterator, that is, when iterating via getNext(int), all retrieved elements will be cached. Previous elements will always be retrieved from the cache. Note that a positioned next will add enough elements to the cache to fulfil the request.

Author:

Ulrich Kreher

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`current` The reference to the current element which is to be retrieved next.
`protected java.util.List<T>`	`elements` The elements that have been retrieved from the underlying remote iterator so far.
`protected int`	`last` The index of last element in case it has been reached in the result set, -1 otherwise.
`protected int`	`lastCached` The index of the last element that is in the cache.
`protected java.lang.Boolean`	`snapshot` Whether the iterator is a snapshot.
`protected RemoteIterator<java.util.List<T>>`	`wrappedIterator` The wrapped iterator of which all elements will be cached.

Constructor Summary

Constructors
Constructor and Description

CachingRemoteIterator(RemoteIterator<java.util.List<T>> wrappedIterator)
Creates a new caching remote iterator for the designated iterator.

Constructors
Constructor and Description
`CachingRemoteIterator(RemoteIterator<java.util.List<T>> wrappedIterator)` Creates a new caching remote iterator for the designated iterator.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`drop()` Explicitly drops this iterator which allows to release occupied memory and resources.
`protected void`	`dropWrapped()` Drops the wrapped iterator either since it is explicitly dropped or the cache contains all items and the wrapped iterator is no longer required.
`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).
`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

- Field Detail
  - wrappedIterator
```
protected RemoteIterator<java.util.List<T>> wrappedIterator
```
    The wrapped iterator of which all elements will be cached. Note that the current cursor need not correspond to the current cursor of the underlying iterator. This will be null when the wrapped iterator has been dropped.
  - elements
```
protected java.util.List<T> elements
```
    The elements that have been retrieved from the underlying remote iterator so far.
  - lastCached
```
protected int lastCached
```
    The index of the last element that is in the cache. This corresponds to the current index of the wrapped iterator.
  - last
```
protected int last
```
    The index of last element in case it has been reached in the result set, -1 otherwise.
  - current
```
protected int current
```
    The reference to the current element which is to be retrieved next.
  - snapshot
```
protected java.lang.Boolean snapshot
```
    Whether the iterator is a snapshot. This will be null until first retrieved from the wrapped iterator.
- Constructor Detail
  - CachingRemoteIterator
```
public CachingRemoteIterator(RemoteIterator<java.util.List<T>> wrappedIterator)
```
    Creates a new caching remote iterator for the designated iterator.
    
    Parameters:
    
    wrappedIterator - The iterator of which the elements should be cached as soon as they are iterated (with getNext(int)).
- 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()
                   throws DataSourceException
```
    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.
    
    Throws:
    
    DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.
  - isForwardOnly
```
public boolean isForwardOnly()
                      throws DataSourceException
```
    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.
    
    Throws:
    
    DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.
  - 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
```
    Description copied from interface: RemoteIterator
    
    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.
    
    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.
  - dropWrapped
```
protected void dropWrapped()
                    throws DataSourceException
```
    Drops the wrapped iterator either since it is explicitly dropped or the cache contains all items and the wrapped iterator is no longer required.
    
    Throws:
    
    DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.

Class CachingRemoteIterator<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

wrappedIterator

elements

lastCached

last

current

snapshot

Constructor Detail

CachingRemoteIterator

Method Detail

getNext

getNext

getPrevious

getAll

isSnapshot

isForwardOnly

getRemainingAliveTime

keepAlive

drop

dropWrapped