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

Interface RemoteIterator<T extends List<?>>

  • Type Parameters:
    T - A collection type that is provided by this iterator. All of these collections have to be sorted, otherwise the iterator does not have a well-defined order for iterating.
    All Superinterfaces:
    AutoCloseable, Closeable, de.aristaflow.adept2.model.communication.ServerSideProxy
    All Known Implementing Classes:
    AbstractRemoteIterator, AbstractTimeTrackingRemoteIterator, CachingRemoteIterator, EmptyRemoteIterator, MemoryBasedCopyingRemoteIterator, ResultSetRemoteIterator, TransformingRemoteIterator
    public interface RemoteIterator<T extends List<?>>
extends de.aristaflow.adept2.model.communication.ServerSideProxy
    A RemoteIterator allows to retrieve parts of collections instead of whole collections. This shortens the retrieval time since such collections need not be fully created before the method corresponding requesting method can return. Additionally, less data needs to be transfered initially to a client. However, partial retrieval may lead to inconsistencies in case the underlying data of the iterator is changed while iterating. For instance, some elements of the original result may be removed while iterating, other elements may be added at an arbitrary position in the collection and therefore missed when iterating.
    The elements returned by a remote iterator may be AutoCloseable. In such cases, the remote iterator is responsible for closing these elements. This may happen in two variants: either when closing the remote iterator itself, which means caching all iterated elements internally, or when progressing the iteration by calling getNext(int), getNext(int, int) or getPrevious(int). In this case only the elements of a traversal need to be cached. Each time traversal proceeds, the elements of the previous traversal will be closed.
    Since iterators occupy resources while they are being used (for instance keeping a database connection open or holding data directly in memory), they have an alive time. As soon as the time passed, the iterator will be closed (dropped) which releases all occupied resources. Afterwards the iterator will not be usable any more; data retrieval methods will throw an IllegalStateException on server side itself) and all methods will throw a ServiceConnectionException on client side. If this alive time is insufficient, users may try to extend the remaining alive time. However, this does not need to succeed since the underlying resources of the iterator may not be able to extend their alive time, for instance pooled database connections.
    To improve resource handling, users may close an iterator any time and should do so as early as possible.

    Implementations of remote iterators may perform internal optimisations which are most adequate for the corresponding purpose. For instance, iterators may be lazy and provide only the necessary data (which requires an open connection to the corresponding data source), they may be eager and provide all data at once (although this is not advised since this contradicts to the original purpose of an iterator of not providing all data at once). Implementations may also be in-between that is prefetching some results but not all. Additionally, already retrieved results may be cached but this is also not required. However, caching is an easy way to detect inconsistencies in partial data already returned with partial data retrieved later.
    To prevent inconsistencies, a remote iterator may be based on a snapshot of the data. Such an iterator returns exactly the temporal state of the data when requesting the iterator. This can be done by either retrieving the complete data eagerly or by support of the underlying data source, for instance temporal databases or the restrictive usage of database transactions which prevents concurrent write accesses to the underlying data.

    Usually the configuration parameters for an iterator (alive time, whether to use a snapshot,...) are provided as parameters to the method returning the iterator. However, the iterator itself may have other values set. This should be checked by the user. Especially the alive time can differ due to restrictions on the resources used by the iterator implementation for instance using time-restricted pooled database connections.

    • 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 inherited from interface de.aristaflow.adept2.model.communication.ServerSideProxy

        DEFAULT_ALIVE_TIME

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      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.
      default void drop()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use close() instead.
      T getAll()
      Gets all elements of this iterator at once.
      T getNext​(int count)
      Gets the next specified amount of elements of this iterator.
      T getNext​(int count, int start)
      Gets the next specified amount of elements of this iterator starting at the designated index (0-based).
      T getPrevious​(int count)
      Gets the previous specified amount of elements of this iterator.
      long getRemainingAliveTime()
      Gets the time in milliseconds this iterator will still be valid and does allow access to the underlying data.
      boolean isForwardOnly()
      Gets whether this iterator only allows iterating in forward direction, that is calls to getNext(int) but not to getNext(int, int) and getPrevious(int).
      boolean isSnapshot()
      Gets whether this iterator is a snapshot and therefore its contents is not subject of change while iterating.
      long keepAlive​(long aliveTime)
      Keeps this iterator alive for the designated time span (in milliseconds).

    • Method Detail

      • getNext

        T getNext​(int count)
   throws DataSourceException,
          DataConsistencyException
        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.
        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.
        IllegalArgumentException - If count is non-positive (<= 0), an IllegalArgumentException will be thrown.
        IllegalStateException - If this iterator has been closed (explicitly or implicitly), an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • getNext

        T getNext​(int count,
          int start)
   throws DataSourceException,
          DataConsistencyException
        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).
        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.
        IllegalArgumentException - If count is non-positive (<= 0) or start is negative (< 0) or it refers to an index that is bigger than the amount of elements of this iterator, an IllegalArgumentException will be thrown. A forward only iterator will be reset to the last element, a non-forward only iterator will be reset to the first element.
        IllegalStateException - If this iterator has been closed (explicitly or implicitly), an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If this iterator is forward only, an UnsupportedOperationException will be thrown.

      • getPrevious

        T getPrevious​(int count)
       throws DataSourceException,
              DataConsistencyException
        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.
        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.
        IllegalArgumentException - If this iterator does not have any previous elements or count is non-positive (<= 0), an IllegalArgumentException will be thrown.
        IllegalStateException - If this iterator has been closed (explicitly or implicitly), an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.
        UnsupportedOperationException - If this iterator is forward only, an UnsupportedOperationException will be thrown.

      • getAll

        T getAll()
  throws DataSourceException,
         DataConsistencyException
        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.
        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.
        IllegalStateException - If this iterator has been closed (explicitly or implicitly), an IllegalStateException will be thrown on server side.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • isSnapshot

        boolean isSnapshot()
            throws DataSourceException
        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.
        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.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • isForwardOnly

        boolean isForwardOnly()
               throws DataSourceException
        Gets whether this iterator only allows iterating in forward direction, that is calls to getNext(int) but not to getNext(int, int) and getPrevious(int). This can be restricted by the underlying data structure, for instance a ResultSet.
        Returns:
        Whether this iterator only allows iterating in forward direction.
        Throws:
        DataSourceException - If there are problems accessing the underlying data source, a DataSourceException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • getRemainingAliveTime

        long getRemainingAliveTime()
        Gets the time in milliseconds this iterator will still be valid and does allow access to the underlying data. Afterwards the iterator will be closed automatically to save memory and resources.
        A negative value indicates a closed 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 de.aristaflow.adept2.model.communication.ServerSideProxy
        Returns:
        The time this iterator remains valid and can be used. Afterwards the iterator will be closed. Long.MIN_VALUE for an already closed remote iterator.
        Throws:
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • keepAlive

        long keepAlive​(long aliveTime)
        throws IOException
        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 closed this iterator.

        Specified by:
        keepAlive in interface de.aristaflow.adept2.model.communication.ServerSideProxy
        Parameters:
        aliveTime - The time in milliseconds to keep this iterator alive that is not to close it automatically.
        Returns:
        The relative time this iterator will be kept alive longer. 0 indicates immediate closing. A negative value represents the failure of extending the alive time, check getRemainingAliveTime() in this case whether extending the keep alive time has been successful or not.
        Throws:
        IOException - If there are problems accessing the underlying data source, an IOException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.

      • close

        void close()
    throws IOException
        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 de.aristaflow.adept2.model.communication.ServerSideProxy
        Throws:
        IOException - If there are problems accessing the underlying data source, an IOException will be thrown.
        de.aristaflow.adept2.model.communication.ServiceConnectionException - If this iterator has been closed (explicitly or implicitly), a ServiceConnectionException will be thrown on client side.