Java tutorial
/* * Copyright (C) 2007 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.database; import android.annotation.UnsupportedAppUsage; import android.net.Uri; import android.os.Handler; import android.os.UserHandle; /** * Receives call backs for changes to content. * Must be implemented by objects which are added to a {@link ContentObservable}. */ public abstract class ContentObserver { private final Object mLock = new Object(); private Transport mTransport; // guarded by mLock Handler mHandler; /** * Creates a content observer. * * @param handler The handler to run {@link #onChange} on, or null if none. */ public ContentObserver(Handler handler) { mHandler = handler; } /** * Gets access to the binder transport object. Not for public consumption. * * {@hide} */ public IContentObserver getContentObserver() { synchronized (mLock) { if (mTransport == null) { mTransport = new Transport(this); } return mTransport; } } /** * Gets access to the binder transport object, and unlinks the transport object * from the ContentObserver. Not for public consumption. * * {@hide} */ @UnsupportedAppUsage public IContentObserver releaseContentObserver() { synchronized (mLock) { final Transport oldTransport = mTransport; if (oldTransport != null) { oldTransport.releaseContentObserver(); mTransport = null; } return oldTransport; } } /** * Returns true if this observer is interested receiving self-change notifications. * * Subclasses should override this method to indicate whether the observer * is interested in receiving notifications for changes that it made to the * content itself. * * @return True if self-change notifications should be delivered to the observer. */ public boolean deliverSelfNotifications() { return false; } /** * This method is called when a content change occurs. * <p> * Subclasses should override this method to handle content changes. * </p> * * @param selfChange True if this is a self-change notification. */ public void onChange(boolean selfChange) { // Do nothing. Subclass should override. } /** * This method is called when a content change occurs. * Includes the changed content Uri when available. * <p> * Subclasses should override this method to handle content changes. * To ensure correct operation on older versions of the framework that * did not provide a Uri argument, applications should also implement * the {@link #onChange(boolean)} overload of this method whenever they * implement the {@link #onChange(boolean, Uri)} overload. * </p><p> * Example implementation: * <pre><code> * // Implement the onChange(boolean) method to delegate the change notification to * // the onChange(boolean, Uri) method to ensure correct operation on older versions * // of the framework that did not have the onChange(boolean, Uri) method. * {@literal @Override} * public void onChange(boolean selfChange) { * onChange(selfChange, null); * } * * // Implement the onChange(boolean, Uri) method to take advantage of the new Uri argument. * {@literal @Override} * public void onChange(boolean selfChange, Uri uri) { * // Handle change. * } * </code></pre> * </p> * * @param selfChange True if this is a self-change notification. * @param uri The Uri of the changed content, or null if unknown. */ public void onChange(boolean selfChange, Uri uri) { onChange(selfChange); } /** * Dispatches a change notification to the observer. Includes the changed * content Uri when available and also the user whose content changed. * * @param selfChange True if this is a self-change notification. * @param uri The Uri of the changed content, or null if unknown. * @param userId The user whose content changed. Can be either a specific * user or {@link UserHandle#USER_ALL}. * * @hide */ public void onChange(boolean selfChange, Uri uri, int userId) { onChange(selfChange, uri); } /** * Dispatches a change notification to the observer. * <p> * If a {@link Handler} was supplied to the {@link ContentObserver} constructor, * then a call to the {@link #onChange} method is posted to the handler's message queue. * Otherwise, the {@link #onChange} method is invoked immediately on this thread. * </p> * * @param selfChange True if this is a self-change notification. * * @deprecated Use {@link #dispatchChange(boolean, Uri)} instead. */ @Deprecated public final void dispatchChange(boolean selfChange) { dispatchChange(selfChange, null); } /** * Dispatches a change notification to the observer. * Includes the changed content Uri when available. * <p> * If a {@link Handler} was supplied to the {@link ContentObserver} constructor, * then a call to the {@link #onChange} method is posted to the handler's message queue. * Otherwise, the {@link #onChange} method is invoked immediately on this thread. * </p> * * @param selfChange True if this is a self-change notification. * @param uri The Uri of the changed content, or null if unknown. */ public final void dispatchChange(boolean selfChange, Uri uri) { dispatchChange(selfChange, uri, UserHandle.getCallingUserId()); } /** * Dispatches a change notification to the observer. Includes the changed * content Uri when available and also the user whose content changed. * <p> * If a {@link Handler} was supplied to the {@link ContentObserver} constructor, * then a call to the {@link #onChange} method is posted to the handler's message queue. * Otherwise, the {@link #onChange} method is invoked immediately on this thread. * </p> * * @param selfChange True if this is a self-change notification. * @param uri The Uri of the changed content, or null if unknown. * @param userId The user whose content changed. */ private void dispatchChange(boolean selfChange, Uri uri, int userId) { if (mHandler == null) { onChange(selfChange, uri, userId); } else { mHandler.post(new NotificationRunnable(selfChange, uri, userId)); } } private final class NotificationRunnable implements Runnable { private final boolean mSelfChange; private final Uri mUri; private final int mUserId; public NotificationRunnable(boolean selfChange, Uri uri, int userId) { mSelfChange = selfChange; mUri = uri; mUserId = userId; } @Override public void run() { ContentObserver.this.onChange(mSelfChange, mUri, mUserId); } } private static final class Transport extends IContentObserver.Stub { private ContentObserver mContentObserver; public Transport(ContentObserver contentObserver) { mContentObserver = contentObserver; } @Override public void onChange(boolean selfChange, Uri uri, int userId) { ContentObserver contentObserver = mContentObserver; if (contentObserver != null) { contentObserver.dispatchChange(selfChange, uri, userId); } } public void releaseContentObserver() { mContentObserver = null; } } }