AsyncPagedListDiffer

Added in 2.0.0
Deprecated in 3.0.0

public class AsyncPagedListDiffer<T extends Object>


Helper object for mapping a androidx.paging.PagedList into a RecyclerView.Adapter.

For simplicity, the PagedListAdapter wrapper class can often be used instead of the differ directly. This diff class is exposed for complex cases, and where overriding an adapter base class to support paging isn't convenient.

When consuming a LiveData of PagedList, you can observe updates and dispatch them directly to submitList. The AsyncPagedListDiffer then can present this updating data set simply for an adapter. It listens to PagedList loading callbacks, and uses DiffUtil on a background thread to compute updates as new PagedLists are received.

It provides a simple list-like API with getItem and itemCount for an adapter to acquire and present data objects.

A complete usage pattern with Room would look like this:

@Dao
interface UserDao {
@Query("SELECT * FROM user ORDER BY lastName ASC")
public abstract DataSource.Factory<Integer, User> usersByLastName();
}

class MyViewModel extends ViewModel {
public final LiveData<PagedList<User>> usersList;
public MyViewModel(UserDao userDao) {
usersList = new LivePagedListBuilder<>(
userDao.usersByLastName(), /* page size */20).build();
}
}

class MyActivity extends AppCompatActivity {
@Override
public void onCreate(Bundle savedState) {
super.onCreate(savedState);
MyViewModel viewModel = new ViewModelProvider(this).get(MyViewModel.class);
RecyclerView recyclerView = findViewById(R.id.user_list);
final UserAdapter adapter = new UserAdapter();
viewModel.usersList.observe(this, pagedList -> adapter.submitList(pagedList));
recyclerView.setAdapter(adapter);
}
}

class UserAdapter extends RecyclerView.Adapter&lt;UserViewHolder> {
private final AsyncPagedListDiffer&lt;User> differ =
new AsyncPagedListDiffer(this, DIFF_CALLBACK);
@Override
public int getItemCount() {
return differ.getItemCount();
}
public void submitList(PagedList&lt;User> pagedList) {
differ.submitList(pagedList);
}
@Override
public void onBindViewHolder(UserViewHolder holder, int position) {
User user = differ.getItem(position);
if (user != null) {
holder.bindTo(user);
} else {
// Null defines a placeholder item - AsyncPagedListDiffer will automatically
// invalidate this row when the actual object is loaded from the database
holder.clear();
}
}
public static final DiffUtil.ItemCallback&lt;User> DIFF_CALLBACK =
new DiffUtil.ItemCallback&lt;User>() {
@Override
public boolean areItemsTheSame(
@NonNull User oldUser, @NonNull User newUser) {
// User properties may have changed if reloaded from the DB, but ID is fixed
return oldUser.getId() == newUser.getId();
}
@Override
public boolean areContentsTheSame(@NonNull User oldUser, @NonNull User newUser) {
// NOTE: if you use equals, your object must properly override Object#equals()
// Incorrectly returning false here will result in too many animations.
return oldUser.equals(newUser);
}
}
}
Parameters
<T extends Object>

Type of the PagedLists this differ will receive.

Summary

Nested types

public interface AsyncPagedListDiffer.PagedListListener<T extends Object>

This interface is deprecated. PagedList is deprecated and has been replaced by PagingData

Public constructors

<T extends Object> AsyncPagedListDiffer(
    @NonNull RecyclerView.Adapter<@NonNull ?> adapter,
    @NonNull DiffUtil.ItemCallback<@NonNull T> diffCallback
)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

<T extends Object> AsyncPagedListDiffer(
    @NonNull ListUpdateCallback listUpdateCallback,
    @NonNull AsyncDifferConfig<@NonNull T> config
)

This method is deprecated. PagedList is deprecated and has been replaced by PagingData

Public methods

void
addLoadStateListener(
    @NonNull Function2<@NonNull LoadType, @NonNull LoadStateUnit> listener
)

Add a LoadState listener to observe the loading state of the current PagedList.

final void
addPagedListListener(
    @NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback
)

Add a callback to receive updates when the current PagedList changes.

void

Add a PagedListListener to receive updates when the current PagedList changes.

PagedList<@NonNull T>

Returns the PagedList currently being displayed by the differ.

T
getItem(int index)

Get the item from the current PagedList at the specified index.

int

Get the number of items currently presented by this Differ.

void

Remove a previously registered LoadState listener.

final void
removePagedListListener(
    @NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback
)

Remove a previously registered callback via addPagedListListener.

void

Remove a previously registered PagedListListener.

void
submitList(PagedList<@NonNull T> pagedList)

Pass a new PagedList to the differ.

void
submitList(PagedList<@NonNull T> pagedList, Runnable commitCallback)

Pass a new PagedList to the differ.

Public constructors

AsyncPagedListDiffer

public <T extends Object> AsyncPagedListDiffer(
    @NonNull RecyclerView.Adapter<@NonNull ?> adapter,
    @NonNull DiffUtil.ItemCallback<@NonNull T> diffCallback
)

Convenience for

AsyncPagedListDiffer(
AdapterListUpdateCallback(adapter),
AsyncDifferConfig.Builder<T>(diffCallback).build()
)
Parameters
@NonNull RecyclerView.Adapter<@NonNull ?> adapter

Adapter that will receive update signals.

@NonNull DiffUtil.ItemCallback<@NonNull T> diffCallback

The DiffUtil.ItemCallback instance to compare items in the list.

AsyncPagedListDiffer

public <T extends Object> AsyncPagedListDiffer(
    @NonNull ListUpdateCallback listUpdateCallback,
    @NonNull AsyncDifferConfig<@NonNull T> config
)

Public methods

addLoadStateListener

Added in 3.0.0
Deprecated in 3.0.0
public void addLoadStateListener(
    @NonNull Function2<@NonNull LoadType, @NonNull LoadStateUnit> listener
)

Add a LoadState listener to observe the loading state of the current PagedList.

As new PagedLists are submitted and displayed, the listener will be notified to reflect current LoadType.REFRESH, LoadType.PREPEND, and LoadType.APPEND states.

Parameters
@NonNull Function2<@NonNull LoadType, @NonNull LoadStateUnit> listener

LoadState listener to receive updates.

addPagedListListener

Added in 3.0.0
Deprecated in 3.0.0
public final void addPagedListListener(
    @NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback
)

Add a callback to receive updates when the current PagedList changes.

Parameters
@NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback

to receive updates.

addPagedListListener

Added in 2.1.0
Deprecated in 3.0.0
public void addPagedListListener(
    @NonNull AsyncPagedListDiffer.PagedListListener<@NonNull T> listener
)

Add a PagedListListener to receive updates when the current PagedList changes.

Parameters
@NonNull AsyncPagedListDiffer.PagedListListener<@NonNull T> listener

Listener to receive updates.

getCurrentList

Added in 2.0.0
Deprecated in 3.0.0
public PagedList<@NonNull T> getCurrentList()

Returns the PagedList currently being displayed by the differ.

This is not necessarily the most recent list passed to submitList, because a diff is computed asynchronously between the new list and the current list before updating the currentList value. May be null if no PagedList is being presented.

Returns
PagedList<@NonNull T>

The list currently being displayed, may be null.

getItem

Added in 2.0.0
Deprecated in 3.0.0
public T getItem(int index)

Get the item from the current PagedList at the specified index.

Note that this operates on both loaded items and null padding within the PagedList.

Parameters
int index

Index of item to get, must be >= 0, and <getItemCount.

Returns
T

The item, or null, if a null placeholder is at the specified position.

getItemCount

Added in 2.0.0
Deprecated in 3.0.0
public int getItemCount()

Get the number of items currently presented by this Differ. This value can be directly returned to RecyclerView.Adapter.getItemCount.

Returns
int

Number of items being presented.

removeLoadStateListener

Added in 3.0.0
Deprecated in 3.0.0
public void removeLoadStateListener(
    @NonNull Function2<@NonNull LoadType, @NonNull LoadStateUnit> listener
)

Remove a previously registered LoadState listener.

Parameters
@NonNull Function2<@NonNull LoadType, @NonNull LoadStateUnit> listener

Previously registered listener.

removePagedListListener

Added in 3.0.0
Deprecated in 3.0.0
public final void removePagedListListener(
    @NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback
)

Remove a previously registered callback via addPagedListListener.

Parameters
@NonNull Function2<PagedList<@NonNull T>, PagedList<@NonNull T>, Unit> callback

Previously registered callback.

removePagedListListener

Added in 2.1.0
Deprecated in 3.0.0
public void removePagedListListener(
    @NonNull AsyncPagedListDiffer.PagedListListener<@NonNull T> listener
)

Remove a previously registered PagedListListener.

Parameters
@NonNull AsyncPagedListDiffer.PagedListListener<@NonNull T> listener

Previously registered listener.

submitList

Added in 2.0.0
Deprecated in 3.0.0
public void submitList(PagedList<@NonNull T> pagedList)

Pass a new PagedList to the differ.

If a PagedList is already present, a diff will be computed asynchronously on a background thread. When the diff is computed, it will be applied (dispatched to the ListUpdateCallback), and the new PagedList will be swapped in as the currentList.

Parameters
PagedList<@NonNull T> pagedList

The new PagedList.

submitList

Added in 2.1.0
Deprecated in 3.0.0
public void submitList(PagedList<@NonNull T> pagedList, Runnable commitCallback)

Pass a new PagedList to the differ.

If a PagedList is already present, a diff will be computed asynchronously on a background thread. When the diff is computed, it will be applied (dispatched to the ListUpdateCallback), and the new PagedList will be swapped in as the current list.

The commit callback can be used to know when the PagedList is committed, but note that it may not be executed. If PagedList B is submitted immediately after PagedList A, and is committed directly, the callback associated with PagedList A will not be run.

Parameters
PagedList<@NonNull T> pagedList

The new PagedList.

Runnable commitCallback

Optional runnable that is executed when the PagedList is committed, if it is committed.

Throws
kotlin.IllegalStateException

if previous PagedList wasn't snapshotted correctly.