Inform ContentObservers about the changed content Uri.

Added a new method ContentObserver.onChange(boolean, Uri) that
receives the changed content Uri.  This can help applications make
better decisions about how to interpret a change notification.

Change-Id: I8e35378b6485fe22c5bc240ba07557d269af0836

5 files changed, 104 insertions, 17 deletions

diff --git a/core/java/android/database/AbstractCursor.java b/core/java/android/database/AbstractCursor.java
index 22df272..b28ed8d 100644
--- a/core/java/android/database/AbstractCursor.java
+++ b/core/java/android/database/AbstractCursor.java
@@ -300,7 +300,7 @@ public abstract class AbstractCursor implements CrossProcessCursor {
      */
     protected void onChange(boolean selfChange) {
         synchronized (mSelfObserverLock) {
-            mContentObservable.dispatchChange(selfChange);
+            mContentObservable.dispatchChange(selfChange, null);
             if (mNotifyUri != null && selfChange) {
                 mContentResolver.notifyChange(mNotifyUri, mSelfObserver);
             }
diff --git a/core/java/android/database/ContentObservable.java b/core/java/android/database/ContentObservable.java
index aece904..7692bb3 100644
--- a/core/java/android/database/ContentObservable.java
+++ b/core/java/android/database/ContentObservable.java
@@ -16,6 +16,8 @@
 
 package android.database;
 
+import android.net.Uri;
+
 /**
  * A specialization of {@link Observable} for {@link ContentObserver}
  * that provides methods for sending notifications to a list of
@@ -31,20 +33,41 @@ public class ContentObservable extends Observable<ContentObserver> {
     }
 
     /**
-     * Invokes {@link ContentObserver#dispatchChange} on each observer.
-     *
+     * Invokes {@link ContentObserver#dispatchChange(boolean)} on each observer.
+     * <p>
      * If <code>selfChange</code> is true, only delivers the notification
      * to the observer if it has indicated that it wants to receive self-change
      * notifications by implementing {@link ContentObserver#deliverSelfNotifications}
      * to return true.
+     * </p>
      *
      * @param selfChange True if this is a self-change notification.
+     *
+     * @deprecated Use {@link #dispatchChange(boolean, Uri)} instead.
      */
+    @Deprecated
     public void dispatchChange(boolean selfChange) {
+        dispatchChange(selfChange, null);
+    }
+
+    /**
+     * Invokes {@link ContentObserver#dispatchChange(boolean, Uri)} on each observer.
+     * Includes the changed content Uri when available.
+     * <p>
+     * If <code>selfChange</code> is true, only delivers the notification
+     * to the observer if it has indicated that it wants to receive self-change
+     * notifications by implementing {@link ContentObserver#deliverSelfNotifications}
+     * to return true.
+     * </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 dispatchChange(boolean selfChange, Uri uri) {
         synchronized(mObservers) {
             for (ContentObserver observer : mObservers) {
                 if (!selfChange || observer.deliverSelfNotifications()) {
-                    observer.dispatchChange(selfChange);
+                    observer.dispatchChange(selfChange, uri);
                 }
             }
         }
@@ -61,7 +84,7 @@ public class ContentObservable extends Observable<ContentObserver> {
     public void notifyChange(boolean selfChange) {
         synchronized(mObservers) {
             for (ContentObserver observer : mObservers) {
-                observer.onChange(selfChange);
+                observer.onChange(selfChange, null);
             }
         }
     }
diff --git a/core/java/android/database/ContentObserver.java b/core/java/android/database/ContentObserver.java
index 4c20262..e4fbc28 100644
--- a/core/java/android/database/ContentObserver.java
+++ b/core/java/android/database/ContentObserver.java
@@ -16,6 +16,7 @@
 
 package android.database;
 
+import android.net.Uri;
 import android.os.Handler;
 
 /**
@@ -83,6 +84,9 @@ public abstract class ContentObserver {
 
     /**
      * 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.
      */
@@ -91,32 +95,89 @@ public abstract class ContentObserver {
     }
 
     /**
-     * Dispatches a change notification to the observer.
+     * 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.
+     * <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) {
         if (mHandler == null) {
-            onChange(selfChange);
+            onChange(selfChange, uri);
         } else {
-            mHandler.post(new NotificationRunnable(selfChange));
+            mHandler.post(new NotificationRunnable(selfChange, uri));
         }
     }
 
     private final class NotificationRunnable implements Runnable {
-        private final boolean mSelf;
+        private final boolean mSelfChange;
+        private final Uri mUri;
 
-        public NotificationRunnable(boolean self) {
-            mSelf = self;
+        public NotificationRunnable(boolean selfChange, Uri uri) {
+            mSelfChange = selfChange;
+            mUri = uri;
         }
 
         @Override
         public void run() {
-            ContentObserver.this.onChange(mSelf);
+            ContentObserver.this.onChange(mSelfChange, mUri);
         }
     }
 
@@ -128,10 +189,10 @@ public abstract class ContentObserver {
         }
 
         @Override
-        public void onChange(boolean selfChange) {
+        public void onChange(boolean selfChange, Uri uri) {
             ContentObserver contentObserver = mContentObserver;
             if (contentObserver != null) {
-                contentObserver.dispatchChange(selfChange);
+                contentObserver.dispatchChange(selfChange, uri);
             }
         }
 
diff --git a/core/java/android/database/CursorToBulkCursorAdaptor.java b/core/java/android/database/CursorToBulkCursorAdaptor.java
index aa0f61e..167278a 100644
--- a/core/java/android/database/CursorToBulkCursorAdaptor.java
+++ b/core/java/android/database/CursorToBulkCursorAdaptor.java
@@ -16,6 +16,7 @@
 
 package android.database;
 
+import android.net.Uri;
 import android.os.Bundle;
 import android.os.IBinder;
 import android.os.RemoteException;
@@ -78,9 +79,9 @@ public final class CursorToBulkCursorAdaptor extends BulkCursorNative
         }
 
         @Override
-        public void onChange(boolean selfChange) {
+        public void onChange(boolean selfChange, Uri uri) {
             try {
-                mRemote.onChange(selfChange);
+                mRemote.onChange(selfChange, uri);
             } catch (RemoteException ex) {
                 // Do nothing, the far side is dead
             }
diff --git a/core/java/android/database/IContentObserver.aidl b/core/java/android/database/IContentObserver.aidl
index ac2f975..13aff05 100755
--- a/core/java/android/database/IContentObserver.aidl
+++ b/core/java/android/database/IContentObserver.aidl
@@ -17,6 +17,8 @@
 
 package android.database;
 
+import android.net.Uri;
+
 /**
  * @hide
  */
@@ -27,5 +29,5 @@ interface IContentObserver
      * observed. selfUpdate is true if the update was caused by a call to
      * commit on the cursor that is being observed.
      */
-    oneway void onChange(boolean selfUpdate);
+    oneway void onChange(boolean selfUpdate, in Uri uri);
 }