Package com.avaya.clientservices.common

## Class DataRetrievalWatcher<T>

- java.lang.Object
- - com.avaya.clientservices.common.DataRetrievalWatcher<T>

- Type Parameters:
    `T` - The type of elements in the data collection.

      public class DataRetrievalWatcher<T>
      extends java.lang.Object

  This class defines an interface that client applications use to perform data retrieval operations for both static and dynamic collections of objects within the SDK.

  An instance of this watcher class is created by the client application for use in methods that initiate some form of data retrieval operation that runs asynchronously and updates a collection of objects. It can be used in cases where a static collection of objects is being retrieved (e.g. search results, etc) or for dynamically updated collections that are retrieved and then subsequently updated as events occur within the system (e.g. the active participants in a conference call).

  Following creation of a DataRetrievalWatcher object, and before the object is used in a method call, the application should install a `DataRetrievalWatcherListener` on the object. This allows the application-defined listener to be in place prior to initiating the action that will perform the data retrieval.

  For static collections, the `onCollectionChanged` callback will be invoked as objects are added to the collection during the retrieval. Once the static collection has been completely retrieved, the `onRetrievalCompleted` callback will be invoked indicating that the retrieval is complete. Following this, no additional callbacks will occur.

  For dynamic collections, the `onCollectionChanged` callback will be invoked as objects are added to the collection during the initial retrieval. It will also be called whenever any of the objects already in the collection are changed or removed. Once the initial retrieval of the dynamic collection has been completed, the `onRetrievalCompleted` callback will be invoked indicating that the initial retrieval is complete. Following this, the `onCollectionChanged` callback will be invoked whenever any changes to the collection occur.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataRetrievalWatcher()` | Constructs a new DataRetrievalWatcher object to be used to watch the progress of a retrieval of data elements of type T.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(DataRetrievalWatcherListener<T> listener)` | Add a listener to be notified of progress in retrieving a data collection and subsequent updates to that collection.
    `void` | `cancel()` | Cancels the current data retrieval operation if one is in progress.
    `int` | `getRequestId()` | The unique request ID associated with the retrieval operation.
    `java.util.List<T>` | `getSnapshot()` | Get the objects currently in the data collection.
    `boolean` | `isCancelled()` | Has the data retrieval operation been cancelled?
    `boolean` | `isCompleted()` | Has the data retrieval operation been completed successfully?
    `void` | `removeListener​(DataRetrievalWatcherListener<T> listener)` | Remove a listener from being notified of data collection retrieval progress and updates.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DataRetrievalWatcher

          public DataRetrievalWatcher()

      Constructs a new DataRetrievalWatcher object to be used to watch the progress of a retrieval of data elements of type T.

  - ### Method Detail

    - #### addListener

          public void addListener​(DataRetrievalWatcherListener<T> listener)

      Add a listener to be notified of progress in retrieving a data collection and subsequent updates to that collection.
      Parameters:
        `listener` - The listener to be added.

    - #### removeListener

          public void removeListener​(DataRetrievalWatcherListener<T> listener)

      Remove a listener from being notified of data collection retrieval progress and updates.
      Parameters:
        `listener` - The listener to be removed.

    - #### getRequestId

          public int getRequestId()

      The unique request ID associated with the retrieval operation.
      Returns:
        If the request has not been initiated or is not outstanding, the value will be 0.

    - #### getSnapshot

          public java.util.List<T> getSnapshot()

      Get the objects currently in the data collection.

      Note that the returned list is a snapshot in time and is not dynamically updated as the collection changes. Updates to the collection are reported to listeners through `DataRetrievalWatcherListener.onCollectionChanged(DataRetrievalWatcher, DataCollectionChangeType, List)`.

      Returns:
        The current set of objects in the data collection.

    - #### cancel

          public void cancel()

      Cancels the current data retrieval operation if one is in progress.

      After this, the cancellation will be reported asynchronously to listeners with a `DataRetrievalCancelledException` passed to `DataRetrievalWatcherListener.onRetrievalFailed(DataRetrievalWatcher, Exception)`.

    - #### isCancelled

          public boolean isCancelled()

      Has the data retrieval operation been cancelled?
      Returns:
        `true` if the operation was cancelled, `false` otherwise.

    - #### isCompleted

          public boolean isCompleted()

      Has the data retrieval operation been completed successfully?
      Returns:
        `true` if the operation was completed successfully, `false` otherwise.