AsyncListDiffer
public
class
AsyncListDiffer
extends Object
java.lang.Object | |
↳ | androidx.recyclerview.widget.AsyncListDiffer<T> |
Helper for computing the difference between two lists via DiffUtil
on a background
thread.
It can be connected to a
RecyclerView.Adapter
, and will signal the
adapter of changes between sumbitted lists.
For simplicity, the ListAdapter
wrapper class can often be used instead of the
AsyncListDiffer directly. This AsyncListDiffer can be used for complex cases, where overriding an
adapter base class to support asynchronous List diffing isn't convenient.
The AsyncListDiffer can consume the values from a LiveData of List
and present the
data simply for an adapter. It computes differences in list contents via DiffUtil
on a
background thread as new List
s are received.
Use getCurrentList()
to access the current List, and present its data objects. Diff
results will be dispatched to the ListUpdateCallback immediately before the current list is
updated. If you're dispatching list updates directly to an Adapter, this means the Adapter can
safely access list items and total size via getCurrentList()
.
A complete usage pattern with Room would look like this:
@Dao interface UserDao { @Query("SELECT * FROM user ORDER BY lastName ASC") public abstract LiveData<List<User>> usersByLastName(); } class MyViewModel extends ViewModel { public final LiveData<List<User>> usersList; public MyViewModel(UserDao userDao) { usersList = userDao.usersByLastName(); } } 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); UserAdapter adapter = new UserAdapter(); viewModel.usersList.observe(this, list -> adapter.submitList(list)); recyclerView.setAdapter(adapter); } } class UserAdapter extends RecyclerView.Adapter<UserViewHolder> { private final AsyncListDiffer<User> mDiffer = new AsyncListDiffer(this, DIFF_CALLBACK); @Override public int getItemCount() { return mDiffer.getCurrentList().size(); } public void submitList(List<User> list) { mDiffer.submitList(list); } @Override public void onBindViewHolder(UserViewHolder holder, int position) { User user = mDiffer.getCurrentList().get(position); holder.bindTo(user); } public static final DiffUtil.ItemCallback<User> DIFF_CALLBACK = new DiffUtil.ItemCallback<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); } } }
See also:
Summary
Nested classes | |
---|---|
interface |
AsyncListDiffer.ListListener<T>
Listener for when the current List is updated. |
Public constructors | |
---|---|
AsyncListDiffer(Adapter adapter, ItemCallback<T> diffCallback)
Convenience for
|
|
AsyncListDiffer(ListUpdateCallback listUpdateCallback, AsyncDifferConfig<T> config)
Create a AsyncListDiffer with the provided config, and ListUpdateCallback to dispatch updates to. |
Public methods | |
---|---|
void
|
addListListener(ListListener<T> listener)
Add a ListListener to receive updates when the current List changes. |
List<T>
|
getCurrentList()
Get the current List - any diffing to present this list has already been computed and dispatched via the ListUpdateCallback. |
void
|
removeListListener(ListListener<T> listener)
Remove a previously registered ListListener. |
void
|
submitList(List<T> newList)
Pass a new List to the AdapterHelper. |
void
|
submitList(List<T> newList, Runnable commitCallback)
Pass a new List to the AdapterHelper. |
Inherited methods | |
---|---|
Public constructors
AsyncListDiffer
public AsyncListDiffer (Adapter adapter, ItemCallback<T> diffCallback)
Convenience for
AsyncListDiffer(new AdapterListUpdateCallback(adapter),
new AsyncDifferConfig.Builder().setDiffCallback(diffCallback).build());
Parameters | |
---|---|
adapter |
Adapter : Adapter to dispatch position updates to. |
diffCallback |
ItemCallback : ItemCallback that compares items to dispatch appropriate animations when |
AsyncListDiffer
public AsyncListDiffer (ListUpdateCallback listUpdateCallback, AsyncDifferConfig<T> config)
Create a AsyncListDiffer with the provided config, and ListUpdateCallback to dispatch updates to.
Parameters | |
---|---|
listUpdateCallback |
ListUpdateCallback : Callback to dispatch updates to. |
config |
AsyncDifferConfig : Config to define background work Executor, and DiffUtil.ItemCallback for
computing List diffs. |
Public methods
addListListener
public void addListListener (ListListener<T> listener)
Add a ListListener to receive updates when the current List changes.
Parameters | |
---|---|
listener |
ListListener : Listener to receive updates. |
getCurrentList
public List<T> getCurrentList ()
Get the current List - any diffing to present this list has already been computed and dispatched via the ListUpdateCallback.
If a null
List, or no List has been submitted, an empty list will be returned.
The returned list may not be mutated - mutations to content must be done through
submitList(List)
.
Returns | |
---|---|
List<T> |
current List. |
removeListListener
public void removeListListener (ListListener<T> listener)
Remove a previously registered ListListener.
Parameters | |
---|---|
listener |
ListListener : Previously registered listener. |
submitList
public void submitList (List<T> newList)
Pass a new List to the AdapterHelper. Adapter updates will be computed on a background thread.
If a List 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 List will be swapped in.
Parameters | |
---|---|
newList |
List : The new List.
|
submitList
public void submitList (List<T> newList, Runnable commitCallback)
Pass a new List to the AdapterHelper. Adapter updates will be computed on a background thread.
If a List 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 List will be swapped in.
The commit callback can be used to know when the List is committed, but note that it may not be executed. If List B is submitted immediately after List A, and is committed directly, the callback associated with List A will not be run.
Parameters | |
---|---|
newList |
List : The new List. |
commitCallback |
Runnable : Optional runnable that is executed when the List is committed, if
it is committed.
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.