Package de.aristaflow.ilm.model.common.collection

Class RemoteIteratorHandler<T,​I extends InitialRemoteIteratorData<T>,​N extends RemoteIteratorData<T>>

  • Type Parameters:
    T - The collection type of the handled RemoteIterators.
    I - The type of the initial remote iterator data provided when requesting the remote iterator.
    N - The type of the remote iterator data provided when iterating.
    public class RemoteIteratorHandler<T,​I extends InitialRemoteIteratorData<T>,​N extends RemoteIteratorData<T>>
extends AbstractIteratorHandler<de.aristaflow.ilm.model.common.collection.RemoteIteratorWrapper<T>,​I,​N>
    This class handles remote iterators by assigning IDs to them and mapping these IDs to the respective handler. This allows to use a UUID instead of a remote iterator instance and thus simplifying interfaces not supporting Java objects, for instance web services.
    All methods of this class (except init(RemoteIterator, Integer) require a UUID identifying the corresponding remote iterator. If the ID does not refer to a remote iterator, an IllegalArgumentException will be thrown. Additionally, this handler keeps track of the alive time of known remote iterators. As soon as their alive time elapses, they will be removed from this handler.

    Remote iterators handled by this class also have an implicit extension of their alive time. That is, every time, a remote iterator is accessed, its alive time is extended. This applies until the first time, the alive time of the remote iterator is explicitly extended via API. After that, this alive time applies and needs to be explicitly extended.

    This handler tries to minimise dropping effort for remote iterators. It will drop them implicitly if

    • all content is transferred initially,
    • all content is retrieved at once (count is null),
    • the end of the data is reached and the iterator is forward-only, or
    • the iterator contains no data at all.
    Usually null will be returned instead of RemoteIteratorData if there is no content (for the current iteration). If the iterator is dropped on-the-fly, a RemoteIteratorData will be returned even if there is no content.

    This class is thread-safe.

    • Field Detail

      • logger

        protected final Logger logger
        The logger for problems when dropping a wrapped remote iterator.

    • Constructor Detail

      • RemoteIteratorHandler

        public RemoteIteratorHandler​(Supplier<I> initDataCreator,
                             Supplier<N> dataCreator,
                             long aliveTimeExtension,
                             LogService logService)
        Creates a new handler for remote iterator.
        Parameters:
        initDataCreator - The creator for the data provided initially when requesting the remote iterator.
        dataCreator - The creator for remote iterator data provided when iterating.
        aliveTimeExtension - The time in milliseconds to extend the alive time of the iterator implicitly.
        logService - The log service to retrieve the logger for the executor from.

    • Method Detail

      • init

        @Valid
public I init​(@NotNull
              @NotNull RemoteIterator<List<T>> iterator,
              @Positive
              @Positive Integer count)
       throws DataSourceException,
              DataConsistencyException
        Adds the designated iterator to this handler, creates an ID for it and calls getNext(UUID, Integer, Integer) with the designated parameters and start = null. The added iterator will be removed from this handler when its alive time elapsed. The alive time of the remote iterator will be extended in case of implicit extension. If the remote iterator is forward only, it will be dropped as soon as the last entry is transferred.
        Also if all entries of the iterator are retrieved now or the iterator has no entries at all, it will be dropped immediately.
        Parameters:
        iterator - The iterator to add to this handler.
        count - The amount of elements to retrieve in forward direction. This has to be > 0 or null. If this is null, all elements of the designated iterator will be returned.
        Returns:
        The initial meta data of the remote iterator and the next n elements of the designated 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 elements, null will be returned. If no count or Integer.MAX_VALUE is specified, all elements of the designated iterator will be returned at once and the iterator will be dropped.
        Throws:
        DataSourceException - If there are problems accessing the underlying data source or all elements should be retrieved (count is null) but the remote iterator forward only and currently not positioned before the first element, 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.
        IllegalArgumentException - If count is non-positive (<= 0), an IllegalArgumentException will be thrown.
        IllegalStateException - If the designated iterator has been dropped implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If a specific amount of elements and a start index are specified and the designated iterator is forward only, an UnsupportedOperationException will be thrown.

      • getNext

        @Valid
public N getNext​(@NotNull
                 @NotNull UUID iteratorId,
                 @Positive
                 @Positive Integer count,
                 @PositiveOrZero
                 @PositiveOrZero Integer start)
          throws DataSourceException,
                 DataConsistencyException
        Calls RemoteIterator.getNext(int) or RemoteIterator.getNext(int, int) on the designated iterator. The alive time of the remote iterator will be extended in case of implicit extension. If the remote iterator is forward only, it will be dropped as soon as the last entry is transferred.
        Parameters:
        iteratorId - The ID of the iterator to forward the call to.
        count - The amount of elements to retrieve in forward direction. This has to be > 0 or null. If this is null, all elements of the designated iterator will be returned and the iterator will be dropped.
        start - The index of the element from which to retrieve the next count elements when requesting a limited amount of elements (count > 0). 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 the designated iterator. If this is null, the next count elements will be returned.
        Returns:
        Some meta data of the remote iterator and the next n elements of the designated iterator, where n is the specified count. In case of an insufficient amount of next elements remaining only the available elements (or no elements) will be returned. If no count or Integer.MAX_VALUE is specified, all remaining elements of the designated iterator will be returned at once. If no count or Integer.MAX_VALUE is specified and there are no more next elements and the forward-only iterator has been dropped, null will be returned.
        Throws:
        DataSourceException - If there are problems accessing the underlying data source or all elements should be retrieved (count is null) but the remote iterator forward only and currently not positioned before the first element, 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.
        IllegalArgumentException - If the designated ID does not refer to a RemoteIterator known by this handler, an IllegalArgumentException will be thrown.
        IllegalArgumentException - If count is non-positive (<= 0) or start is negative (< 0) or start refers to an index that is bigger than the amount of elements of the designated iterator, an IllegalArgumentException will be thrown.
        IllegalStateException - If the designated iterator has been dropped implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If a specific amount of elements and a start index are specified and the designated iterator is forward only, an UnsupportedOperationException will be thrown.

      • getNext

        protected N getNext​(UUID iteratorId,
                    de.aristaflow.ilm.model.common.collection.RemoteIteratorWrapper<T> iterator,
                    Integer count,
                    Integer start)
             throws DataSourceException,
                    DataConsistencyException
        Calls RemoteIterator.getNext(int), RemoteIterator.getNext(int, int) or RemoteIterator.getAll() on the designated iterator. The alive time of the remote iterator will be extended in case of implicit extension. If the remote iterator is forward only, it will be set to be dropped as soon as the last entry is transferred. It will also be set to be dropped in case all content is provided at once. The caller of this method has to drop the iterator!
        Parameters:
        iteratorId - The ID of the iterator to forward the call to.
        iterator - The iterator to forward the call to.
        count - The amount of elements to retrieve in forward direction. This has to be > 0 or null. If this is null, all elements of the designated iterator will be returned and the iterator will be dropped. Therefore null is only allowed for the first element retrieval.
        start - The index of the element from which to retrieve the next count elements when requesting a limited amount of elements (count > 0). 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 the designated iterator. If this is null, the next count elements will be returned.
        Returns:
        Some meta data of the remote iterator and the next n elements of the designated iterator, where n is the specified count. In case of an insufficient amount of next elements remaining only the available elements (or no elements) will be returned.
        Throws:
        DataSourceException - If there are problems accessing the underlying data source or all elements should be retrieved (count is null) but the remote iterator forward only and currently not positioned before the first element, 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.
        IllegalArgumentException - If the designated ID does not refer to a RemoteIterator known by this handler, an IllegalArgumentException will be thrown.
        IllegalArgumentException - If count is non-positive (<= 0) or start is negative (< 0) or start refers to an index that is bigger than the amount of elements of the designated iterator, an IllegalArgumentException will be thrown.
        IllegalStateException - If the designated iterator has been dropped implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If a specific amount of elements and a start index are specified and the designated iterator is forward only, an UnsupportedOperationException will be thrown.

      • getPrevious

        @Valid
public N getPrevious​(@NotNull
                     @NotNull UUID iteratorId,
                     @NotNull @Positive
                     @NotNull @Positive Integer count)
              throws DataSourceException,
                     DataConsistencyException
        Calls RemoteIterator.getPrevious(int) on the designated iterator.
        Parameters:
        iteratorId - The ID of the iterator to forward the call to.
        count - The amount of elements to retrieve in backward direction. This has to be > 0.
        Returns:
        Some meta data of the remote iterator and the previous n elements of the designated 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 as content.
        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 the designated iterator is forward only, a DataConsistencyException will be thrown.
        IllegalArgumentException - If the designated ID does not refer to a RemoteIterator known by this handler, an IllegalArgumentException will be thrown.
        IllegalArgumentException - If the designated iterator does not have any previous elements or count is non-positive (<= 0), an IllegalArgumentException will be thrown.
        IllegalStateException - If the designated iterator has been dropped implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If the designated iterator is forward only, an UnsupportedOperationException will be thrown.

      • keepAlive

        public long keepAlive​(@NotNull
                      @NotNull UUID iteratorId,
                      @NotNull
                      @NotNull Long aliveTime)
               throws DataSourceException
        Calls RemoteIterator.keepAlive(long) on the designated iterator and sets the alive time to explicit extension.
        Parameters:
        iteratorId - The ID of the iterator to forward the call to.
        aliveTime - The time in milliseconds to keep the designated iterator alive that is not to drop it automatically.
        Returns:
        The relative time the designated 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:
        IllegalArgumentException - If the designated ID does not refer to a RemoteIterator known by this handler, an IllegalArgumentException will be thrown.
        DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.

      • drop

        public void drop​(@NotNull
                 @NotNull UUID iteratorId)
          throws DataSourceException
        Calls RemoteIterator.drop() on the designated iterator and removes it from this handler.
        Forward only remote iterators will be automatically dropped as soon as the last data is transferred.
        Parameters:
        iteratorId - The ID of the iterator to forward the call to.
        Throws:
        IllegalArgumentException - If the designated ID does not refer to a RemoteIterator known by this handler, an IllegalArgumentException will be thrown.
        DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been dropped implicitly, a ServiceConnectionException will be thrown on client side.