docs/html/training/load-data-background/define-launch-query.jd

page.title=Defining and Launching the Query
trainingnavtop=true
startpage=true

@jd:body

<!-- This is the training bar -->
<div id="tb-wrapper">
  <div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
    <li>
        <a href="#DefineLaunch">Define and Launch the Query</a>
    </li>
</ol>
  </div>
</div>

<p>
    To perform a query, create the {@link android.support.v4.content.CursorLoader}, set up its
    query, and pass it to the loader framework. From then on, the framework manages everything.
    It runs the query on a background thread, returns the results to the foreground, and
    watches for changes to the data associated with the query.
</p>
<p>
    Pass a {@link android.support.v4.content.CursorLoader} to the loader framework in
    your implementation of
    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}.
    The loader framework calls this method when you <i>create</i> a loader by calling
    {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. You can create
    a {@link android.support.v4.content.CursorLoader} anywhere,
    but the preferred way is to create it in
    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()},
    because this defers creation until the object is actually needed.
</p>
<p>
    Notice that {@link android.support.v4.app.LoaderManager#initLoader initLoader()} will only
    {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}
    if the {@link android.support.v4.content.CursorLoader} doesn't already exist; otherwise, it
    re-uses the existing {@link android.support.v4.content.CursorLoader}. The loader framework
    tracks {@link android.support.v4.content.CursorLoader} instance using the <code>id</code>
    value passed to {@link android.support.v4.app.LoaderManager#initLoader initLoader()}.
</p>
<h2 id="DefineLaunch">Define and Launch the Query</h2>
<p>
    To create a {@link android.support.v4.content.CursorLoader} and define its
    query at the same time, call the constructor
{@link android.support.v4.content.CursorLoader#CursorLoader(Context, Uri, String[], String, String[], String)
    CursorLoader(context, uri, projection, selection, selectionArgs, sortOrder)}. The
    <code>context</code> and <code>uri</code> arguments are required, but the others are optional.
    To use the default value for an optional argument, pass in <code>null</code>. The
    {@link android.support.v4.content.CursorLoader} runs the query against the
    {@link android.content.ContentProvider} identified by <code>uri</code>, just as if you had
    called {@link android.content.ContentResolver#query ContentResolver.query()} with the same
    arguments.
</p>
<p>
    For example:
</p>
<pre>
public Loader&lt;Cursor&gt; onCreateLoader(int loaderID, Bundle bundle)
{
    /*
     * Takes action based on the ID of the Loader that's being created
     */
    switch (loaderID) {
        case URL_LOADER:
            /*
             * Return a new CursorLoader
             */
            return new CursorLoader(
                this,                           // Context
                DataProviderContract.IMAGE_URI, // Provider's content URI
                PROJECTION,                     // Columns to return
                null,                           // Return all rows
                null,                           // No search arguments
                null);                          // Default search order
        default:
            // An invalid id was passed in
            return null;
    }
}
</pre>