Api指南--Loaders介绍

 

Android 3.0以后才出现了loaders，在Activity或Fragment中使用时可以很容易的实现异步加载数据。Loaders有以下特点：

1）  在每一个Activity或Fragment中都可用。

2）  它们提供数据的异步加载。

3）  它们会监控源数据的变化，并且会提供变化的数据。

4）  当配置变化，需要重建Activity或者Fragment时，这些loader会自动重连游标。因此，无须你担心它们的数据连接。

 

LoaderAPI 摘要

 

在一个应用中，使用Loader时可能需要多个类及接口。它们如下表所示：

类/接口	描述
LoaderManager	与一个Activity或Fragment关联的抽象类，用来管理一个或多个Loader实例。它帮助应用在Activity或Fragment的生命周期中管理那些耗时的操作；通常与一个CursorLoader一起使用，当然了，应用也可以创建自己的loader来加载其它类型的数据。   每一个Activity或Fragment只有一个LoaderManager。但是一个LoaderManager可以拥有多个Loader。
LoaderManager.LoaderCallbacks	客户端和LoaderManager交互的回调接口。例如，你使用其中的onCreateLoader()回调方法来创建一个新的Loader。
Loader	一个抽象类，提供数据的异步加载。这是Loader的基类。通常你会使用CursorLoader，但是你也可以实现自己的子类。当Loader处于活动状态时，它会监控数据源的变化，并且传递新的数据。
AsyncTaskLoader	一个抽象Loader，内部提供一个AsyncTask来工作。
CursorLoader	AsyncTaskLoader的子类，用来查询ContentResolver，并且返回一个Cursor。这个类以标准的形式实现了Loader的特定接口来获取Cursor，基于AsyncTaskLoader在后台线程中查询Cursor，而不会引起应用UI的阻塞。如果需要从ContentProvider中加载数据，那么使用这个Loader是最好的解决方案，而无须通过Fragment或Activity的API接口执行一个查询（即不推荐使用Activity.managedQuery）。

 

上表中的类和接口是实现一个Loader的基本组成部分。你不需要上面所有的类和接口，但是你总是需要引用Activity或Fragment的LoaderManager实例，来初始化一个Loader或者一个Loader的子类如CursorLoader。下面的部分将向你展示如何在应用中使用这些类和接口。

 

在应用中使用Loader

 

这个部分描述了如何在应用中使用loader。使用时，通常会包含以下参与者：

1）  一个Activity或Fragment。

2）  一个LoaderManager实例。

3）  一个CursorLoader，加载ContentProvider的数据。可选的是，你可以实现自己的Loader或者AsyncTaskLoader子类来加载其它类型的源数据。

4）  一个LoaderManager.LoaderCallbacks实现。在这里你可以创建一个新的Loader，管理你的Loader实例。

5）  显示loader数据的途径，例如一个SimpleCursorAdapter。

6）  一个数据源，例如使用CursorLoader时，数据源就是一个ContentProvider。

 

启动一个Loader

 

在一个Activity或Fragment中，LoaderManager来管理一到多个Loader实例。每一个Activity或Fragment中只有一个LoaderManager。

 

你通常会在Activity的onCreate()方法中或者Fragment中的onActivityCreated()方法中初始化一个Loader。如下所示：

/ Prepare the loader.  Either re-connect with an existing one,
// or start a new one.
getLoaderManager().initLoader(0, null, this);

 

上面的initLoader方法包含如下参数：

1）  一个用来识别loader的ID。本例中ID为0。

2）  可选参数，在LoaderManager.LoaderCallbacks的回调方法中onCreateLoader(int id, Bundle args)，作为第2个参数传递进来。本例是null。

3）  一个LoaderManager.LoaderCallbacks实现，LoaderManager通过此来通知loader事件。在本例中，当前类实现了LoaderManager.LoaderCallbacks接口，所以传递了this。

 

initLoader()方法调用确保一个loader被初始化，并处于活动状态。调用会产生两种可能结果：

1）  如果ID标记的Loader已经存在，那么会重用已存在的loader，而不会重建。

2）  如果ID标记的Loader不存在，那么initLoader()方法会引起LoaderManager.LoaderCallbacks的方法onCreateLoader()被调用。在这里你可以实现自己的代码来初始化和返回一个新的Loader。

 

如果在调用initLoader方法时，已存在的loader已经加载完数据，那么onLoadFinished()会被立即调用(initLoader()返回前)，所以你必须认识到这一点。

 

注意到initLoader()方法返回你创建的Loader，但是你不需要保存这些Loader引用。LoaderManager会自动管理这些loader的生命周期。LoaderManager会在必要的时候启动和停止数据加载，管理和维护Loader的状态和相关内容。因此，你很少会与loader直接交互（但是LoaderThrottle例子程序稍有例外。）你大多数情况下只需使用LoaderManager.LoaderCallbacks的回调方法来参与数据的加载过程。

 

重启一个Loader

 

如果所示，当你调用initLoader()时，如果ID标记的loader已经存在的话，就会使用这个已存在的loader。如果没有的话，就会创建一个。但是有些时候，你也许想丢弃旧的数据，重新启动。

 

为了丢弃旧数据，你可以调用restartLoader()。例如，在下面的SearchView.OnQueryTextListener方法中，当用户修改查询数据时，就会重启loader。这种情况下需要重启loader，因为需要根据用户的新的输入来启动不同的新的查询：

public boolean onQueryTextChanged(String newText) {
    // Called when the action bar search text has changed.  Update
    // the search filter, and restart the loader to do a new query
    // with this filter.
    mCurFilter = !TextUtils.isEmpty(newText) ? newText : null;
    getLoaderManager().restartLoader(0, null, this);
    return true;
}

 

使用LoaderManager回调

 

LoaderManager.LoaderCallbacks是一个回调接口，允许客户端和LoaderManager交互。

 

Loader，尤其是CursorLoader，在被停止以后，是可以继续保留他们的数据的。这样应用在Activity或者Fragment的onStop()和onStart()之间的生命周期内可以保留他们的数据，这样当用户返回应用的时候，就不需要因为重新加载数据而等待。你通过LoaderManager.LoaderCallbacks回调方法，就可以知道什么时候创建一个新的loader，什么时候告诉应用停止使用loader数据。

 

LoaderManager.LoaderCallbacks包含以下这些方法：

1）  onCreateLoader()  -- 初始化，并返回一个对应ID的新的Loader。

2）  onLoadFinished() – 当之前创建的loader加载完成的时候调用。

3）  onLoaderReset() – 当之前创建的loader被重置的时候调用，然后使数据不可用。

 

这些方法会在下面详解。

 

onCreateLoader

 

当你想使用一个loader的时候（例如，调用initLoader()），LoaderManager会查看ID标记的loader是否存在。如果不存在，就会调用LoaderManager.LoaderCallbacks的方法onCreateLoader()。在这个方法中你可以创建一个新的loader。通常情况下，你可以返回一个CursorLoader，但是你也可以返回你自己的Loader子类。

 

在本例中，onCreateLoader()回调方法创建了一个CursorLoader。你必须通过CursorLoader的构造方法来创建它，这个构造方法需要完整的可以查询一个ContentProvider的信息。通常需要以下信息：

Uri – 查询的URI地址。

projection – 指定查询结果返回的列有哪些。传递null表示返回所有的列，这是比较低效的。

selection – 指定返回哪些结果行，请使用SQLWHERE子句的形式(不包含WHERE)。传递null表示返回所有行。

selectionArgs – 在selection中也许包含?，那么这些值会被selectionArgs中的值依次替代。这些值应当是String类型的。

sortOrder – 如何排序结果行，请使用SQL ORDERBY语句形式(不包含 ORDER BY)。传递null表示使用默认排序，也意味着可能是无序的。

 

例如：

 // If non-null, this is the current filter the user has provided.
String mCurFilter;
...
public Loader<Cursor> onCreateLoader(int id, Bundle args) {
    // This is called when a new Loader needs to be created.  This
    // sample only has one Loader, so we don't care about the ID.
    // First, pick the base URI to use depending on whether we are
    // currently filtering.
    Uri baseUri;
    if (mCurFilter != null) {
        baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI,
                  Uri.encode(mCurFilter));
    } else {
        baseUri = Contacts.CONTENT_URI;
    }

    // Now create and return a CursorLoader that will take care of
    // creating a Cursor for the data being displayed.
    String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND ("
            + Contacts.HAS_PHONE_NUMBER + "=1) AND ("
            + Contacts.DISPLAY_NAME + " != '' ))";
    return new CursorLoader(getActivity(), baseUri,
            CONTACTS_SUMMARY_PROJECTION, select, null,
            Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC");
}

 

onLoadFinished

 

当之前创建的loader加载完数据的时候调用。此方法保证在释放上一组旧数据之前调用。也就是说，此时你应当停止对旧有的数据的使用（因为这些数据马上就要被释放），但是你不应该自己释放这些旧数据，它们是由Loader自己管理的。

 

Loader一旦知道应用不再使用它的数据的时候，它就会释放这些数据。例如，假设数据是一个从CursorLoader返回的cursor，那么你不应该自己调用cursor.close()。如果这些cursor被放置在CursorAdapter中，那么你应该使用swapCursor()方法，这样旧的cursor就会被关闭了。例如：

 

// This is the Adapter being used to display the list's data.
SimpleCursorAdapter mAdapter;
...

public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
    // Swap the new cursor in.  (The framework will take care of closing the
    // old cursor once we return.)
    mAdapter.swapCursor(data);
}

 

onLoaderReset

 

当之前创建的Loader被重置的时候调用，因此需要把数据置为不可用状态。这个回调告诉你什么时候这些数据要被释放，因此你应该此时移除对这些对象的引用。

 

如下实现调用swapCursor(null)：

 

// This is the Adapter being used to display the list's data.
SimpleCursorAdapter mAdapter;
...

public void onLoaderReset(Loader<Cursor> loader) {
    // This is called when the last Cursor provided to onLoadFinished()
    // above is about to be closed.  We need to make sure we are no
    // longer using it.
    mAdapter.swapCursor(null);
}

示例

 

作为例子，这里是一个Fragment的完全实现，它使用一个ListView显示了对联系人的内容查询的结果。它使用了一个CursorLoader来管理对provider的查询。

 

为了能够像本例查询联系人的信息，应用需要在配置文件中声明权限READ_CONTACTS。

 

public static class CursorLoaderListFragment extends ListFragment
        implements OnQueryTextListener, LoaderManager.LoaderCallbacks<Cursor> {

    // This is the Adapter being used to display the list's data.
    SimpleCursorAdapter mAdapter;

    // If non-null, this is the current filter the user has provided.
    String mCurFilter;

    @Override public void onActivityCreated(Bundle savedInstanceState) {
        super.onActivityCreated(savedInstanceState);

        // Give some text to display if there is no data.  In a real
        // application this would come from a resource.
        setEmptyText("No phone numbers");

        // We have a menu item to show in action bar.
        setHasOptionsMenu(true);

        // Create an empty adapter we will use to display the loaded data.
        mAdapter = new SimpleCursorAdapter(getActivity(),
                android.R.layout.simple_list_item_2, null,
                new String[] { Contacts.DISPLAY_NAME, Contacts.CONTACT_STATUS },
                new int[] { android.R.id.text1, android.R.id.text2 }, 0);
        setListAdapter(mAdapter);

        // Prepare the loader.  Either re-connect with an existing one,
        // or start a new one.
        getLoaderManager().initLoader(0, null, this);
    }

    @Override public void onCreateOptionsMenu(Menu menu, MenuInflater inflater) {
        // Place an action bar item for searching.
        MenuItem item = menu.add("Search");
        item.setIcon(android.R.drawable.ic_menu_search);
        item.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
        SearchView sv = new SearchView(getActivity());
        sv.setOnQueryTextListener(this);
        item.setActionView(sv);
    }

    public boolean onQueryTextChange(String newText) {
        // Called when the action bar search text has changed.  Update
        // the search filter, and restart the loader to do a new query
        // with this filter.
        mCurFilter = !TextUtils.isEmpty(newText) ? newText : null;
        getLoaderManager().restartLoader(0, null, this);
        return true;
    }

    @Override public boolean onQueryTextSubmit(String query) {
        // Don't care about this.
        return true;
    }

    @Override public void onListItemClick(ListView l, View v, int position, long id) {
        // Insert desired behavior here.
        Log.i("FragmentComplexList", "Item clicked: " + id);
    }

    // These are the Contacts rows that we will retrieve.
    static final String[] CONTACTS_SUMMARY_PROJECTION = new String[] {
        Contacts._ID,
        Contacts.DISPLAY_NAME,
        Contacts.CONTACT_STATUS,
        Contacts.CONTACT_PRESENCE,
        Contacts.PHOTO_ID,
        Contacts.LOOKUP_KEY,
    };
    public Loader<Cursor> onCreateLoader(int id, Bundle args) {
        // This is called when a new Loader needs to be created.  This
        // sample only has one Loader, so we don't care about the ID.
        // First, pick the base URI to use depending on whether we are
        // currently filtering.
        Uri baseUri;
        if (mCurFilter != null) {
            baseUri = Uri.withAppendedPath(Contacts.CONTENT_FILTER_URI,
                    Uri.encode(mCurFilter));
        } else {
            baseUri = Contacts.CONTENT_URI;
        }

        // Now create and return a CursorLoader that will take care of
        // creating a Cursor for the data being displayed.
        String select = "((" + Contacts.DISPLAY_NAME + " NOTNULL) AND ("
                + Contacts.HAS_PHONE_NUMBER + "=1) AND ("
                + Contacts.DISPLAY_NAME + " != '' ))";
        return new CursorLoader(getActivity(), baseUri,
                CONTACTS_SUMMARY_PROJECTION, select, null,
                Contacts.DISPLAY_NAME + " COLLATE LOCALIZED ASC");
    }

    public void onLoadFinished(Loader<Cursor> loader, Cursor data) {
        // Swap the new cursor in.  (The framework will take care of closing the
        // old cursor once we return.)
        mAdapter.swapCursor(data);
    }

    public void onLoaderReset(Loader<Cursor> loader) {
        // This is called when the last Cursor provided to onLoadFinished()
        // above is about to be closed.  We need to make sure we are no
        // longer using it.
        mAdapter.swapCursor(null);
    }
}

更多例子

 

在ApiDemos中包含了几个演示如何使用loader的例子：

LoaderCursor – 上面所示代码片段的完整版本。

LoaderThrottle – 演示了当数据发生变化的时候，如何减少在content provider上的查询次数。