MediatorLiveData

Kotlin |Java

open class MediatorLiveData<T : Any!> : MutableLiveData<T>

kotlin.Any
↳	androidx.lifecycle.LiveData<T>
	↳	androidx.lifecycle.MutableLiveData<T>
		↳	androidx.lifecycle.MediatorLiveData

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&lt;&gt;(); liveDataMerger.addSource(liveData1, value -&gt; liveDataMerger.setValue(value)); liveDataMerger.addSource(liveData2, value -&gt; liveDataMerger.setValue(value)); 
  </integer>
 </integer>
</integer>

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<integer>
 () {
       private int count = 1;
 
       @Override public void onChanged(@Nullable Integer s) {
           count++;
           liveDataMerger.setValue(s);
           if (count &gt; 10) {
               liveDataMerger.removeSource(liveData1);
           }
       }
  });
  
</integer>

Summary

Public constructors
`<init>()` `LiveData` subclass which may observe other `LiveData` objects and react on `OnChanged` events from them.

Public methods
open Unit	`addSource(@NonNull source: LiveData<S>, @NonNull onChanged: Observer<in S>)` Starts to listen the given `source` LiveData, `onChanged` observer will be called when `source` value was changed.
open Unit	`removeSource(@NonNull toRemote: LiveData<S>)` Stops to listen the given `LiveData`.

Protected methods
open Unit	`onActive()`
open Unit	`onInactive()`

Inherited functions

From class LiveData

`T?`	`getValue()` Returns the current value. Note that calling this method on a background thread does not guarantee that the latest value set will be received.
`Boolean`	`hasActiveObservers()` Returns true if this LiveData has active observers.
`Boolean`	`hasObservers()` Returns true if this LiveData has observers.
`Unit`	`observe(@NonNull owner: LifecycleOwner, @NonNull observer: Observer<in T>)` Adds the given observer to the observers list within the lifespan of the given owner. The events are dispatched on the main thread. If LiveData already has data set, it will be delivered to the observer. The observer will only receive events if the owner is in `Lifecycle.State#STARTED` or `Lifecycle.State#RESUMED` state (active). If the owner moves to the `Lifecycle.State#DESTROYED` state, the observer will automatically be removed. When data changes while the `owner` is not active, it will not receive any updates. If it becomes active again, it will receive the last available data automatically. LiveData keeps a strong reference to the observer and the owner as long as the given LifecycleOwner is not destroyed. When it is destroyed, LiveData removes references to the observer & the owner. If the given owner is already in `Lifecycle.State#DESTROYED` state, LiveData ignores the call. If the given owner, observer tuple is already in the list, the call is ignored. If the observer is already in the list with another owner, LiveData throws an `IllegalArgumentException`.
`Unit`	`observeForever(@NonNull observer: Observer<in T>)` Adds the given observer to the observers list. This call is similar to `LiveData#observe(LifecycleOwner, Observer)` with a LifecycleOwner, which is always active. This means that the given observer will receive all events and will never be automatically removed. You should manually call `removeObserver(Observer)` to stop observing this LiveData. While LiveData has one of such observers, it will be considered as active. If the observer was already added with an owner to this LiveData, LiveData throws an `IllegalArgumentException`.
`Unit`	`onActive()` Called when the number of active observers change from 0 to 1. This callback can be used to know that this LiveData is being used thus should be kept up to date.
`Unit`	`onInactive()` 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 `hasObservers()`.
`Unit`	`removeObserver(@NonNull observer: Observer<in T>)` Removes the given observer from the observers list.
`Unit`	`removeObservers(@NonNull owner: LifecycleOwner)` Removes all observers that are tied to the given `LifecycleOwner`.

From class MutableLiveData

`Unit`	`postValue(value: T)`
`Unit`	`setValue(value: T)`

Public constructors

<init>

MediatorLiveData()

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.

LiveData<integer>
  liveData1 = ...;
  LiveData
 <integer>
   liveData2 = ...; MediatorLiveData
  <integer>
    liveDataMerger = new MediatorLiveData&lt;&gt;(); liveDataMerger.addSource(liveData1, value -&gt; liveDataMerger.setValue(value)); liveDataMerger.addSource(liveData2, value -&gt; liveDataMerger.setValue(value)); 
  </integer>
 </integer>
</integer>

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<integer>
 () {
       private int count = 1;
 
       @Override public void onChanged(@Nullable Integer s) {
           count++;
           liveDataMerger.setValue(s);
           if (count &gt; 10) {
               liveDataMerger.removeSource(liveData1);
           }
       }
  });
  
</integer>

Public methods

addSource

@MainThread open fun <S : Any!> addSource(
    @NonNull source: LiveData<S>, 
    @NonNull onChanged: Observer<in S>
): Unit

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.

Parameters
`source`	LiveData<S>: the `LiveData` to listen to
`onChanged`	Observer<in S>: The observer that will receive the events
`<S>`	The type of data hold by `source` LiveData

removeSource

@MainThread open fun <S : Any!> removeSource(@NonNull toRemote: LiveData<S>): Unit

Stops to listen the given LiveData.

Parameters
`toRemote`	LiveData<S>: `LiveData` to stop to listen
`<S>`	the type of data hold by `source` LiveData

Protected methods

onActive

@CallSuper protected open fun onActive(): Unit

onInactive

@CallSuper protected open fun onInactive(): Unit