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

Class 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 Cleanup<IOException> cleanup
      The clean-up for closing the closeables as post-mortem task for this instance or when closing.
      protected Collection<AutoCloseable> closeables
      The elements that are AutoCloseable that should be closed at the next traversal or when closing.
      protected Logger logger
      The logger for logging messages instead of throwing exceptions.
      protected 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).

    • Field Detail

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

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

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

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

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