android-35/android/database/ContentObserver.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * 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.NonNull;
 import android.annotation.Nullable;
 import android.annotation.SystemApi;
 import android.annotation.UserIdInt;
 import android.app.compat.CompatChanges;
 import android.compat.annotation.ChangeId;
 import android.compat.annotation.EnabledAfter;
 import android.compat.annotation.UnsupportedAppUsage;
 import android.content.ContentResolver.NotifyFlags;
 import android.net.Uri;
 import android.os.Handler;
 import android.os.UserHandle;

 import java.util.Arrays;
 import java.util.Collection;
 import java.util.concurrent.Executor;

 /**
  * Receives call backs for changes to content.
  * Must be implemented by objects which are added to a {@link ContentObservable}.
  */
 @android.ravenwood.annotation.RavenwoodKeepWholeClass
 public abstract class ContentObserver {
     /**
      * Starting in {@link android.os.Build.VERSION_CODES#R}, there is a new
      * public API overload {@link #onChange(boolean, Uri, int)} that delivers a
      * {@code int flags} argument.
      * <p>
      * Some apps may be relying on a previous hidden API that delivered a
      * {@code int userId} argument, and this change is used to control delivery
      * of the new {@code int flags} argument in its place.
      */
     @ChangeId
     @EnabledAfter(targetSdkVersion=android.os.Build.VERSION_CODES.Q)
     private static final long ADD_CONTENT_OBSERVER_FLAGS = 150939131L;
     private final Object mLock = new Object();
     private Transport mTransport; // guarded by mLock

     Handler mHandler;
     private final Executor mExecutor;

     /**
      * Creates a content observer.
      *
      * @param handler The handler to run {@link #onChange} on, or null if none.
      */
     public ContentObserver(Handler handler) {
         mHandler = handler;
         mExecutor = null;
     }

     /**
      * @hide
      * Creates a content observer with an executor.
      *
      * @param executor The executor to run {@link #onChange} on, or null if none.
      * @param unused a second argument to avoid source incompatibility.
      */
     public ContentObserver(@Nullable Executor executor, int unused) {
         mExecutor = executor;
     }

     /**
      * 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 richer arguments, applications should implement all overloads.
      * <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.
      */
     public void onChange(boolean selfChange, @Nullable Uri uri) {
         onChange(selfChange);
     }

     /**
      * 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 richer arguments, applications should implement all overloads.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uri The Uri of the changed content.
      * @param flags Flags indicating details about this change.
      */
     public void onChange(boolean selfChange, @Nullable Uri uri, @NotifyFlags int flags) {
         onChange(selfChange, uri);
     }

     /**
      * This method is called when a content change occurs. Includes the changed
      * content Uris 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 richer arguments, applications should implement all overloads.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uris The Uris of the changed content.
      * @param flags Flags indicating details about this change.
      */
     public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
             @NotifyFlags int flags) {
         for (Uri uri : uris) {
             onChange(selfChange, uri, flags);
         }
     }

     /**
      * This method is called when a content change occurs. Includes the changed
      * content Uris 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 richer arguments, applications should implement all overloads.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uris The Uris of the changed content.
      * @param flags Flags indicating details about this change.
      * @param user The corresponding {@link UserHandle} for the current notification.
      *
      * @hide
      */
     @SystemApi
     public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
             @NotifyFlags int flags, @NonNull UserHandle user) {
         onChange(selfChange, uris, user.getIdentifier());
     }

     /** @hide */
     public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
             @NotifyFlags int flags, @UserIdInt int userId) {
         // There are dozens of people relying on the hidden API inside the
         // system UID, so hard-code the old behavior for all of them; for
         // everyone else we gate based on a specific change
         if (!isChangeEnabledAddContentObserverFlags()
                 || android.os.Process.myUid() == android.os.Process.SYSTEM_UID) {
             // Deliver userId through argument to preserve hidden API behavior
             onChange(selfChange, uris, flags, UserHandle.of(userId));
         } else {
             onChange(selfChange, uris, flags);
         }
     }

     @android.ravenwood.annotation.RavenwoodReplace
     private static boolean isChangeEnabledAddContentObserverFlags() {
         return CompatChanges.isChangeEnabled(ADD_CONTENT_OBSERVER_FLAGS);
     }

     private static boolean isChangeEnabledAddContentObserverFlags$ravenwood() {
         return true;
     }

     /**
      * 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.
      *
      * @deprecated Callers should migrate towards using a richer overload that
      *             provides more details about the change, such as
      *             {@link #dispatchChange(boolean, Collection, int)}.
      */
     @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.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uri The Uri of the changed content.
      */
     public final void dispatchChange(boolean selfChange, @Nullable Uri uri) {
         dispatchChange(selfChange, uri, 0);
     }

     /**
      * 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.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uri The Uri of the changed content.
      * @param flags Flags indicating details about this change.
      */
     public final void dispatchChange(boolean selfChange, @Nullable Uri uri,
             @NotifyFlags int flags) {
         dispatchChange(selfChange, Arrays.asList(uri), flags);
     }

     /**
      * Dispatches a change notification to the observer. Includes the changed
      * content Uris 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.
      *
      * @param selfChange True if this is a self-change notification.
      * @param uris The Uri of the changed content.
      * @param flags Flags indicating details about this change.
      */
     public final void dispatchChange(boolean selfChange, @NonNull Collection<Uri> uris,
             @NotifyFlags int flags) {
         dispatchChange(selfChange, uris, flags, UserHandle.getCallingUserId());
     }

     /** @hide */
     public final void dispatchChange(boolean selfChange, @NonNull Collection<Uri> uris,
             @NotifyFlags int flags, @UserIdInt int userId) {
         if (mExecutor != null) {
             mExecutor.execute(() -> {
                 onChange(selfChange, uris, flags, userId);
             });
         } else if (mHandler != null) {
             // Supporting Handler directly rather than wrapping in a HandlerExecutor
             //  avoids introducing a RejectedExecutionException for legacy code when
             //  the post fails.
             mHandler.post(() -> {
                 onChange(selfChange, uris, flags, userId);
             });
         } else {
             onChange(selfChange, uris, flags, userId);
         }
     }

     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) {
             // This is kept intact purely for apps using hidden APIs, to
             // redirect to the updated implementation
             onChangeEtc(selfChange, new Uri[] { uri }, 0, userId);
         }

         @Override
         public void onChangeEtc(boolean selfChange, Uri[] uris, int flags, int userId) {
             ContentObserver contentObserver = mContentObserver;
             if (contentObserver != null) {
                 contentObserver.dispatchChange(selfChange, Arrays.asList(uris), flags, userId);
             }
         }

         public void releaseContentObserver() {
             mContentObserver = null;
         }
     }
 }
	/*
	* 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.NonNull;
	import android.annotation.Nullable;
	import android.annotation.SystemApi;
	import android.annotation.UserIdInt;
	import android.app.compat.CompatChanges;
	import android.compat.annotation.ChangeId;
	import android.compat.annotation.EnabledAfter;
	import android.compat.annotation.UnsupportedAppUsage;
	import android.content.ContentResolver.NotifyFlags;
	import android.net.Uri;
	import android.os.Handler;
	import android.os.UserHandle;

	import java.util.Arrays;
	import java.util.Collection;
	import java.util.concurrent.Executor;

	/**
	* Receives call backs for changes to content.
	* Must be implemented by objects which are added to a {@link ContentObservable}.
	*/
	@android.ravenwood.annotation.RavenwoodKeepWholeClass
	public abstract class ContentObserver {
	/**
	* Starting in {@link android.os.Build.VERSION_CODES#R}, there is a new
	* public API overload {@link #onChange(boolean, Uri, int)} that delivers a
	* {@code int flags} argument.
	* <p>
	* Some apps may be relying on a previous hidden API that delivered a
	* {@code int userId} argument, and this change is used to control delivery
	* of the new {@code int flags} argument in its place.
	*/
	@ChangeId
	@EnabledAfter(targetSdkVersion=android.os.Build.VERSION_CODES.Q)
	private static final long ADD_CONTENT_OBSERVER_FLAGS = 150939131L;
	private final Object mLock = new Object();
	private Transport mTransport; // guarded by mLock

	Handler mHandler;
	private final Executor mExecutor;

	/**
	* Creates a content observer.
	*
	* @param handler The handler to run {@link #onChange} on, or null if none.
	*/
	public ContentObserver(Handler handler) {
	mHandler = handler;
	mExecutor = null;
	}

	/**
	* @hide
	* Creates a content observer with an executor.
	*
	* @param executor The executor to run {@link #onChange} on, or null if none.
	* @param unused a second argument to avoid source incompatibility.
	*/
	public ContentObserver(@Nullable Executor executor, int unused) {
	mExecutor = executor;
	}

	/**
	* 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 richer arguments, applications should implement all overloads.
	* <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.
	*/
	public void onChange(boolean selfChange, @Nullable Uri uri) {
	onChange(selfChange);
	}

	/**
	* 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 richer arguments, applications should implement all overloads.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uri The Uri of the changed content.
	* @param flags Flags indicating details about this change.
	*/
	public void onChange(boolean selfChange, @Nullable Uri uri, @NotifyFlags int flags) {
	onChange(selfChange, uri);
	}

	/**
	* This method is called when a content change occurs. Includes the changed
	* content Uris 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 richer arguments, applications should implement all overloads.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uris The Uris of the changed content.
	* @param flags Flags indicating details about this change.
	*/
	public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
	@NotifyFlags int flags) {
	for (Uri uri : uris) {
	onChange(selfChange, uri, flags);
	}
	}

	/**
	* This method is called when a content change occurs. Includes the changed
	* content Uris 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 richer arguments, applications should implement all overloads.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uris The Uris of the changed content.
	* @param flags Flags indicating details about this change.
	* @param user The corresponding {@link UserHandle} for the current notification.
	*
	* @hide
	*/
	@SystemApi
	public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
	@NotifyFlags int flags, @NonNull UserHandle user) {
	onChange(selfChange, uris, user.getIdentifier());
	}

	/** @hide */
	public void onChange(boolean selfChange, @NonNull Collection<Uri> uris,
	@NotifyFlags int flags, @UserIdInt int userId) {
	// There are dozens of people relying on the hidden API inside the
	// system UID, so hard-code the old behavior for all of them; for
	// everyone else we gate based on a specific change
	if (!isChangeEnabledAddContentObserverFlags()
	\|\| android.os.Process.myUid() == android.os.Process.SYSTEM_UID) {
	// Deliver userId through argument to preserve hidden API behavior
	onChange(selfChange, uris, flags, UserHandle.of(userId));
	} else {
	onChange(selfChange, uris, flags);
	}
	}

	@android.ravenwood.annotation.RavenwoodReplace
	private static boolean isChangeEnabledAddContentObserverFlags() {
	return CompatChanges.isChangeEnabled(ADD_CONTENT_OBSERVER_FLAGS);
	}

	private static boolean isChangeEnabledAddContentObserverFlags$ravenwood() {
	return true;
	}

	/**
	* 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.
	*
	* @deprecated Callers should migrate towards using a richer overload that
	* provides more details about the change, such as
	* {@link #dispatchChange(boolean, Collection, int)}.
	*/
	@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.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uri The Uri of the changed content.
	*/
	public final void dispatchChange(boolean selfChange, @Nullable Uri uri) {
	dispatchChange(selfChange, uri, 0);
	}

	/**
	* 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.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uri The Uri of the changed content.
	* @param flags Flags indicating details about this change.
	*/
	public final void dispatchChange(boolean selfChange, @Nullable Uri uri,
	@NotifyFlags int flags) {
	dispatchChange(selfChange, Arrays.asList(uri), flags);
	}

	/**
	* Dispatches a change notification to the observer. Includes the changed
	* content Uris 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.
	*
	* @param selfChange True if this is a self-change notification.
	* @param uris The Uri of the changed content.
	* @param flags Flags indicating details about this change.
	*/
	public final void dispatchChange(boolean selfChange, @NonNull Collection<Uri> uris,
	@NotifyFlags int flags) {
	dispatchChange(selfChange, uris, flags, UserHandle.getCallingUserId());
	}

	/** @hide */
	public final void dispatchChange(boolean selfChange, @NonNull Collection<Uri> uris,
	@NotifyFlags int flags, @UserIdInt int userId) {
	if (mExecutor != null) {
	mExecutor.execute(() -> {
	onChange(selfChange, uris, flags, userId);
	});
	} else if (mHandler != null) {
	// Supporting Handler directly rather than wrapping in a HandlerExecutor
	// avoids introducing a RejectedExecutionException for legacy code when
	// the post fails.
	mHandler.post(() -> {
	onChange(selfChange, uris, flags, userId);
	});
	} else {
	onChange(selfChange, uris, flags, userId);
	}
	}

	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) {
	// This is kept intact purely for apps using hidden APIs, to
	// redirect to the updated implementation
	onChangeEtc(selfChange, new Uri[] { uri }, 0, userId);
	}

	@Override
	public void onChangeEtc(boolean selfChange, Uri[] uris, int flags, int userId) {
	ContentObserver contentObserver = mContentObserver;
	if (contentObserver != null) {
	contentObserver.dispatchChange(selfChange, Arrays.asList(uris), flags, userId);
	}
	}

	public void releaseContentObserver() {
	mContentObserver = null;
	}
	}
	}