How to Use Loaders in Android

With the introduction of Honeycomb Loaders became the preferred way to access data of databases or content providers. They load data asynchronously and notify listeners when the results are ready.

Google did not only introduce Loaders but also deprecated the previous way to handle a Cursor within your activities. You shouldn’t use startManagingCursor() or managedQuery() in your projects anymore.

With managed cursors queries and requeries are executed on the UI thread. This could cause the app to feel unresponsive or to even display an ANR error message. With Loaders your queries will no longer run on the UI thread and your app remains responsive.

In this post I introduce the classes that form the Loader API and show you how to use them.

The classes and interfaces of the Loader API
Class Usage
LoaderManager Manages your Loaders for you. Responsible for dealing with the Activity or Fragment lifecycle
LoaderManager.LoaderCallbacks A callback interface you must implement
Loader The base class for all Loaders
AsyncTaskLoader An implementation that uses an AsyncTask to do its work
CursorLoader A subclass of AsyncTaskLoader for accessing ContentProvider data

In the following sections I describe most of these classes and what you need to know about them – starting with the LoaderManager.

LoaderManager

This class keeps your Loaders in line with the lifecycle of your activities or fragments. If Android destroys your fragments or activities, the LoaderManager notifies the managed loaders to free up their resources. The LoaderManager is also responsible for retaining your data on configuration changes like a change of orientation and it calls the relevant callback methods when the data changes. In short: The LoaderManager is way more powerful than the old startManagingCursor() or managedQuery() methods.

You do not instantiate the LoaderManager yourself. Instead you simply call getLoaderManager() from within your activity or your fragment to get hold of it.

Most often you are only interested in two methods of the manager:

  • initLoader() and
  • restartLoader()

initLoader()

The initLoader() method adds a Loader to the LoaderManager:

getLoaderManager().initLoader(LIST_ID, null, this);

It takes three arguments:

  • a unique ID for this loader,
  • an optional Bundle with arguments for your Loader and
  • a LoaderCallbacks interface

You might need the ID for further method calls. So using a final static field for the ID makes your code more readable. The Bundle can be used to pass additional arguments to your Loader, but isn’t used by the CursorLoader. The third argument, the callback interface, will be covered in detail later on.

The initLoader() method creates a new Loader only if for this ID none has been created previously. Keep in mind that Android deals with configuration changes for you, thus a simple change in orientation is enough to trigger a new call to initLoader(). In this case the method returns the existing instance and your query is not executed again.

restartLoader()

Because Android doesn’t execute the query again, you need a way to re-initialize the Loader when data, that is used to build the query, changes. Typical examples are search queries.

You reset your Loader by using the restartLoader() method. It takes the same parameters as initLoader(). Of course you have to use the same ID you used for initializing.

getLoaderManager().restartLoader(LIST_ID, null, this);

LoaderManager.LoaderCallbacks

The interface LoaderCallbacks defines methods you must implement to create your Loader, to deal with the results and to clean up resources.

Since the interface is parameterized you must specify the type of data your Loader holds. Most often the type will be Cursor:

public class YourFragment extends Fragment 
      implements LoaderCallbacks<Cursor> {
   //...
}

The methods you have to implement are:

  • onCreateLoader(),
  • onLoadFinished() and
  • onLoadReset()

In the next sections I show what to do in each of these callback methods.

onCreateLoader()

The LoaderManager calls this method when you call initLoader() for the first time. As mentioned, the manager only calls this method if no loader for the given ID exists.

The method gets an int value and a Bundle passed in. These are the same values you used for your initLoader() call.

A typical example creating a CursorLoader looks like this:

public Loader<Cursor> onCreateLoader(int id, Bundle args) {
   CursorLoader loader = new CursorLoader(
         this.getActivity(),
         SOME_CONTENT_URI, 
         projection, 
         selection, 
         selectionArgs, 
         sortOrder);
   return loader;
}

As you can see the parameters are a Context object plus those of the ContentResolver’s query() method. If you’re not familiar with these arguments, I recommend you read my post about accessing content providers.

If you need to track multiple queries and thus use different IDs for your Loaders, all you need to add is a simple case- or if-else-branch.

onLoadFinished()

This method is the most interesting one. Here you update the UI based on the results of your query.

For ListAdapters you simply swap the cursor of the adapter as described in the section “Changes needed for CursorAdapters“.

For all other cases you have to get references to the view elements and set their value according to the result.

This is how it looks in the sample project:

public void onLoadFinished(
      Loader<Cursor> loader, 
      Cursor cursor) {
   if (cursor != null && cursor.getCount() > 0) {
      cursor.moveToFirst();
      int idIndex = 
            cursor.getColumnIndex(LentItems._ID);
      int nameIndex = 
            cursor.getColumnIndex(LentItems.NAME);
      int borrowerIndex = 
            cursor.getColumnIndex(LentItems.BORROWER);
      this.itemId = cursor.getLong(idIndex);
      String name = cursor.getString(nameIndex);
      String borrower = cursor.getString(borrowerIndex);
      ((EditText)findViewById(R.id.name)).
            setText(name);
      ((EditText)findViewById(R.id.person)).
            setText(borrower);
   }
}

onLoadReset()

This method allows you to release any resources you hold, so that the Loader can free them. You can set any references to the cursor object you hold to null.
But do not close the cursor – the Loader does this for you.

See also the section about how to deal with CursorAdapters.

Loader, AsyncTaskLoader and CursorLoader

The Loader interface and its implementations are not very interesting – unless you write your own custom Loaders. You have to create a Loader of course. But other than using the constructor of CursorLoader, you normally do not interact with these objects yourself.

If you use multiple Loaders you need to access the ID in the callback methods. You can do so by calling getId() on the loader passed in to the callbacks.

If you want to write a custom Loader yourself, please have a look at Alex Lockwood’s tutorial on implementing loaders.

Changes needed for CursorAdapters

An important use of cursors in Android is to use a CursorAdapter as data source for ListViews, AutoCompleteTextViews and so on. When working with Loaders you have to adapt the old way slightly.

First of all: You do not have a Cursor object before the onLoadFinished() method of your callback has been called. In other words: The cursor is not ready when you create the adapter. Thus you create the adapter using null for the cursor argument:

SimpleCursorAdapter adapter = 
      new SimpleCursorAdapter(
            getApplicationContext(), 
            android.R.layout.simple_list_item_1, 
            null, 
            columns, 
            layoutIds, 
            0);

When the cursor is finally available you have to add it. You do this by calling swapCursor() on your adapter and passing in the cursor object of your callback method:

public void onLoadFinished(
      Loader<Cursor> loader, 
      Cursor cursor) {
   ((SimpleCursorAdapter)this.getListAdapter()).
         swapCursor(cursor);
}

And to clean up resources in the onLoadReset() method you also use swapCursor(), this time passing in a null value:

public void onLoaderReset(Loader<Cursor> loader) {
   ((SimpleCursorAdapter)this.getListAdapter()).
         swapCursor(null);
}

Use the Support Library for older Android versions

To support newer features on older Android versions, Google provides the Support Library. The two main components this library contains are Fragments and Loaders.

You can and should use this library for projects that must support older versions. All reasons for using the Loader-API are valid for pre-Honeycomb devices as well.

But you have to keep an eye on the import statements. All import statements for classes of the Support Library begin with android.support.v4:

import android.support.v4.app.LoaderManager;
import android.support.v4.app.LoaderManager.LoaderCallbacks;
import android.support.v4.content.CursorLoader;
import android.support.v4.content.Loader;

Don’t mix classes of the support library with normal classes. The compiler will spot most problems for you and then there is also Lint to help you. But if you ever wonder why some code is marked as invalid, this most likely is the reason.

To use Loaders for older Android versions, you need to use activities or fragments of the Support Library. The normal ones do not have the getLoaderManager() method before Honeycomb. You project would still compile (if your build target is at least SDK 11) but at runtime you would get a NoSuchMethodError on older devices.

Using Loaders to access your SQLiteDatabase

Since Android’s CursorLoader is only for Cursors returned by content providers we need another Loader implementation if we want to use SQLite directly.

Thankfully Mark Murphy has written a library that offers enhancements to the Loader framework. This library also contains a SQLiteCursorLoader.

To use Mark Murphy’s SQLiteCursorLoader you have to create an SQL select statement and pass it to the constructor.The constructor also expects an SQLiteOpenHelper object. An example of the onCreateLoader() method could look like this:

public Loader<Cursor> onCreateLoader(int id, Bundle args) {
   String rawQuery = "SELECT ...";
   String[] queryParams = // to substitute placeholders
   SQLiteCursorLoader loader = 
   new SQLiteCursorLoader(
         getActivity().getApplicationContext(), 
         yourSqliteOpenHelper, 
         rawQuery, 
         queryParams);
   return loader;
}

But there is more to it. You have to use this loader also for deleting, updating or inserting rows as well. Only by doing so, the loader knows about a data change and can call the correct callback methods.

I won’t go into these details here. See the project’s github page or have a look at Mark Murphy’s sample project.

If you intend to use this library, don’t use the jar-file offered on the project page. It is outdated. Instead clone the git repository and add the project to your IDE directly.

When not to use Loaders

On reddit, cokacokacoh noted that my post missed a section on when not to use Loaders. He was right of course. So I added the following paragraph to this post.

As cokacokacoh points out, you shouldn’t use Loaders if you need the background tasks to complete. Android destroys Loaders together with the Activities/Fragments they belong to. If you want to do some tasks, that have to run until completion, do not use Loaders. You should use services for this kind of stuff instead.

Keep in mind that Loaders are special components to help you create responsive UIs and to asynchronously load data that this UI component needs. That’s the reason why Loaders are tied to the lifecycle of their creating components. Do not try to abuse them for anything else!

Lessons learned

In this blog post you have seen how to use the Loader framework. And since this framework is available for older Android versions using the Support Library there is no reason not to use it.

The CursorLoader provided by Android is useful for content providers. But not all projects use these. If your project uses SQLite directly you can use Mark Murphys SQLiteCursorLoader as shown above.

I didn’t cover how to write Loaders on your own. If you need to do so, +Alex Lockwood has a nice tutorial on implementing loaders.

Please let me know in the comments if this post was helpful or if you have any questions left. And don’t forget to plus one or tweet this post, if you liked it :-)

Share this article:

You can leave a response, or trackback from your own site.

33 Responses to “How to Use Loaders in Android”

  1. Great post! BTW, I think it’s worth clarifying that Mark Murphy’s SQLiteCursorLoader is a bit different from the Android SDK CursorLoader in that there is no global notification system in place to notify the Loader when changes are made to the underlying SQLiteDatabase. That is, with a CursorLoader you can use the ContentResolver to modify the underlying data source from wherever you want and you can trust that the CursorLoader will be notify about these changes. The same cannot be said about the SQLiteCursorLoader… all modifications to the SQLiteDatabase *must* be followed by a call to the loader’s “onContentChanged()” method, which will notify the Loader to reload its data. IIRC, the LoaderEx project includes a few AsyncTasks that you can use to perform asynchronous insertions/updates/deletions to the SQLiteDatabase, each of which are followed by a call to “onContentChanged()”.

    I guess it’s not that big of a deal, but this is one of the reasons why I prefer using ContentProviders. :)

  2. Lem Lordje Ko says:

    My content provider has the notifyUriChange() and related stuffs.
    I noticed that onLoadFinished() gets called when the data gets changed. Is restartLoader() called automatically?

    The problem is I find the need to handle onLoadFinished() differently when it’s from restartLoader(). Is there a way to do this?

    • The onLoaderFinished() method gets called by the LoaderManager directly without the use of restartLoader(). That’s triggered by the ContentObserver used within CursorLoader.

      Is that what you were hoping for? And why would you want to treat the loading differently depending on which of the initLoader() vs. restartLoader() methods caused it?

  3. [...] une utilisation via les ContentProvider et non une simple base de données… A bon entendeur! http://www.grokkingandroid.com/using-loaders-in-android/  Rencontrez vous !Si vous souhaitez rencontrer d’autres développeurs européens, discuter [...]

  4. Vipul says:

    Very Nice Tutorial!! Clear and Concise !!

  5. Miguel says:

    Hi Wolfram, first of all thanks for tutorials & Google+ shares

    From what I’ve understood about Loaders, regarding DB access their only purpose is to Read, as we can’t be sure that an Insert, Update or Delete will take place. Services are the way to go for must-happen operations.

    If I’m right about this, why does Mark Murphy’s ‘loaderex’ project mention the possibility of using Insert, delete or update with his SQLiteCursorLoader? I know you are not the developer, but since you recommend the library maybe you can shed light on this topic.

    On a more abstract approach, in the past I’ve used DAOs accessing the DB directly and DAOs accessing DB through ContentProviders, but right now I’m quite confused with all the options available. To your understanding, what’s the best DB architecture?

    In a new project I don’t need to share data with other applications, so I’m considering using Services + DAOs with direct access to DB through a synchronized singleton, and Loaders for reading that data.

    Sorry for long post, needed to put my doubts on paper, no one near experienced enough to ask :(

    • About LoaderEx: See the Activity ConstantsBrowserACL from his sample project. While the Loader is initially used as usual (for querying data) you can later on use the same loader to delete or add data. And you get automatic reloading with this.

      I personally wouldn’t use ContentProvider until I have to. I have to when I either want to be notified about changes in the underlying data or when I want to export data. Notifying myself about changes is much easier with CP because they are specifically designed to do so and thus you do not need too much code. If you export data, think about possible joins people might want to use!

      About DAOs: Fine. But don’t do them yourself. Use GreenDAO, ormlight or StORM.

  6. Prashant says:

    Hello Wolfram, very well-informed post and got a fine knowledge about Cursor Loader. I’ve already gone through many posts and blog but after reading your post only I became comfortable with Loaders. I’ve to use it in my project, so thanks.

  7. Dickson Owuor says:

    of much help, thanks

  8. Tobias says:

    Thank you for the valueable article. Do you know of a implementation or article which concentrates on the special requirements of a map view such as for Google Maps on Android?

    • With regards to Loaders? I don’t know of any special posts/articles about the combination of Loaders and a MapView. Well, I think, I didn’t understand your question. Can you expand a bit more on what you want/need?

  9. Hello,
    Is there a use case for calling destroy loader().

    Thanks,
    Igor

    • Well, rarely :-)

      If you need to de-couple your loader lifecycle from the component lifecycle is one use case. For example if – once the Loader has finished – you want to display the result but do not want it to reload with the next config change.

      Or if you either need to pass in a different Bundle or a different LoaderCallbacks when restarting a loader. In this case you would call destroyLoader() first and initLoader() with the changed arguments afterwards. A call to restartLoader() wouldn’t work in that case.

  10. Stu says:

    Some great tutorials on your site, but for some reason every time I visit this page it resets my router!

  11. mohammed says:

    hi, i have gone through your tutorial an it was helpfull to me but i have one doubt what is difference between content reolver and loader both are used for accessing content providers then what is difference between them where exactly we can use this two?

    • A Loader is a helper to asynchronously access a data provider. The data source could be anything – but very often is a ContentProvider. The Loader keeps track of the state the data is in and reloads data whenever the content has changed.

      A ContentResolver on the other hand works only with ContentProviders. It doesn’t load anything and it doesn’t reload anything. It just get’s notified whenever the data within the content provider has changed.

      The CursorLoader, a concrete Loader implementation provided by the framework, relies on ContentObservers to get notifications of any change in the underlying data. For any other data provider you would have to create something comparable as well to enable Loaders to be as powerful with that data provider.

      So the ContentObserver is what makes the CursorLoader so powerful.

  12. sunny says:

    hi..

    I want to refresh system time to be updated on screen without any button-clicks.plz help me how to do it?

  13. Gödel77 says:

    Hello Wolfram,
    I work with CursorLoader with my custom CursorAdapter and pass a null Cursor to constructor as you made with SimpleCursorAdapter, how you explained so good.
    My Problem is that I can save data in my SQLiteDatabase but ListView is not populated and I tried with

    // dataAdapter is my Custom CursorAdapter
    dataAdapter.notifyDataSetChanged();
    listView.SetAdapter(dataAdapter);

    in the last line of onLoadFinished but I can’t see yet data in ListView.

    Kind Regards

    • Gödel77 says:

      Hi Wolfram, that was my error, I knew where I had to notify and set the ListView with the adapter, precise in “onLoadFinished” but I did it below “adapter.swap(cursor)” Line and we must to do it above.

      Good WebSite.

      Grüße aus Niederbayern

  14. J.C says:

    Hello, i wrote my own content provider, implemented CursorLoader on my main activity. I have list of items on main screen and i get them through ContentResolver . But when i call update on any item using COntentResolver it is toooo slow. I couldnt figure it out why. I’ll be happy if you can help me with this. Please take a look at codes here: http://p2p.wrox.com/book-professional-android-4-application-development/93177-content-provider-loadermanager.html

    • What exactly is too slow? Your content provider? The time until your callback is called? The swapCursor() execution time? What time measurement are we speaking about? And how does the slowness manifest itself?

      Two things about your code:

      1.) You are calling the update() method on the main thread. You shouldn’t do that – depending on the device, the load the device is suffering from and so on, this might cause perceived lag – or even worse an ANR.

      2.) You are calling notifyDatasetChanged() on your OnClickListener but swap the Cursor with your Loader. swapCursor() is sufficient.

      • JC says:

        As you have seen the app screen, when i click plus button again and again (maybe 2 clicks per second) the count increases slow, that’s my problem.In old version, when using startManagingCursor() there wasnt lack when i click Plus or Minus button. Is there any error you have noticed in contentProvider or LoaderManger so far?

      • JC says:

        Not loaderManger sorry, Is there any error you have noticed in contentProvider or CursorLoader so far?

  15. Gödel77 says:

    JC, I have copy & pasted of API Reference
    http://developer.android.com/reference/android/app/Activity.html#startManagingCursor(android.database.Cursor)
    “void startManagingCursor(Cursor c)
    This method was deprecated in API level 11. Use the new CursorLoader class with LoaderManager instead; this is also available on older platforms through the Android compatibility package.”

    If you use CursorLoader, you need no more AsyncTask Class, so that CursorLoader is an extension of AsyncTaskLoader, as you can see in this web page.
    To better comprehesion take a look at http://www.mysamplecode.com/2012/11/android-database-content-provider.html

    You can see when and how CursorLoader works and when you are able to write Cursor-Provider Queries(*). Please modularize, you should have i.E. the initialization-Load in your main activity and in a second activity
    you can do (*) something
    Cursor = getContentResolver().query(uri, projection, null, null, null);

    • JC says:

      Cursor = getContentResolver().query(uri, projection, null, null, null);

      By using this i can get row of data from database, and iterate it over cursor, use it..

      But i dont want to get data and display it, i want to insert and update data . so i used getContentResolver().update(…) which is slow, i didnt understand the reason.

      Also i use contentProvider, so that other applications can access my database, also do CRUD operations.

  16. Rajesh says:

    Hi Wolfram

    I am using cursorLoader in my project, Whenever there is a insertion to the database the list is automatically updating and list is scrolled to top position.

    My point is how to stop to scroll the list to top when I am in the bottom of the list even there is a insertion to the database.

    Note: But the content should be update. Can you please help on this using CursorLoader.

    Thanks

    • Gödel77 says:

      Hi, have you such a line? “listView.setSelection(0)”?
      It seems, that you have write such a code line in your Methode where you update

  17. ziahaqi says:

    thanks for the awesome information :)
    i have one question..
    does loader have utility for automatic, partial load data(like data from dabatabase using limit offset)

    • No. Loaders do not support this out of the box.

      But if you are using your own content provider you could easily implement this behaviour with a specific URI. For example:

      content://yourauthority/items/from/a/to/z

      Where a is the offset value (e.g. 100) and z is the limit value (e.g. 50). Of course you would have to parse a tiny bit more, but that’s actually not that difficult.

      Only with existing providers you’re out of luck.

Leave a Reply

You can also subscribe without commenting.

Subscribe to RSS Feed My G+-Profile Follow me on Twitter!