Package de.aristaflow.adept2.model.common.collection

Class CachingRemoteIterator<T>

  • Type Parameters:
    T - The type of the elements that are retrieved from the cached iterator.
    All Implemented Interfaces:
    RemoteIterator<List<T>>, AutoCloseable
    public class CachingRemoteIterator<T>
extends Object
implements RemoteIterator<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.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int current
      The reference to the current element which is to be retrieved next.
      protected 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 Boolean snapshot
      Whether the iterator is a snapshot.
      protected RemoteIterator<List<T>> wrappedIterator
      The wrapped iterator of which all elements will be cached.

    • Field Detail

      • wrappedIterator

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

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