Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * Copyright (C) 2010 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 package android.app;
 
 
Interface associated with an Activity or Fragment for managing one or more android.content.Loader instances associated with it. This helps an application manage longer-running operations in conjunction with the Activity or Fragment lifecycle; the most common use of this is with a android.content.CursorLoader, however applications are free to write their own loaders for loading other types of data. While the LoaderManager API was introduced in android.os.Build.VERSION_CODES.HONEYCOMB, a version of the API at is also available for use on older platforms through android.support.v4.app.FragmentActivity. See the blog post Fragments For All for more details.

As an example, here is the full implementation of a Fragment that displays a android.widget.ListView containing the results of a query against the contacts content provider. It uses a android.content.CursorLoader to manage the query on the provider. development/samples/ApiDemos/src/com/example/android/apis/app/LoaderCursor.java fragment_cursor

Developer Guides

For more information about using loaders, read the Loaders developer guide.

 
 public abstract class LoaderManager {
    
Callback interface for a client to interact with the manager.
 
     public interface LoaderCallbacks<D> {
        
Instantiate and return a new Loader for the given ID.

Parameters:
id The ID whose loader is to be created.
args Any arguments supplied by the caller.
Returns:
Return a new Loader instance that is ready to start loading.
 
         public Loader<D> onCreateLoader(int idBundle args);

        
Called when a previously created loader has finished its load. Note that normally an application is not allowed to commit fragment transactions while in this call, since it can happen after an activity's state is saved. See FragmentManager.openTransaction() for further discussion on this.

This function is guaranteed to be called prior to the release of the last data that was supplied for this Loader. At this point you should remove all use of the old data (since it will be released soon), but should not do your own release of the data since its Loader owns it and will take care of that. The Loader will take care of management of its data so you don't have to. In particular:

Parameters:
loader The Loader that has finished.
data The data generated by the Loader.
        public void onLoadFinished(Loader<D> loader, D data);

        
Called when a previously created loader is being reset, and thus making its data unavailable. The application should at this point remove any references it has to the Loader's data.

Parameters:
loader The Loader that is being reset.
        public void onLoaderReset(Loader<D> loader);
    }
    
    
Ensures a loader is initialized and active. If the loader doesn't already exist, one is created and (if the activity/fragment is currently started) starts the loader. Otherwise the last created loader is re-used.

In either case, the given callback is associated with the loader, and will be called as the loader state changes. If at the point of call the caller is in its started state, and the requested loader already exists and has generated its data, then callback LoaderManager.LoaderCallbacks.onLoadFinished(android.content.Loader,java.lang.Object) will be called immediately (inside of this function), so you must be prepared for this to happen.

Parameters:
id A unique identifier for this loader. Can be whatever you want. Identifiers are scoped to a particular LoaderManager instance.
args Optional arguments to supply to the loader at construction. If a loader already exists (a new one does not need to be created), this parameter will be ignored and the last arguments continue to be used.
callback Interface the LoaderManager will call to report about changes in the state of the loader. Required.
    public abstract <D> Loader<D> initLoader(int idBundle args,
            LoaderManager.LoaderCallbacks<D> callback);

    
Starts a new or restarts an existing android.content.Loader in this manager, registers the callbacks to it, and (if the activity/fragment is currently started) starts loading it. If a loader with the same id has previously been started it will automatically be destroyed when the new loader completes its work. The callback will be delivered before the old loader is destroyed.

Parameters:
id A unique identifier for this loader. Can be whatever you want. Identifiers are scoped to a particular LoaderManager instance.
args Optional arguments to supply to the loader at construction.
callback Interface the LoaderManager will call to report about changes in the state of the loader. Required.
    public abstract <D> Loader<D> restartLoader(int idBundle args,
            LoaderManager.LoaderCallbacks<D> callback);

    
Stops and removes the loader with the given ID. If this loader had previously reported data to the client through LoaderManager.LoaderCallbacks.onLoadFinished(android.content.Loader,java.lang.Object), a call will be made to LoaderManager.LoaderCallbacks.onLoaderReset(android.content.Loader).
    public abstract void destroyLoader(int id);

    
Return the Loader with the given id or null if no matching Loader is found.
    public abstract <D> Loader<D> getLoader(int id);

    
Print the LoaderManager's state into the given stream.

Parameters:
prefix Text to print at the front of each line.
fd The raw file descriptor that the dump is being sent to.
writer A PrintWriter to which the dump is to be set.
args Additional arguments to the dump request.
    public abstract void dump(String prefixFileDescriptor fdPrintWriter writerString[] args);

    
Control whether the framework's internal loader manager debugging logs are turned on. If enabled, you will see output in logcat as the framework performs loader operations.
    public static void enableDebugLogging(boolean enabled) {
        . = enabled;
    }
    static final String TAG = "LoaderManager";
    static boolean DEBUG = false;
    // These are the currently active loaders.  A loader is here
    // from the time its load is started until it has been explicitly
    // stopped or restarted by the application.
    // These are previously run loaders.  This list is maintained internally
    // to avoid destroying a loader while an application is still using it.
    // It allows an application to restart a loader, but continue using its
    // previously run loader until the new loader's data is available.
    boolean mStarted;
    boolean mRetaining;
    boolean mRetainingStarted;
    
    boolean mCreatingLoader;
    final class LoaderInfo implements Loader.OnLoadCompleteListener<Object> {
        final int mId;
        final Bundle mArgs;
        Loader<ObjectmLoader;
        boolean mHaveData;
        boolean mDeliveredData;
        Object mData;
        boolean mStarted;
        boolean mRetaining;
        boolean mRetainingStarted;
        boolean mReportNextStart;
        boolean mDestroyed;
        boolean mListenerRegistered;
        LoaderInfo mPendingLoader;
        
        public LoaderInfo(int idBundle argsLoaderManager.LoaderCallbacks<Objectcallbacks) {
             = id;
             = args;
             = callbacks;
        }
        
        void start() {
            if ( && ) {
                // Our owner is started, but we were being retained from a
                // previous instance in the started state...  so there is really
                // nothing to do here, since the loaders are still started.
                 = true;
                return;
            }
            if () {
                // If loader already started, don't restart.
                return;
            }
             = true;
            
            if () Log.v("  Starting: " + this);
            if ( == null &&  != null) {
                = .onCreateLoader();
            }
            if ( != null) {
                if (.getClass().isMemberClass()
                        && !Modifier.isStatic(.getClass().getModifiers())) {
                    throw new IllegalArgumentException(
                            "Object returned from onCreateLoader must not be a non-static inner member class: "
                            + );
                }
                if (!) {
                    .registerListener(this);
                     = true;
                }
                .startLoading();
            }
        }
        
        void retain() {
            if () Log.v("  Retaining: " + this);
             = true;
             = ;
             = false;
             = null;
        }
        
        void finishRetain() {
            if () {
                if () Log.v("  Finished Retaining: " + this);
                 = false;
                if ( != ) {
                    if (!) {
                        // This loader was retained in a started state, but
                        // at the end of retaining everything our owner is
                        // no longer started...  so make it stop.
                        stop();
                    }
                }
            }
            if ( &&  && !) {
                // This loader has retained its data, either completely across
                // a configuration change or just whatever the last data set
                // was after being restarted from a stop, and now at the point of
                // finishing the retain we find we remain started, have
                // our data, and the owner has a new callback...  so
                // let's deliver the data now.
                callOnLoadFinished();
            }
        }
        
        void reportStart() {
            if () {
                if () {
                     = false;
                    if () {
                        callOnLoadFinished();
                    }
                }
            }
        }
        void stop() {
            if () Log.v("  Stopping: " + this);
             = false;
            if (!) {
                if ( != null && ) {
                    // Let the loader know we're done with it
                     = false;
                    .unregisterListener(this);
                    .stopLoading();
                }
            }
        }
        
        void destroy() {
            if () Log.v("  Destroying: " + this);
             = true;
            boolean needReset = ;
             = false;
            if ( != null &&  != null &&  && needReset) {
                if () Log.v("  Reseting: " + this);
                String lastBecause = null;
                if ( != null) {
                    lastBecause = ..;
                    .. = "onLoaderReset";
                }
                try {
                    .onLoaderReset();
                } finally {
                    if ( != null) {
                        .. = lastBecause;
                    }
                }
            }
             = null;
             = null;
             = false;
            if ( != null) {
                if () {
                     = false;
                    .unregisterListener(this);
                }
                .reset();
            }
            if ( != null) {
                .destroy();
            }
        }
        
        @Override public void onLoadComplete(Loader<ObjectloaderObject data) {
            if () Log.v("onLoadComplete: " + this);
            
            if () {
                if () Log.v("  Ignoring load complete -- destroyed");
                return;
            }
            if (.get() != this) {
                // This data is not coming from the current active loader.
                // We don't care about it.
                if () Log.v("  Ignoring load complete -- not active");
                return;
            }
            
            LoaderInfo pending = ;
            if (pending != null) {
                // There is a new request pending and we were just
                // waiting for the old one to complete before starting
                // it.  So now it is time, switch over to the new loader.
                if () Log.v("  Switching to pending loader: " + pending);
                 = null;
                .put(null);
                destroy();
                installLoader(pending);
                return;
            }
            
            // Notify of the new data so the app can switch out the old data before
            // we try to destroy it.
            if ( != data || !) {
                 = data;
                 = true;
                if () {
                    callOnLoadFinished(loaderdata);
                }
            }
            //if (DEBUG) Log.v(TAG, "  onLoadFinished returned: " + this);
            // We have now given the application the new loader with its
            // loaded data, so it should have stopped using the previous
            // loader.  If there is a previous loader on the inactive list,
            // clean it up.
            LoaderInfo info = .get();
            if (info != null && info != this) {
                info.mDeliveredData = false;
                info.destroy();
                .remove();
            }
            if ( != null && !hasRunningLoaders()) {
                ..startPendingDeferredFragments();
            }
        }
        void callOnLoadFinished(Loader<ObjectloaderObject data) {
            if ( != null) {
                String lastBecause = null;
                if ( != null) {
                    lastBecause = ..;
                    .. = "onLoadFinished";
                }
                try {
                    if () Log.v("  onLoadFinished in " + loader + ": "
                            + loader.dataToString(data));
                    .onLoadFinished(loaderdata);
                } finally {
                    if ( != null) {
                        .. = lastBecause;
                    }
                }
                 = true;
            }
        }
        
        @Override
        public String toString() {
            StringBuilder sb = new StringBuilder(64);
            sb.append("LoaderInfo{");
            sb.append(Integer.toHexString(System.identityHashCode(this)));
            sb.append(" #");
            sb.append();
            sb.append(" : ");
            DebugUtils.buildShortClassTag(sb);
            sb.append("}}");
            return sb.toString();
        }
        public void dump(String prefixFileDescriptor fdPrintWriter writerString[] args) {
            writer.print(prefix); writer.print("mId="); writer.print();
                    writer.print(" mArgs="); writer.println();
            writer.print(prefix); writer.print("mCallbacks="); writer.println();
            writer.print(prefix); writer.print("mLoader="); writer.println();
            if ( != null) {
                .dump(prefix + "  "fdwriterargs);
            }
            if ( || ) {
                writer.print(prefix); writer.print("mHaveData="); writer.print();
                        writer.print("  mDeliveredData="); writer.println();
                writer.print(prefix); writer.print("mData="); writer.println();
            }
            writer.print(prefix); writer.print("mStarted="); writer.print();
                    writer.print(" mReportNextStart="); writer.print();
                    writer.print(" mDestroyed="); writer.println();
            writer.print(prefix); writer.print("mRetaining="); writer.print();
                    writer.print(" mRetainingStarted="); writer.print();
                    writer.print(" mListenerRegistered="); writer.println();
            if ( != null) {
                writer.print(prefix); writer.println("Pending Loader ");
                        writer.print(); writer.println(":");
                .dump(prefix + "  "fdwriterargs);
            }
        }
    }
    
    LoaderManagerImpl(Activity activityboolean started) {
         = activity;
         = started;
    }
    
    void updateActivity(Activity activity) {
         = activity;
    }
    
    private LoaderInfo createLoader(int idBundle args,
            LoaderManager.LoaderCallbacks<Objectcallback) {
        LoaderInfo info = new LoaderInfo(idargs,  (LoaderManager.LoaderCallbacks<Object>)callback);
        Loader<Objectloader = callback.onCreateLoader(idargs);
        info.mLoader = (Loader<Object>)loader;
        return info;
    }
    
    private LoaderInfo createAndInstallLoader(int idBundle args,
            LoaderManager.LoaderCallbacks<Objectcallback) {
        try {
             = true;
            LoaderInfo info = createLoader(idargscallback);
            installLoader(info);
            return info;
        } finally {
             = false;
        }
    }
    
    void installLoader(LoaderInfo info) {
        .put(info.mIdinfo);
        if () {
            // The activity will start all existing loaders in it's onStart(),
            // so only start them here if we're past that point of the activitiy's
            // life cycle
            info.start();
        }
    }
    
    
Call to initialize a particular ID with a Loader. If this ID already has a Loader associated with it, it is left unchanged and any previous callbacks replaced with the newly provided ones. If there is not currently a Loader for the ID, a new one is created and started.

This function should generally be used when a component is initializing, to ensure that a Loader it relies on is created. This allows it to re-use an existing Loader's data if there already is one, so that for example when an Activity is re-created after a configuration change it does not need to re-create its loaders.

Note that in the case where an existing Loader is re-used, the args given here will be ignored because you will continue using the previous Loader.

Parameters:
id A unique (to this LoaderManager instance) identifier under which to manage the new Loader.
args Optional arguments that will be propagated to LoaderCallbacks.onCreateLoader().
callback Interface implementing management of this Loader. Required. Its onCreateLoader() method will be called while inside of the function to instantiate the Loader object.
    @SuppressWarnings("unchecked")
    public <D> Loader<D> initLoader(int idBundle argsLoaderManager.LoaderCallbacks<D> callback) {
        if () {
            throw new IllegalStateException("Called while creating a loader");
        }
        
        LoaderInfo info = .get(id);
        
        if () Log.v("initLoader in " + this + ": args=" + args);
        if (info == null) {
            // Loader doesn't already exist; create.
            info = createAndInstallLoader(idargs,  (LoaderManager.LoaderCallbacks<Object>)callback);
            if () Log.v("  Created new loader " + info);
        } else {
            if () Log.v("  Re-using existing loader " + info);
            info.mCallbacks = (LoaderManager.LoaderCallbacks<Object>)callback;
        }
        
        if (info.mHaveData && ) {
            // If the loader has already generated its data, report it now.
            info.callOnLoadFinished(info.mLoaderinfo.mData);
        }
        
        return (Loader<D>)info.mLoader;
    }
    
    
Call to re-create the Loader associated with a particular ID. If there is currently a Loader associated with this ID, it will be canceled/stopped/destroyed as appropriate. A new Loader with the given arguments will be created and its data delivered to you once available.

This function does some throttling of Loaders. If too many Loaders have been created for the given ID but not yet generated their data, new calls to this function will create and return a new Loader but not actually start it until some previous loaders have completed.

After calling this function, any previous Loaders associated with this ID will be considered invalid, and you will receive no further data updates from them.

Parameters:
id A unique (to this LoaderManager instance) identifier under which to manage the new Loader.
args Optional arguments that will be propagated to LoaderCallbacks.onCreateLoader().
callback Interface implementing management of this Loader. Required. Its onCreateLoader() method will be called while inside of the function to instantiate the Loader object.
    @SuppressWarnings("unchecked")
    public <D> Loader<D> restartLoader(int idBundle argsLoaderManager.LoaderCallbacks<D> callback) {
        if () {
            throw new IllegalStateException("Called while creating a loader");
        }
        
        LoaderInfo info = .get(id);
        if () Log.v("restartLoader in " + this + ": args=" + args);
        if (info != null) {
            LoaderInfo inactive = .get(id);
            if (inactive != null) {
                if (info.mHaveData) {
                    // This loader now has data...  we are probably being
                    // called from within onLoadComplete, where we haven't
                    // yet destroyed the last inactive loader.  So just do
                    // that now.
                    if () Log.v("  Removing last inactive loader: " + info);
                    inactive.mDeliveredData = false;
                    inactive.destroy();
                    info.mLoader.abandon();
                    .put(idinfo);
                } else {
                    // We already have an inactive loader for this ID that we are
                    // waiting for!  What to do, what to do...
                    if (!info.mStarted) {
                        // The current Loader has not been started...  we thus
                        // have no reason to keep it around, so bam, slam,
                        // thank-you-ma'am.
                        if () Log.v("  Current loader is stopped; replacing");
                        .put(idnull);
                        info.destroy();
                    } else {
                        // Now we have three active loaders... we'll queue
                        // up this request to be processed once one of the other loaders
                        // finishes.
                        if (info.mPendingLoader != null) {
                            if () Log.v("  Removing pending loader: " + info.mPendingLoader);
                            info.mPendingLoader.destroy();
                            info.mPendingLoader = null;
                        }
                        if () Log.v("  Enqueuing as new pending loader");
                        info.mPendingLoader = createLoader(idargs
                                (LoaderManager.LoaderCallbacks<Object>)callback);
                        return (Loader<D>)info.mPendingLoader.mLoader;
                    }
                }
            } else {
                // Keep track of the previous instance of this loader so we can destroy
                // it when the new one completes.
                if () Log.v("  Making last loader inactive: " + info);
                info.mLoader.abandon();
                .put(idinfo);
            }
        }
        
        info = createAndInstallLoader(idargs,  (LoaderManager.LoaderCallbacks<Object>)callback);
        return (Loader<D>)info.mLoader;
    }
    
    
Rip down, tear apart, shred to pieces a current Loader ID. After returning from this function, any Loader objects associated with this ID are destroyed. Any data associated with them is destroyed. You better not be using it when you do this.

Parameters:
id Identifier of the Loader to be destroyed.
    public void destroyLoader(int id) {
        if () {
            throw new IllegalStateException("Called while creating a loader");
        }
        
        if () Log.v("destroyLoader in " + this + " of " + id);
        int idx = .indexOfKey(id);
        if (idx >= 0) {
            LoaderInfo info = .valueAt(idx);
            .removeAt(idx);
            info.destroy();
        }
        idx = .indexOfKey(id);
        if (idx >= 0) {
            LoaderInfo info = .valueAt(idx);
            .removeAt(idx);
            info.destroy();
        }
        if ( != null && !hasRunningLoaders()) {
        }
    }

    
Return the most recent Loader object associated with the given ID.
    @SuppressWarnings("unchecked")
    public <D> Loader<D> getLoader(int id) {
        if () {
            throw new IllegalStateException("Called while creating a loader");
        }
        
        LoaderInfo loaderInfo = .get(id);
        if (loaderInfo != null) {
            if (loaderInfo.mPendingLoader != null) {
                return (Loader<D>)loaderInfo.mPendingLoader.mLoader;
            }
            return (Loader<D>)loaderInfo.mLoader;
        }
        return null;
    }
 
    void doStart() {
        if () Log.v("Starting in " + this);
        if () {
            RuntimeException e = new RuntimeException("here");
            e.fillInStackTrace();
            Log.w("Called doStart when already started: " + thise);
            return;
        }
        
         = true;
        // Call out to sub classes so they can start their loaders
        // Let the existing loaders know that we want to be notified when a load is complete
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i).start();
        }
    }
    
    void doStop() {
        if () Log.v("Stopping in " + this);
        if (!) {
            RuntimeException e = new RuntimeException("here");
            e.fillInStackTrace();
            Log.w("Called doStop when not started: " + thise);
            return;
        }
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i).stop();
        }
         = false;
    }
    
    void doRetain() {
        if () Log.v("Retaining in " + this);
        if (!) {
            RuntimeException e = new RuntimeException("here");
            e.fillInStackTrace();
            Log.w("Called doRetain when not started: " + thise);
            return;
        }
         = true;
         = false;
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i).retain();
        }
    }
    
    void finishRetain() {
        if () {
            if () Log.v("Finished Retaining in " + this);
             = false;
            for (int i = .size()-1; i >= 0; i--) {
                .valueAt(i).finishRetain();
            }
        }
    }
    
    void doReportNextStart() {
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i). = true;
        }
    }
    void doReportStart() {
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i).reportStart();
        }
    }
    void doDestroy() {
        if (!) {
            if () Log.v("Destroying Active in " + this);
            for (int i = .size()-1; i >= 0; i--) {
                .valueAt(i).destroy();
            }
        }
        
        if () Log.v("Destroying Inactive in " + this);
        for (int i = .size()-1; i >= 0; i--) {
            .valueAt(i).destroy();
        }
        .clear();
    }
    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder(128);
        sb.append("LoaderManager{");
        sb.append(Integer.toHexString(System.identityHashCode(this)));
        sb.append(" in ");
        DebugUtils.buildShortClassTag(sb);
        sb.append("}}");
        return sb.toString();
    }
    @Override
    public void dump(String prefixFileDescriptor fdPrintWriter writerString[] args) {
        if (.size() > 0) {
            writer.print(prefix); writer.println("Active Loaders:");
            String innerPrefix = prefix + "    ";
            for (int i=0; i < .size(); i++) {
                LoaderInfo li = .valueAt(i);
                writer.print(prefix); writer.print("  #"); writer.print(.keyAt(i));
                        writer.print(": "); writer.println(li.toString());
                li.dump(innerPrefixfdwriterargs);
            }
        }
        if (.size() > 0) {
            writer.print(prefix); writer.println("Inactive Loaders:");
            String innerPrefix = prefix + "    ";
            for (int i=0; i < .size(); i++) {
                LoaderInfo li = .valueAt(i);
                writer.print(prefix); writer.print("  #"); writer.print(.keyAt(i));
                        writer.print(": "); writer.println(li.toString());
                li.dump(innerPrefixfdwriterargs);
            }
        }
    }
    public boolean hasRunningLoaders() {
        boolean loadersRunning = false;
        final int count = .size();
        for (int i = 0; i < counti++) {
            final LoaderInfo li = .valueAt(i);
            loadersRunning |= li.mStarted && !li.mDeliveredData;
        }
        return loadersRunning;
    }
New to GrepCode? Check out our FAQ X