Package icyllis.modernui.lifecycle

# Class MediatorLiveData<T>

java.lang.Object
icyllis.modernui.lifecycle.LiveData<T>
icyllis.modernui.lifecycle.MutableLiveData<T>
icyllis.modernui.lifecycle.MediatorLiveData<T>

Type Parameters:
  `T` - The type of data hold by this instance

public class MediatorLiveData<T> extends MutableLiveData<T>
`LiveData` subclass which may observe other `LiveData` objects and react on `OnChanged` events from them.

This class correctly propagates its active/inactive states down to source `LiveData` objects.

Consider the following scenario: we have 2 instances of `LiveData`, let's name them `liveData1` and `liveData2`, and we want to merge their emissions in one object: `liveDataMerger`. Then, `liveData1` and `liveData2` will become sources for the `MediatorLiveData liveDataMerger` and every time `onChanged` callback is called for either of them, we set a new value in `liveDataMerger`.

     LiveData<Integer> liveData1 = ...;
     LiveData<Integer> liveData2 = ...;

     MediatorLiveData<Integer> liveDataMerger = new MediatorLiveData<>();
     liveDataMerger.addSource(liveData1, liveDataMerger::setValue);
     liveDataMerger.addSource(liveData2, liveDataMerger::setValue);

Let's consider that we only want 10 values emitted by `liveData1`, to be merged in the `liveDataMerger`. Then, after 10 values, we can stop listening to `liveData1` and remove it as a source.

     liveDataMerger.addSource(liveData1, new Observer<>() {
          private int count = 1;

          @Override
          public void onChanged(@Nullable Integer s) {
              count++;
              liveDataMerger.setValue(s);
              if (count > 10) {
                  liveDataMerger.removeSource(liveData1);
              }
          }
     });

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MediatorLiveData()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<S> void`
  `addSource(LiveData<S> source, Observer<? super S> onChanged)`
  Starts to listen the given `source` LiveData, `onChanged` observer will be called when `source` value was changed.
  `protected void`
  `onActive()`
  Called when the number of active observers change to 1 from 0.
  `protected void`
  `onInactive()`
  Called when the number of active observers change from 1 to 0.
  `<S> void`
  `removeSource(LiveData<S> toRemote)`
  Stops to listen the given `LiveData`.

  ### Methods inherited from class icyllis.modernui.lifecycle.MutableLiveData

  `postValue, setValue`

  ### Methods inherited from class icyllis.modernui.lifecycle.LiveData

  `getValue, hasActiveObservers, hasObservers, observe, observeForever, removeObserver, removeObservers`

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

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

- ## Constructor Details

  - ### MediatorLiveData

    public MediatorLiveData()

- ## Method Details

  - ### addSource

    @UiThread public <S> void addSource(@Nonnull LiveData<S> source, @Nonnull Observer<? super S> onChanged)
    Starts to listen the given `source` LiveData, `onChanged` observer will be called when `source` value was changed.

    `onChanged` callback will be called only when this `MediatorLiveData` is active.

    If the given LiveData is already added as a source but with a different Observer, `IllegalArgumentException` will be thrown.

    Type Parameters:
      `S` - The type of data hold by `source` LiveData
    Parameters:
      `source` - the `LiveData` to listen to
      `onChanged` - The observer that will receive the events

  - ### removeSource

    @UiThread public <S> void removeSource(@Nonnull LiveData<S> toRemote)
    Stops to listen the given `LiveData`.
    Type Parameters:
      `S` - the type of data hold by `source` LiveData
    Parameters:
      `toRemote` - `LiveData` to stop to listen

  - ### onActive

    @CallSuper protected void onActive()
    Description copied from class: `LiveData`
    Called when the number of active observers change to 1 from 0.

    This callback can be used to know that this LiveData is being used thus should be kept up to date.

    Overrides:
      `onActive` in class `LiveData<T>`

  - ### onInactive

    @CallSuper protected void onInactive()
    Description copied from class: `LiveData`
    Called when the number of active observers change from 1 to 0.

    This does not mean that there are no observers left, there may still be observers but their lifecycle states aren't `Lifecycle.State.STARTED` or `Lifecycle.State.RESUMED` (like an Activity in the back stack).

    You can check if there are observers via `LiveData.hasObservers()`.

    Overrides:
      `onInactive` in class `LiveData<T>`