added in version 1.0.0
belongs to Maven artifact android.arch.lifecycle:livedata-core:1.1.1

Summary: Ctors | Methods | Protected Methods | Inherited Methods

LiveData

The android.arch Architecture Components packages are no longer maintained. They have been superseded by the corresponding androidx.* packages. See androidx.lifecycle.LiveData instead.

public abstract class LiveData
extends Object

java.lang.Object
↳	android.arch.lifecycle.LiveData<T>

Known direct subclasses MutableLiveData<T> MutableLiveData<T> LiveData which publicly exposes setValue(T) and postValue(T) method.

Known indirect subclasses MediatorLiveData<T> MediatorLiveData<T> LiveData subclass which may observe other LiveData objects and react on OnChanged events from them.

---

LiveData is a data holder class that can be observed within a given lifecycle. This means that an Observer can be added in a pair with a LifecycleOwner, and this observer will be notified about modifications of the wrapped data only if the paired LifecycleOwner is in active state. LifecycleOwner is considered as active, if its state is STARTED or RESUMED. An observer added via observeForever(Observer) is considered as always active and thus will be always notified about modifications. For those observers, you should manually call removeObserver(Observer).

An observer added with a Lifecycle will be automatically removed if the corresponding Lifecycle moves to DESTROYED state. This is especially useful for activities and fragments where they can safely observe LiveData and not worry about leaks: they will be instantly unsubscribed when they are destroyed.

In addition, LiveData has onActive() and onInactive() methods to get notified when number of active Observers change between 0 and 1. This allows LiveData to release any heavy resources when it does not have any Observers that are actively observing.

This class is designed to hold individual data fields of ViewModel, but can also be used for sharing data between different modules in your application in a decoupled fashion.

See also:

• ViewModel

Summary

Public constructors
LiveData()

Public methods
T	getValue() Returns the current value.
boolean	hasActiveObservers() Returns true if this LiveData has active observers.
boolean	hasObservers() Returns true if this LiveData has observers.
void	observe(LifecycleOwner owner, Observer<T> observer) Adds the given observer to the observers list within the lifespan of the given owner.
void	observeForever(Observer<T> observer) Adds the given observer to the observers list.
void	removeObserver(Observer<T> observer) Removes the given observer from the observers list.
void	removeObservers(LifecycleOwner owner) Removes all observers that are tied to the given LifecycleOwner.

Protected methods
void	onActive() Called when the number of active observers change to 1 from 0.
void	onInactive() Called when the number of active observers change from 1 to 0.
void	postValue(T value) Posts a task to a main thread to set the given value.
void	setValue(T value) Sets the value.

Inherited methods
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait(long arg0, int arg1) final void wait(long arg0) final void wait()

Public constructors

LiveData

added in version 1.0.0

LiveData ()

Public methods

getValue

added in version 1.0.0

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.

Returns
T	the current value

hasActiveObservers

added in version 1.0.0

boolean hasActiveObservers ()

Returns true if this LiveData has active observers.

Returns
boolean	true if this LiveData has active observers

hasObservers

added in version 1.0.0

boolean hasObservers ()

Returns true if this LiveData has observers.

Returns
boolean	true if this LiveData has observers

observe

added in version 1.0.0

void observe (LifecycleOwner owner, 
                Observer<T> observer)

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 STARTED or RESUMED state (active).

If the owner moves to the 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 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.

Parameters
owner	LifecycleOwner: The LifecycleOwner which controls the observer
observer	Observer: The observer that will receive the events

observeForever

added in version 1.0.0

void observeForever (Observer<T> observer)

Adds the given observer to the observers list. This call is similar to 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.

Parameters
observer	Observer: The observer that will receive the events

removeObserver

added in version 1.0.0

void removeObserver (Observer<T> observer)

Removes the given observer from the observers list.

Parameters
observer	Observer: The Observer to receive events.

removeObservers

added in version 1.0.0

void removeObservers (LifecycleOwner owner)

Removes all observers that are tied to the given LifecycleOwner.

Parameters
owner	LifecycleOwner: The LifecycleOwner scope for the observers to be removed.

Protected methods

onActive

added in version 1.0.0

void onActive ()

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.

onInactive

added in version 1.0.0

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

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

postValue

added in version 1.0.0

void postValue (T value)

Posts a task to a main thread to set the given value. So if you have a following code executed in the main thread:

 liveData.postValue("a");
 liveData.setValue("b");
 

The value "b" would be set at first and later the main thread would override it with the value "a".

If you called this method multiple times before a main thread executed a posted task, only the last value would be dispatched.

Parameters
value	T: The new value

setValue

added in version 1.0.0

void setValue (T value)

Sets the value. If there are active observers, the value will be dispatched to them.

This method must be called from the main thread. If you need set a value from a background thread, you can use postValue(Object)

Parameters
value	T: The new value

• Annotations

  • OnLifecycleEvent

• Interfaces

  • DefaultLifecycleObserver
  • LifecycleObserver
  • LifecycleOwner
  • LifecycleRegistryOwner
  • Observer
  • ViewModelProvider.Factory
  • ViewModelStoreOwner

• Classes

  • AndroidViewModel
  • Lifecycle
  • LifecycleRegistry
  • LifecycleService
  • LiveData
  • LiveDataReactiveStreams
  • MediatorLiveData
  • MutableLiveData
  • ProcessLifecycleOwner
  • ServiceLifecycleDispatcher
  • Transformations
  • ViewModel
  • ViewModelProvider
  • ViewModelProvider.AndroidViewModelFactory
  • ViewModelProvider.NewInstanceFactory
  • ViewModelProviders
  • ViewModelProviders.DefaultFactory
  • ViewModelStore
  • ViewModelStores

• Enums

  • Lifecycle.Event
  • Lifecycle.State