added in version 1.0.0
belongs to Maven artifact android.arch.lifecycle:livedata:1.1.1
Summary: Methods | Inherited Methods

Transformations

public class Transformations
extends Object

java.lang.Object
   ↳ android.arch.lifecycle.Transformations

Transformations for a LiveData class.

You can use transformation methods to carry information across the observer's lifecycle. The transformations aren't calculated unless an observer is observing the returned LiveData object.

Because the transformations are calculated lazily, lifecycle-related behavior is implicitly passed down without requiring additional explicit calls or dependencies.

Summary

Public methods

static <X, Y> LiveData<Y> map(LiveData<X> source, Function<X, Y> func)

Applies the given function on the main thread to each value emitted by source LiveData and returns LiveData, which emits resulting values.

static <X, Y> LiveData<Y> switchMap(LiveData<X> trigger, Function<X, LiveData<Y>> func)

Creates a LiveData, let's name it swLiveData, which follows next flow: it reacts on changes of trigger LiveData, applies the given function to new value of trigger LiveData and sets resulting LiveData as a "backing" LiveData to swLiveData.

Inherited methods

Public methods

map

added in version 1.0.0
LiveData<Y> map (LiveData<X> source, 
                Function<X, Y> func)

Applies the given function on the main thread to each value emitted by source LiveData and returns LiveData, which emits resulting values.

The given function func will be executed on the main thread.

Suppose that you have a LiveData, named userLiveData, that contains user data and you need to display the user name, created by concatenating the first and the last name of the user. You can define a function that handles the name creation, that will be applied to every value emitted by useLiveData. 

 LiveData userLiveData = ...;
 LiveData userName = Transformations.map(userLiveData, user -> {
      return user.firstName + " " + user.lastName
 });

Parameters
source LiveData: a LiveData to listen to
func Function: a function to apply
Returns
LiveData<Y> a LiveData which emits resulting values

switchMap

added in version 1.0.0
LiveData<Y> switchMap (LiveData<X> trigger, 
                Function<X, LiveData<Y>> func)

Creates a LiveData, let's name it swLiveData, which follows next flow: it reacts on changes of trigger LiveData, applies the given function to new value of trigger LiveData and sets resulting LiveData as a "backing" LiveData to swLiveData. "Backing" LiveData means, that all events emitted by it will retransmitted by swLiveData.

If the given function returns null, then swLiveData is not "backed" by any other LiveData.

The given function func will be executed on the main thread.

Consider the case where you have a LiveData containing a user id. Every time there's a new user id emitted, you want to trigger a request to get the user object corresponding to that id, from a repository that also returns a LiveData.

The userIdLiveData is the trigger and the LiveData returned by the repository.getUserById is the "backing" LiveData.

In a scenario where the repository contains User(1, "Jane") and User(2, "John"), when the userIdLiveData value is set to "1", the switchMap will call getUser(1), that will return a LiveData containing the value User(1, "Jane"). So now, the userLiveData will emit User(1, "Jane"). When the user in the repository gets updated to User(1, "Sarah"), the userLiveData gets automatically notified and will emit User(1, "Sarah").

When the setUserId method is called with userId = "2", the value of the userIdLiveData changes and automatically triggers a request for getting the user with id "2" from the repository. So, the userLiveData emits User(2, "John"). The LiveData returned by repository.getUserById(1) is removed as a source. 

 MutableLiveData userIdLiveData = ...;
 LiveData userLiveData = Transformations.switchMap(userIdLiveData, id ->
     repository.getUserById(id));

 void setUserId(String userId) {
      this.userIdLiveData.setValue(userId);
 }

Parameters
trigger LiveData: a LiveData to listen to
func Function: a function which creates "backing" LiveData
Returns
LiveData<Y>