| /* |
| * 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; |
| } |
| } |
| } |