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

    This handler tries to minimise closing effort for remote iterators. It will close 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 closed on-the-fly, a RemoteIteratorData will be returned even if there is no content.

    This class is thread-safe.

    • Constructor Detail

      • RemoteIteratorHandler

        public RemoteIteratorHandler​(Supplier<I> initDataCreator,
                             Supplier<N> dataCreator,
                             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.
        logService - The log service to retrieve the logger for log messages 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 closed 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 closed 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 closed.
        Throws:
        DataSourceException - If 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 closed implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been closed 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 closed 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 closed.
        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 closed, null will be returned.
        Throws:
        DataSourceException - If 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 closed implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been closed 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,
                    RemoteIterator<List<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 closed as soon as the last entry is transferred. It will also be set to be closed in case all content is provided at once. The caller of this method has to close 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 closed. 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 closed implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been closed 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 closed implicitly, an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been closed 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 IOException
        Calls RemoteIterator.keepAlive(long) on the designated iterator.
        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 close it automatically.
        Returns:
        The relative time the designated iterator will be kept alive longer. 0 indicates immediate closing. 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.
        IOException - If there are problems accessing the underlying data source, an IOException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If the designated iterator has been closed implicitly, a ServiceConnectionException will be thrown on client side.