Add nullability annotations to Handler's public API

Fixes: 126702574
Test: none
Change-Id: I396665e0971c6dc8eabbcfa32dee07bcdce13061

diff --git a/api/current.txt b/api/current.txt
index a291a10..03a56bc 100644 (file)
--- a/api/current.txt
+++ b/api/current.txt
@@ -34676,46 +34676,46 @@ package android.os {
 
   public class Handler {
     ctor public Handler();
-    ctor public Handler(android.os.Handler.Callback);
-    ctor public Handler(android.os.Looper);
-    ctor public Handler(android.os.Looper, android.os.Handler.Callback);
+    ctor public Handler(@Nullable android.os.Handler.Callback);
+    ctor public Handler(@NonNull android.os.Looper);
+    ctor public Handler(@NonNull android.os.Looper, @Nullable android.os.Handler.Callback);
     method @NonNull public static android.os.Handler createAsync(@NonNull android.os.Looper);
     method @NonNull public static android.os.Handler createAsync(@NonNull android.os.Looper, @NonNull android.os.Handler.Callback);
-    method public void dispatchMessage(android.os.Message);
-    method public final void dump(android.util.Printer, String);
-    method public final android.os.Looper getLooper();
-    method public String getMessageName(android.os.Message);
-    method public void handleMessage(android.os.Message);
-    method public final boolean hasCallbacks(Runnable);
+    method public void dispatchMessage(@NonNull android.os.Message);
+    method public final void dump(@NonNull android.util.Printer, @NonNull String);
+    method @NonNull public final android.os.Looper getLooper();
+    method @NonNull public String getMessageName(@NonNull android.os.Message);
+    method public void handleMessage(@NonNull android.os.Message);
+    method public final boolean hasCallbacks(@NonNull Runnable);
     method public final boolean hasMessages(int);
-    method public final boolean hasMessages(int, Object);
-    method public final android.os.Message obtainMessage();
-    method public final android.os.Message obtainMessage(int);
-    method public final android.os.Message obtainMessage(int, Object);
-    method public final android.os.Message obtainMessage(int, int, int);
-    method public final android.os.Message obtainMessage(int, int, int, Object);
-    method public final boolean post(Runnable);
-    method public final boolean postAtFrontOfQueue(Runnable);
-    method public final boolean postAtTime(Runnable, long);
-    method public final boolean postAtTime(Runnable, Object, long);
-    method public final boolean postDelayed(Runnable, long);
-    method public final boolean postDelayed(Runnable, Object, long);
-    method public final void removeCallbacks(Runnable);
-    method public final void removeCallbacks(Runnable, Object);
-    method public final void removeCallbacksAndMessages(Object);
+    method public final boolean hasMessages(int, @Nullable Object);
+    method @NonNull public final android.os.Message obtainMessage();
+    method @NonNull public final android.os.Message obtainMessage(int);
+    method @NonNull public final android.os.Message obtainMessage(int, @Nullable Object);
+    method @NonNull public final android.os.Message obtainMessage(int, int, int);
+    method @NonNull public final android.os.Message obtainMessage(int, int, int, @Nullable Object);
+    method public final boolean post(@NonNull Runnable);
+    method public final boolean postAtFrontOfQueue(@NonNull Runnable);
+    method public final boolean postAtTime(@NonNull Runnable, long);
+    method public final boolean postAtTime(@NonNull Runnable, @Nullable Object, long);
+    method public final boolean postDelayed(@NonNull Runnable, long);
+    method public final boolean postDelayed(@NonNull Runnable, @Nullable Object, long);
+    method public final void removeCallbacks(@NonNull Runnable);
+    method public final void removeCallbacks(@NonNull Runnable, @Nullable Object);
+    method public final void removeCallbacksAndMessages(@Nullable Object);
     method public final void removeMessages(int);
-    method public final void removeMessages(int, Object);
+    method public final void removeMessages(int, @Nullable Object);
     method public final boolean sendEmptyMessage(int);
     method public final boolean sendEmptyMessageAtTime(int, long);
     method public final boolean sendEmptyMessageDelayed(int, long);
-    method public final boolean sendMessage(android.os.Message);
-    method public final boolean sendMessageAtFrontOfQueue(android.os.Message);
-    method public boolean sendMessageAtTime(android.os.Message, long);
-    method public final boolean sendMessageDelayed(android.os.Message, long);
+    method public final boolean sendMessage(@NonNull android.os.Message);
+    method public final boolean sendMessageAtFrontOfQueue(@NonNull android.os.Message);
+    method public boolean sendMessageAtTime(@NonNull android.os.Message, long);
+    method public final boolean sendMessageDelayed(@NonNull android.os.Message, long);
   }
 
   public static interface Handler.Callback {
-    method public boolean handleMessage(android.os.Message);
+    method public boolean handleMessage(@NonNull android.os.Message);
   }
 
   public class HandlerThread extends java.lang.Thread {

diff --git a/core/java/android/os/Handler.java b/core/java/android/os/Handler.java
index e6c12c7..a039742 100644 (file)
--- a/core/java/android/os/Handler.java
+++ b/core/java/android/os/Handler.java
@@ -82,19 +82,19 @@ public class Handler {
          * @param msg A {@link android.os.Message Message} object
          * @return True if no further handling is desired
          */
-        public boolean handleMessage(Message msg);
+        boolean handleMessage(@NonNull Message msg);
     }
     
     /**
      * Subclasses must implement this to receive messages.
      */
-    public void handleMessage(Message msg) {
+    public void handleMessage(@NonNull Message msg) {
     }
     
     /**
      * Handle system messages here.
      */
-    public void dispatchMessage(Message msg) {
+    public void dispatchMessage(@NonNull Message msg) {
         if (msg.callback != null) {
             handleCallback(msg);
         } else {
@@ -128,7 +128,7 @@ public class Handler {
      *
      * @param callback The callback interface in which to handle messages, or null.
      */
-    public Handler(Callback callback) {
+    public Handler(@Nullable Callback callback) {
         this(callback, false);
     }
 
@@ -137,7 +137,7 @@ public class Handler {
      *
      * @param looper The looper, must not be null.
      */
-    public Handler(Looper looper) {
+    public Handler(@NonNull Looper looper) {
         this(looper, null, false);
     }
 
@@ -148,7 +148,7 @@ public class Handler {
      * @param looper The looper, must not be null.
      * @param callback The callback interface in which to handle messages, or null.
      */
-    public Handler(Looper looper, Callback callback) {
+    public Handler(@NonNull Looper looper, @Nullable Callback callback) {
         this(looper, callback, false);
     }
 
@@ -189,7 +189,7 @@ public class Handler {
      *
      * @hide
      */
-    public Handler(Callback callback, boolean async) {
+    public Handler(@Nullable Callback callback, boolean async) {
         if (FIND_POTENTIAL_LEAKS) {
             final Class<? extends Handler> klass = getClass();
             if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
@@ -229,7 +229,7 @@ public class Handler {
      *
      * @hide
      */
-    public Handler(Looper looper, Callback callback, boolean async) {
+    public Handler(@NonNull Looper looper, @Nullable Callback callback, boolean async) {
         mLooper = looper;
         mQueue = looper.mQueue;
         mCallback = callback;
@@ -289,7 +289,8 @@ public class Handler {
     }
 
     /** {@hide} */
-    public String getTraceName(Message message) {
+    @NonNull
+    public String getTraceName(@NonNull Message message) {
         final StringBuilder sb = new StringBuilder();
         sb.append(getClass().getName()).append(": ");
         if (message.callback != null) {
@@ -308,7 +309,8 @@ public class Handler {
      *  
      * @param message The message whose name is being queried 
      */
-    public String getMessageName(Message message) {
+    @NonNull
+    public String getMessageName(@NonNull Message message) {
         if (message.callback != null) {
             return message.callback.getClass().getName();
         }
@@ -320,6 +322,7 @@ public class Handler {
      * creating and allocating new instances. The retrieved message has its handler set to this instance (Message.target == this).
      *  If you don't want that facility, just call Message.obtain() instead.
      */
+    @NonNull
     public final Message obtainMessage()
     {
         return Message.obtain(this);
@@ -331,6 +334,7 @@ public class Handler {
      * @param what Value to assign to the returned Message.what field.
      * @return A Message from the global message pool.
      */
+    @NonNull
     public final Message obtainMessage(int what)
     {
         return Message.obtain(this, what);
@@ -345,8 +349,8 @@ public class Handler {
      * @param obj Value to assign to the returned Message.obj field.
      * @return A Message from the global message pool.
      */
-    public final Message obtainMessage(int what, Object obj)
-    {
+    @NonNull
+    public final Message obtainMessage(int what, @Nullable Object obj) {
         return Message.obtain(this, what, obj);
     }
 
@@ -359,6 +363,7 @@ public class Handler {
      * @param arg2 Value to assign to the returned Message.arg2 field.
      * @return A Message from the global message pool.
      */
+    @NonNull
     public final Message obtainMessage(int what, int arg1, int arg2)
     {
         return Message.obtain(this, what, arg1, arg2);
@@ -374,8 +379,8 @@ public class Handler {
      * @param obj Value to assign to the returned Message.obj field.
      * @return A Message from the global message pool.
      */
-    public final Message obtainMessage(int what, int arg1, int arg2, Object obj)
-    {
+    @NonNull
+    public final Message obtainMessage(int what, int arg1, int arg2, @Nullable Object obj) {
         return Message.obtain(this, what, arg1, arg2, obj);
     }
 
@@ -390,8 +395,7 @@ public class Handler {
      *         message queue.  Returns false on failure, usually because the
      *         looper processing the message queue is exiting.
      */
-    public final boolean post(Runnable r)
-    {
+    public final boolean post(@NonNull Runnable r) {
        return  sendMessageDelayed(getPostMessage(r), 0);
     }
     
@@ -413,8 +417,7 @@ public class Handler {
      *         the looper is quit before the delivery time of the message
      *         occurs then the message will be dropped.
      */
-    public final boolean postAtTime(Runnable r, long uptimeMillis)
-    {
+    public final boolean postAtTime(@NonNull Runnable r, long uptimeMillis) {
         return sendMessageAtTime(getPostMessage(r), uptimeMillis);
     }
     
@@ -440,8 +443,8 @@ public class Handler {
      *         
      * @see android.os.SystemClock#uptimeMillis
      */
-    public final boolean postAtTime(Runnable r, Object token, long uptimeMillis)
-    {
+    public final boolean postAtTime(
+            @NonNull Runnable r, @Nullable Object token, long uptimeMillis) {
         return sendMessageAtTime(getPostMessage(r, token), uptimeMillis);
     }
     
@@ -464,8 +467,7 @@ public class Handler {
      *         if the looper is quit before the delivery time of the message
      *         occurs then the message will be dropped.
      */
-    public final boolean postDelayed(Runnable r, long delayMillis)
-    {
+    public final boolean postDelayed(@NonNull Runnable r, long delayMillis) {
         return sendMessageDelayed(getPostMessage(r), delayMillis);
     }
     
@@ -495,8 +497,8 @@ public class Handler {
      *         if the looper is quit before the delivery time of the message
      *         occurs then the message will be dropped.
      */
-    public final boolean postDelayed(Runnable r, Object token, long delayMillis)
-    {
+    public final boolean postDelayed(
+            @NonNull Runnable r, @Nullable Object token, long delayMillis) {
         return sendMessageDelayed(getPostMessage(r, token), delayMillis);
     }
 
@@ -515,8 +517,7 @@ public class Handler {
      *         message queue.  Returns false on failure, usually because the
      *         looper processing the message queue is exiting.
      */
-    public final boolean postAtFrontOfQueue(Runnable r)
-    {
+    public final boolean postAtFrontOfQueue(@NonNull Runnable r) {
         return sendMessageAtFrontOfQueue(getPostMessage(r));
     }
 
@@ -560,7 +561,7 @@ public class Handler {
      * If we ever do make it part of the API, we might want to rename it to something
      * less funny like runUnsafe().
      */
-    public final boolean runWithScissors(final Runnable r, long timeout) {
+    public final boolean runWithScissors(@NonNull Runnable r, long timeout) {
         if (r == null) {
             throw new IllegalArgumentException("runnable must not be null");
         }
@@ -580,8 +581,7 @@ public class Handler {
     /**
      * Remove any pending posts of Runnable r that are in the message queue.
      */
-    public final void removeCallbacks(Runnable r)
-    {
+    public final void removeCallbacks(@NonNull Runnable r) {
         mQueue.removeMessages(this, r, null);
     }
 
@@ -590,8 +590,7 @@ public class Handler {
      * <var>token</var> that are in the message queue.  If <var>token</var> is null,
      * all callbacks will be removed.
      */
-    public final void removeCallbacks(Runnable r, Object token)
-    {
+    public final void removeCallbacks(@NonNull Runnable r, @Nullable Object token) {
         mQueue.removeMessages(this, r, token);
     }
 
@@ -604,8 +603,7 @@ public class Handler {
      *         message queue.  Returns false on failure, usually because the
      *         looper processing the message queue is exiting.
      */
-    public final boolean sendMessage(Message msg)
-    {
+    public final boolean sendMessage(@NonNull Message msg) {
         return sendMessageDelayed(msg, 0);
     }
 
@@ -664,8 +662,7 @@ public class Handler {
      *         the looper is quit before the delivery time of the message
      *         occurs then the message will be dropped.
      */
-    public final boolean sendMessageDelayed(Message msg, long delayMillis)
-    {
+    public final boolean sendMessageDelayed(@NonNull Message msg, long delayMillis) {
         if (delayMillis < 0) {
             delayMillis = 0;
         }
@@ -691,7 +688,7 @@ public class Handler {
      *         the looper is quit before the delivery time of the message
      *         occurs then the message will be dropped.
      */
-    public boolean sendMessageAtTime(Message msg, long uptimeMillis) {
+    public boolean sendMessageAtTime(@NonNull Message msg, long uptimeMillis) {
         MessageQueue queue = mQueue;
         if (queue == null) {
             RuntimeException e = new RuntimeException(
@@ -714,7 +711,7 @@ public class Handler {
      *         message queue.  Returns false on failure, usually because the
      *         looper processing the message queue is exiting.
      */
-    public final boolean sendMessageAtFrontOfQueue(Message msg) {
+    public final boolean sendMessageAtFrontOfQueue(@NonNull Message msg) {
         MessageQueue queue = mQueue;
         if (queue == null) {
             RuntimeException e = new RuntimeException(
@@ -734,7 +731,7 @@ public class Handler {
      *         looper processing the message queue is exiting.
      * @hide
      */
-    public final boolean executeOrSendMessage(Message msg) {
+    public final boolean executeOrSendMessage(@NonNull Message msg) {
         if (mLooper == Looper.myLooper()) {
             dispatchMessage(msg);
             return true;
@@ -742,7 +739,8 @@ public class Handler {
         return sendMessage(msg);
     }
 
-    private boolean enqueueMessage(MessageQueue queue, Message msg, long uptimeMillis) {
+    private boolean enqueueMessage(@NonNull MessageQueue queue, @NonNull Message msg,
+            long uptimeMillis) {
         msg.target = this;
         msg.workSourceUid = ThreadLocalWorkSource.getUid();
 
@@ -765,7 +763,7 @@ public class Handler {
      * 'object' that are in the message queue.  If <var>object</var> is null,
      * all messages will be removed.
      */
-    public final void removeMessages(int what, Object object) {
+    public final void removeMessages(int what, @Nullable Object object) {
         mQueue.removeMessages(this, what, object);
     }
 
@@ -774,7 +772,7 @@ public class Handler {
      * <var>obj</var> is <var>token</var>.  If <var>token</var> is null,
      * all callbacks and messages will be removed.
      */
-    public final void removeCallbacksAndMessages(Object token) {
+    public final void removeCallbacksAndMessages(@Nullable Object token) {
         mQueue.removeCallbacksAndMessages(this, token);
     }
 
@@ -798,7 +796,7 @@ public class Handler {
      * Check if there are any pending posts of messages with code 'what' and
      * whose obj is 'object' in the message queue.
      */
-    public final boolean hasMessages(int what, Object object) {
+    public final boolean hasMessages(int what, @Nullable Object object) {
         return mQueue.hasMessages(this, what, object);
     }
 
@@ -806,17 +804,18 @@ public class Handler {
      * Check if there are any pending posts of messages with callback r in
      * the message queue.
      */
-    public final boolean hasCallbacks(Runnable r) {
+    public final boolean hasCallbacks(@NonNull Runnable r) {
         return mQueue.hasMessages(this, r, null);
     }
 
     // if we can get rid of this method, the handler need not remember its loop
     // we could instead export a getMessageQueue() method... 
+    @NonNull
     public final Looper getLooper() {
         return mLooper;
     }
 
-    public final void dump(Printer pw, String prefix) {
+    public final void dump(@NonNull Printer pw, @NonNull String prefix) {
         pw.println(prefix + this + " @ " + SystemClock.uptimeMillis());
         if (mLooper == null) {
             pw.println(prefix + "looper uninitialized");
@@ -828,7 +827,7 @@ public class Handler {
     /**
      * @hide
      */
-    public final void dumpMine(Printer pw, String prefix) {
+    public final void dumpMine(@NonNull Printer pw, @NonNull String prefix) {
         pw.println(prefix + this + " @ " + SystemClock.uptimeMillis());
         if (mLooper == null) {
             pw.println(prefix + "looper uninitialized");