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

Class AbstractRemoteIterator<S,T>

java.lang.Object
de.aristaflow.adept2.model.common.collection.AbstractRemoteIterator<S,T>
Type Parameters:
S - The source type of the provided elements, which is subject of transformation before returning them.
T - The type of the elements that is provided when iterating.
All Implemented Interfaces:
RemoteIterator<List<T>>, de.aristaflow.adept2.model.communication.ServerSideProxy, Closeable, AutoCloseable
Direct Known Subclasses:
AbstractTimeTrackingRemoteIterator, TransformingRemoteIterator
public abstract class AbstractRemoteIterator<S,T> extends Object implements RemoteIterator<List<T>>
This class provides the basic means for a window mechanism for lists of elements, that is, the basic means for a RemoteIterator. It provides refusal of accessing a closed remote iterator, basic active thread tracking, transformation and tracking of returned elements and tracking of AutoCloseable elements. Such elements can either be closed on traversal or when closing the remote iterator. closeOnTraversal() will AutoCloseable.close() all elements of the previous traversal (call to getNext(int), getNext(int, int) or getPrevious(int)). This reduces the amount of memory required to keep this elements for closing. But it prevents re-accessing these elements. If the elements are created for every traversal, this is no problem, if they are provided via memory, closing needs to be deferred.
While AutoCloseable.close() on close() is the default, subclasses may choose to close on traversal (useful for RemoteIterator.isForwardOnly() and iterators creating new elements when traversing) or even to disable closing at all. The latter is required for remote iterators that cache already accessed elements and re-provide them when traversing back.

AutoCloseable elements will be wrapped so that the using classes cannot close the retrieved elements outside of this remote iterator.

See Also:
  • CloseIgnoringWrapper

  • Nested Class Summary

    Nested classes/interfaces inherited from interface de.aristaflow.adept2.model.communication.ServerSideProxy

    de.aristaflow.adept2.model.communication.ServerSideProxy.LegacySspCloser, de.aristaflow.adept2.model.communication.ServerSideProxy.ServerSideProxyRemover

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final Cleanup<IOException>
    cleanup
    The clean-up for closing the closeables as post-mortem task for this instance or when closing.
    protected final Collection<AutoCloseable>
    closeables
    The elements that are AutoCloseable that should be closed at the next traversal or when closing.
    protected final Logger
    logger
    The logger for logging messages instead of throwing exceptions.
    protected final Function<S,T>
    transformator
    The transformator function applied to each individual object before retrieval.

    Fields inherited from interface de.aristaflow.adept2.model.communication.ServerSideProxy

    DEFAULT_ALIVE_TIME

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractRemoteIterator(Function<S,T> transformator, Logger logger)
    Creates a new remote iterator with the designated transformator function applied to each element before returning it and using the designated logger for problems when closing (this remote iterator or the appropriate elements).

  • Method Summary

    Modifier and Type
    Method
    Description
    protected List<T>
    aboutToReturn(List<S> elems)
    Tracks the AutoCloseables of the designated elements before returning them, handles their closing (when closeOnTraversal) and applies the transformation.
    void
    close()
    Explicitly closes this iterator which allows to release occupied memory and resources.
    boolean
    closeOnTraversal()
    Gets whether this remote iterator closes elements of AutoCloseable type when traversing to the next elements.
    protected void
    enter()
    Allows to track entering a method reentrant.
    protected Long
    exit()
    Tracks exiting a method reentrant.
    final List<T>
    getAll()
    Gets all elements of this iterator at once.
    protected abstract List<S>
    getAllImpl()
    Implements getAll() without the need to consider result transformation, closeable and alive time tracking.
    final List<T>
    getNext(int count)
    Gets the next specified amount of elements of this iterator.
    final 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 List<S>
    getNextImpl(int count)
    Implements getNext(int) without the need to consider result transformation, closeable and alive time tracking.
    protected abstract List<S>
    getNextImpl(int count, int start)
    Implements getNext(int, int) without the need to consider result transformation, closeable and alive time tracking.
    final List<T>
    getPrevious(int count)
    Gets the previous specified amount of elements of this iterator.
    protected abstract List<S>
    getPreviousImpl(int count)
    Implements getPrevious(int) without the need to consider result transformation, closeable and alive time tracking.
    protected abstract boolean
    isClosed()
    Gets whether this remote iterator has been closed and its data is not available any more.
    protected void
    setCloseOnTraversal(Boolean closeOnTraversal)
    Sets whether closing of elements should be applied when traversing (Boolean.TRUE), when closing this remote iterator (Boolean.FALSE) or not at all (null).

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface de.aristaflow.adept2.model.common.collection.RemoteIterator

    drop, getRemainingAliveTime, isForwardOnly, isSnapshot, keepAlive

  • Field Details

    • logger

      protected final Logger logger
      The logger for logging messages instead of throwing exceptions.

    • transformator

      protected final Function<S,T> transformator
      The transformator function applied to each individual object before retrieval.

    • closeables

      protected final Collection<AutoCloseable> closeables
      The elements that are AutoCloseable that should be closed at the next traversal or when closing.

    • cleanup

      protected final Cleanup<IOException> cleanup
      The clean-up for closing the closeables as post-mortem task for this instance or when closing.

  • Constructor Details

    • AbstractRemoteIterator

      protected AbstractRemoteIterator(Function<S,T> transformator, Logger logger)
      Creates a new remote iterator with the designated transformator function applied to each element before returning it and using the designated logger for problems when closing (this remote iterator or the appropriate elements).
      Parameters:
      transformator - The transformator function applied to each individual object before retrieval.
      logger - The logger for logging messages instead of throwing exceptions.

  • Method Details

    • enter

      protected void enter()
      Allows to track entering a method reentrant.

    • exit

      protected Long exit()
      Tracks exiting a method reentrant.
      Returns:
      The possibly new remaining alive time in milliseconds or null in case the thread is still active and not exiting finally.

    • isClosed

      protected abstract boolean isClosed()
      Gets whether this remote iterator has been closed and its data is not available any more.
      Returns:
      Whether this remote iterator has been closed and its data is not available any more.

    • getNextImpl

      protected abstract List<S> getNextImpl(int count) throws DataSourceException, DataConsistencyException
      Implements getNext(int) without the need to consider result transformation, closeable and alive time tracking.
      Throws:
      DataSourceException
      DataConsistencyException

    • getNextImpl

      protected abstract List<S> getNextImpl(int count, int start) throws DataSourceException, DataConsistencyException
      Implements getNext(int, int) without the need to consider result transformation, closeable and alive time tracking.
      Throws:
      DataSourceException
      DataConsistencyException

    • getPreviousImpl

      protected abstract List<S> getPreviousImpl(int count) throws DataSourceException, DataConsistencyException
      Implements getPrevious(int) without the need to consider result transformation, closeable and alive time tracking.
      Throws:
      DataSourceException
      DataConsistencyException

    • getAllImpl

      protected abstract List<S> getAllImpl() throws DataSourceException, DataConsistencyException
      Implements getAll() without the need to consider result transformation, closeable and alive time tracking.
      Throws:
      DataSourceException
      DataConsistencyException

    • aboutToReturn

      protected List<T> aboutToReturn(List<S> elems)
      Tracks the AutoCloseables of the designated elements before returning them, handles their closing (when closeOnTraversal) and applies the transformation.
      Parameters:
      elems - The elements which are about to be returned in the current traversal and which may need to be tracked and/or transformed.
      Returns:
      The designated elements transformed appropriately which are about to be returned in the current traversal.

    • setCloseOnTraversal

      protected void setCloseOnTraversal(Boolean closeOnTraversal)
      Sets whether closing of elements should be applied when traversing (Boolean.TRUE), when closing this remote iterator (Boolean.FALSE) or not at all (null).
      Parameters:
      closeOnTraversal - Boolean.TRUE for immediate closing the AutoCloseable elements of the previous traversal, Boolean.FALSE for closing the AutoCloseable elements when closing this remote iterator, or null for no element closing at all.

    • getNext

      public final 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<S>
      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.
      AutoCloseables will be coupled to this RemoteIterator, so do not close them; clone them if required longer than until automatic closing which may happen when traversing or when closing this RemoteIterator.
      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 final 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<S>
      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.
      AutoCloseables will be coupled to this RemoteIterator, so do not close them; clone them if required longer than until automatic closing which may happen when traversing or when closing this RemoteIterator.
      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 final 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<S>
      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.
      AutoCloseables will be coupled to this RemoteIterator, so do not close them; clone them if required longer than until automatic closing which may happen when traversing or when closing this RemoteIterator.
      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 final 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<S>
      Returns:
      All elements of this iterator at once.
      AutoCloseables will be coupled to this RemoteIterator, so do not close them; clone them if required longer than until automatic closing which may happen when traversing or when closing this RemoteIterator.
      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.

    • closeOnTraversal

      public boolean closeOnTraversal()
      Description copied from interface: RemoteIterator
      Gets whether this remote iterator closes elements of AutoCloseable type when traversing to the next elements. If so, all elements of the previous traversal will be closed. That is, each call to RemoteIterator.getNext(int), RemoteIterator.getNext(int, int) or RemoteIterator.getPrevious(int) will cache all elements and close them with the next call to either RemoteIterator.getNext(int), RemoteIterator.getNext(int, int) or RemoteIterator.getPrevious(int). Otherwise the elements will be closed when closing this remote iterator.
      Specified by:
      closeOnTraversal in interface RemoteIterator<S>
      Returns:
      Whether this remote iterator closes elements when traversing to the next elements.

    • close

      public void close() throws IOException
      Description copied from interface: RemoteIterator
      Explicitly closes this iterator which allows to release occupied memory and resources. Closing 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:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface RemoteIterator<S>
      Specified by:
      close in interface de.aristaflow.adept2.model.communication.ServerSideProxy
      Throws:
      IOException - If there are problems accessing the underlying data source, an IOException will be thrown.