MediatorLiveData

Artifact: androidx.lifecycle:lifecycle-livedata

Added in 2.0.0

Kotlin |Java

android

class MediatorLiveData<T> : MutableLiveData

kotlin.Any
↳	androidx.lifecycle.LiveData
	↳	androidx.lifecycle.MutableLiveData
		↳	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 MediatorLiveData object: liveDataMerger. Then, liveData1 and liveData2 will become sources for the 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, value -> liveDataMerger.setValue(value));
liveDataMerger.addSource(liveData2, value -> liveDataMerger.setValue(value));

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 > 10) {
             liveDataMerger.removeSource(liveData1);
         }
     }
});

Parameters
`<T>`	The type of data hold by this instance

Summary

Public constructors
`MediatorLiveData()` Creates a MediatorLiveData with no value assigned to it.	android
`MediatorLiveData(value: T!)` Creates a MediatorLiveData initialized with the given `value`.	android

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

Protected functions
`Unit`	`@CallSuper onActive()` Called when the number of active observers change from 0 to 1.	android
`Unit`	`@CallSuper onInactive()` Called when the number of active observers change from 1 to 0.	android

Inherited functions

From androidx.lifecycle.LiveData

`T?`	`getValue()` Returns the current value.	android
`Boolean`	`hasActiveObservers()` Returns true if this LiveData has active observers.	android
`Boolean`	`hasObservers()` Returns true if this LiveData has observers.	android
`Boolean`	`isInitialized()` Returns whether an explicit value has been set on this LiveData.	android
`Unit`	`@MainThread observe(owner: LifecycleOwner, observer: Observer<T!>)` Adds the given observer to the observers list within the lifespan of the given owner.	android
`Unit`	`@MainThread observeForever(observer: Observer<T!>)` Adds the given observer to the observers list.	android
`Unit`	`@MainThread removeObserver(observer: Observer<T!>)` Removes the given observer from the observers list.	android
`Unit`	`@MainThread removeObservers(owner: LifecycleOwner)` Removes all observers that are tied to the given `LifecycleOwner`.	android

From androidx.lifecycle.MutableLiveData

`Unit`	`postValue(value: T!)` Posts a task to a main thread to set the given value.	android
`Unit`	`setValue(value: T!)` Sets the value.	android

Public constructors

MediatorLiveData

android

Added in 2.0.0

MediatorLiveData()

Creates a MediatorLiveData with no value assigned to it.

MediatorLiveData

android

Added in 2.6.0

MediatorLiveData(value: T!)

Creates a MediatorLiveData initialized with the given value.

Parameters
`value: T!`	initial value

Public functions

addSource

android

Added in 2.0.0

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

Starts to listen to 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
`<S>`	The type of data hold by `source` LiveData
`source: LiveData<S!>`	the `LiveData` to listen to
`onChanged: Observer<S!>`	The observer that will receive the events

removeSource

android

Added in 2.0.0

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

Stops to listen the given LiveData.

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

Protected functions

onActive

android

@CallSuper
protected fun onActive(): Unit

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.

onInactive

android

@CallSuper
protected fun onInactive(): Unit

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 STARTED or RESUMED (like an Activity in the back stack).

You can check if there are observers via hasObservers.