Add typedefs and nullness annotations.
This changeset adds in typedef annotations (custom annotations
marked with @IntDef) for various int parameters and return values
in the API. It also adds nullness annotations for cases where the
documentation explicitly mentioned null policy, or where it was
blindingly obvious from the context. Also fixed some typos in the
documentation.
Change-Id: Ica27c01368895818e26237544edd8483007155bb
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 8df5bee..67f76f7 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -16,6 +16,10 @@
package android.content;
+import android.annotation.IntDef;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.annotation.StringDef;
import android.content.pm.ApplicationInfo;
import android.content.pm.PackageManager;
import android.content.res.AssetManager;
@@ -45,6 +49,8 @@
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
/**
* Interface to global information about an application environment. This is
@@ -130,6 +136,20 @@
*/
public static final int MODE_ENABLE_WRITE_AHEAD_LOGGING = 0x0008;
+ /** @hide */
+ @IntDef(flag = true,
+ value = {
+ BIND_AUTO_CREATE,
+ BIND_AUTO_CREATE,
+ BIND_DEBUG_UNBIND,
+ BIND_NOT_FOREGROUND,
+ BIND_ABOVE_CLIENT,
+ BIND_ALLOW_OOM_MANAGEMENT,
+ BIND_WAIVE_PRIORITY
+ })
+ @Retention(RetentionPolicy.SOURCE)
+ public @interface BindServiceFlags {}
+
/**
* Flag for {@link #bindService}: automatically create the service as long
* as the binding exists. Note that while this will create the service,
@@ -486,7 +506,7 @@
* and {@link #MODE_WORLD_WRITEABLE} to control permissions. The bit
* {@link #MODE_MULTI_PROCESS} can also be used if multiple processes
* are mutating the same SharedPreferences file. {@link #MODE_MULTI_PROCESS}
- * is always on in apps targetting Gingerbread (Android 2.3) and below, and
+ * is always on in apps targeting Gingerbread (Android 2.3) and below, and
* off by default in later versions.
*
* @return The single {@link SharedPreferences} instance that can be used
@@ -662,7 +682,8 @@
* @see #getFilesDir
* @see android.os.Environment#getExternalStoragePublicDirectory
*/
- public abstract File getExternalFilesDir(String type);
+ @Nullable
+ public abstract File getExternalFilesDir(@Nullable String type);
/**
* Returns absolute paths to application-specific directories on all
@@ -787,6 +808,7 @@
*
* @see #getCacheDir
*/
+ @Nullable
public abstract File getExternalCacheDir();
/**
@@ -893,7 +915,8 @@
* @see #deleteDatabase
*/
public abstract SQLiteDatabase openOrCreateDatabase(String name,
- int mode, CursorFactory factory, DatabaseErrorHandler errorHandler);
+ int mode, CursorFactory factory,
+ @Nullable DatabaseErrorHandler errorHandler);
/**
* Delete an existing private SQLiteDatabase associated with this Context's
@@ -1039,7 +1062,7 @@
* @see #startActivity(Intent)
* @see PackageManager#resolveActivity
*/
- public abstract void startActivity(Intent intent, Bundle options);
+ public abstract void startActivity(Intent intent, @Nullable Bundle options);
/**
* Version of {@link #startActivity(Intent, Bundle)} that allows you to specify the
@@ -1055,7 +1078,7 @@
* @throws ActivityNotFoundException
* @hide
*/
- public void startActivityAsUser(Intent intent, Bundle options, UserHandle userId) {
+ public void startActivityAsUser(Intent intent, @Nullable Bundle options, UserHandle userId) {
throw new RuntimeException("Not implemented. Must override in a subclass.");
}
@@ -1174,7 +1197,7 @@
* @see #startIntentSender(IntentSender, Intent, int, int, int)
*/
public abstract void startIntentSender(IntentSender intent,
- Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags,
+ @Nullable Intent fillInIntent, int flagsMask, int flagsValues, int extraFlags,
Bundle options) throws IntentSender.SendIntentException;
/**
@@ -1224,11 +1247,11 @@
* @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
*/
public abstract void sendBroadcast(Intent intent,
- String receiverPermission);
+ @Nullable String receiverPermission);
/**
* Like {@link #sendBroadcast(Intent, String)}, but also allows specification
- * of an assocated app op as per {@link android.app.AppOpsManager}.
+ * of an associated app op as per {@link android.app.AppOpsManager}.
* @hide
*/
public abstract void sendBroadcast(Intent intent,
@@ -1255,7 +1278,7 @@
* @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
*/
public abstract void sendOrderedBroadcast(Intent intent,
- String receiverPermission);
+ @Nullable String receiverPermission);
/**
* Version of {@link #sendBroadcast(Intent)} that allows you to
@@ -1299,15 +1322,15 @@
* @see #registerReceiver
* @see android.app.Activity#RESULT_OK
*/
- public abstract void sendOrderedBroadcast(Intent intent,
- String receiverPermission, BroadcastReceiver resultReceiver,
- Handler scheduler, int initialCode, String initialData,
- Bundle initialExtras);
+ public abstract void sendOrderedBroadcast(@NonNull Intent intent,
+ @Nullable String receiverPermission, BroadcastReceiver resultReceiver,
+ @Nullable Handler scheduler, int initialCode, @Nullable String initialData,
+ @Nullable Bundle initialExtras);
/**
* Like {@link #sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler,
* int, String, android.os.Bundle)}, but also allows specification
- * of an assocated app op as per {@link android.app.AppOpsManager}.
+ * of an associated app op as per {@link android.app.AppOpsManager}.
* @hide
*/
public abstract void sendOrderedBroadcast(Intent intent,
@@ -1342,7 +1365,7 @@
* @see #sendBroadcast(Intent, String)
*/
public abstract void sendBroadcastAsUser(Intent intent, UserHandle user,
- String receiverPermission);
+ @Nullable String receiverPermission);
/**
* Version of
@@ -1375,8 +1398,9 @@
* @see #sendOrderedBroadcast(Intent, String, BroadcastReceiver, Handler, int, String, Bundle)
*/
public abstract void sendOrderedBroadcastAsUser(Intent intent, UserHandle user,
- String receiverPermission, BroadcastReceiver resultReceiver, Handler scheduler,
- int initialCode, String initialData, Bundle initialExtras);
+ @Nullable String receiverPermission, BroadcastReceiver resultReceiver,
+ @Nullable Handler scheduler, int initialCode, @Nullable String initialData,
+ @Nullable Bundle initialExtras);
/**
* Perform a {@link #sendBroadcast(Intent)} that is "sticky," meaning the
@@ -1441,8 +1465,8 @@
*/
public abstract void sendStickyOrderedBroadcast(Intent intent,
BroadcastReceiver resultReceiver,
- Handler scheduler, int initialCode, String initialData,
- Bundle initialExtras);
+ @Nullable Handler scheduler, int initialCode, @Nullable String initialData,
+ @Nullable Bundle initialExtras);
/**
* Remove the data previously sent with {@link #sendStickyBroadcast},
@@ -1502,8 +1526,8 @@
*/
public abstract void sendStickyOrderedBroadcastAsUser(Intent intent,
UserHandle user, BroadcastReceiver resultReceiver,
- Handler scheduler, int initialCode, String initialData,
- Bundle initialExtras);
+ @Nullable Handler scheduler, int initialCode, @Nullable String initialData,
+ @Nullable Bundle initialExtras);
/**
* Version of {@link #removeStickyBroadcast(Intent)} that allows you to specify the
@@ -1570,7 +1594,8 @@
* @see #sendBroadcast
* @see #unregisterReceiver
*/
- public abstract Intent registerReceiver(BroadcastReceiver receiver,
+ @Nullable
+ public abstract Intent registerReceiver(@Nullable BroadcastReceiver receiver,
IntentFilter filter);
/**
@@ -1604,8 +1629,10 @@
* @see #sendBroadcast
* @see #unregisterReceiver
*/
+ @Nullable
public abstract Intent registerReceiver(BroadcastReceiver receiver,
- IntentFilter filter, String broadcastPermission, Handler scheduler);
+ IntentFilter filter, @Nullable String broadcastPermission,
+ @Nullable Handler scheduler);
/**
* @hide
@@ -1631,9 +1658,10 @@
* @see #sendBroadcast
* @see #unregisterReceiver
*/
+ @Nullable
public abstract Intent registerReceiverAsUser(BroadcastReceiver receiver,
- UserHandle user, IntentFilter filter, String broadcastPermission,
- Handler scheduler);
+ UserHandle user, IntentFilter filter, @Nullable String broadcastPermission,
+ @Nullable Handler scheduler);
/**
* Unregister a previously registered BroadcastReceiver. <em>All</em>
@@ -1693,6 +1721,7 @@
* @see #stopService
* @see #bindService
*/
+ @Nullable
public abstract ComponentName startService(Intent service);
/**
@@ -1780,8 +1809,8 @@
* @see #BIND_DEBUG_UNBIND
* @see #BIND_NOT_FOREGROUND
*/
- public abstract boolean bindService(Intent service, ServiceConnection conn,
- int flags);
+ public abstract boolean bindService(Intent service, @NonNull ServiceConnection conn,
+ @BindServiceFlags int flags);
/**
* Same as {@link #bindService(Intent, ServiceConnection, int)}, but with an explicit userHandle
@@ -1802,7 +1831,7 @@
*
* @see #bindService
*/
- public abstract void unbindService(ServiceConnection conn);
+ public abstract void unbindService(@NonNull ServiceConnection conn);
/**
* Start executing an {@link android.app.Instrumentation} class. The given
@@ -1827,8 +1856,64 @@
* @return {@code true} if the instrumentation was successfully started,
* else {@code false} if it could not be found.
*/
- public abstract boolean startInstrumentation(ComponentName className,
- String profileFile, Bundle arguments);
+ public abstract boolean startInstrumentation(@NonNull ComponentName className,
+ @Nullable String profileFile, @Nullable Bundle arguments);
+
+ /** @hide */
+ @StringDef({
+ POWER_SERVICE,
+ WINDOW_SERVICE,
+ LAYOUT_INFLATER_SERVICE,
+ ACCOUNT_SERVICE,
+ ACTIVITY_SERVICE,
+ ALARM_SERVICE,
+ NOTIFICATION_SERVICE,
+ ACCESSIBILITY_SERVICE,
+ CAPTIONING_SERVICE,
+ KEYGUARD_SERVICE,
+ LOCATION_SERVICE,
+ //@hide: COUNTRY_DETECTOR,
+ SEARCH_SERVICE,
+ SENSOR_SERVICE,
+ STORAGE_SERVICE,
+ WALLPAPER_SERVICE,
+ VIBRATOR_SERVICE,
+ //@hide: STATUS_BAR_SERVICE,
+ CONNECTIVITY_SERVICE,
+ //@hide: UPDATE_LOCK_SERVICE,
+ //@hide: NETWORKMANAGEMENT_SERVICE,
+ //@hide: NETWORK_STATS_SERVICE,
+ //@hide: NETWORK_POLICY_SERVICE,
+ WIFI_SERVICE,
+ WIFI_P2P_SERVICE,
+ NSD_SERVICE,
+ AUDIO_SERVICE,
+ MEDIA_ROUTER_SERVICE,
+ TELEPHONY_SERVICE,
+ CLIPBOARD_SERVICE,
+ INPUT_METHOD_SERVICE,
+ TEXT_SERVICES_MANAGER_SERVICE,
+ //@hide: APPWIDGET_SERVICE,
+ //@hide: BACKUP_SERVICE,
+ DROPBOX_SERVICE,
+ DEVICE_POLICY_SERVICE,
+ UI_MODE_SERVICE,
+ DOWNLOAD_SERVICE,
+ NFC_SERVICE,
+ BLUETOOTH_SERVICE,
+ //@hide: SIP_SERVICE,
+ USB_SERVICE,
+ //@hide: SERIAL_SERVICE,
+ INPUT_SERVICE,
+ DISPLAY_SERVICE,
+ //@hide: SCHEDULING_POLICY_SERVICE,
+ USER_SERVICE,
+ //@hide: APP_OPS_SERVICE
+ CAMERA_SERVICE,
+ PRINT_SERVICE
+ })
+ @Retention(RetentionPolicy.SOURCE)
+ public @interface ServiceName {}
/**
* Return the handle to a system-level service by name. The class of the
@@ -1929,7 +2014,7 @@
* @see #DOWNLOAD_SERVICE
* @see android.app.DownloadManager
*/
- public abstract Object getSystemService(String name);
+ public abstract Object getSystemService(@ServiceName @NonNull String name);
/**
* Use with {@link #getSystemService} to retrieve a
@@ -2409,7 +2494,8 @@
* @see PackageManager#checkPermission(String, String)
* @see #checkCallingPermission
*/
- public abstract int checkPermission(String permission, int pid, int uid);
+ @PackageManager.PermissionResult
+ public abstract int checkPermission(@NonNull String permission, int pid, int uid);
/**
* Determine whether the calling process of an IPC you are handling has been
@@ -2432,7 +2518,8 @@
* @see #checkPermission
* @see #checkCallingOrSelfPermission
*/
- public abstract int checkCallingPermission(String permission);
+ @PackageManager.PermissionResult
+ public abstract int checkCallingPermission(@NonNull String permission);
/**
* Determine whether the calling process of an IPC <em>or you</em> have been
@@ -2450,7 +2537,8 @@
* @see #checkPermission
* @see #checkCallingPermission
*/
- public abstract int checkCallingOrSelfPermission(String permission);
+ @PackageManager.PermissionResult
+ public abstract int checkCallingOrSelfPermission(@NonNull String permission);
/**
* If the given permission is not allowed for a particular process
@@ -2465,7 +2553,7 @@
* @see #checkPermission(String, int, int)
*/
public abstract void enforcePermission(
- String permission, int pid, int uid, String message);
+ @NonNull String permission, int pid, int uid, @Nullable String message);
/**
* If the calling process of an IPC you are handling has not been
@@ -2486,7 +2574,7 @@
* @see #checkCallingPermission(String)
*/
public abstract void enforceCallingPermission(
- String permission, String message);
+ @NonNull String permission, @Nullable String message);
/**
* If neither you nor the calling process of an IPC you are
@@ -2502,7 +2590,7 @@
* @see #checkCallingOrSelfPermission(String)
*/
public abstract void enforceCallingOrSelfPermission(
- String permission, String message);
+ @NonNull String permission, @Nullable String message);
/**
* Grant permission to access a specific Uri to another package, regardless
@@ -2538,7 +2626,7 @@
* @see #revokeUriPermission
*/
public abstract void grantUriPermission(String toPackage, Uri uri,
- int modeFlags);
+ @Intent.GrantUriMode int modeFlags);
/**
* Remove all permissions to access a particular content provider Uri
@@ -2557,7 +2645,7 @@
*
* @see #grantUriPermission
*/
- public abstract void revokeUriPermission(Uri uri, int modeFlags);
+ public abstract void revokeUriPermission(Uri uri, @Intent.GrantUriMode int modeFlags);
/**
* Determine whether a particular process and user ID has been granted
@@ -2580,7 +2668,8 @@
*
* @see #checkCallingUriPermission
*/
- public abstract int checkUriPermission(Uri uri, int pid, int uid, int modeFlags);
+ public abstract int checkUriPermission(Uri uri, int pid, int uid,
+ @Intent.GrantUriMode int modeFlags);
/**
* Determine whether the calling process and user ID has been
@@ -2603,7 +2692,7 @@
*
* @see #checkUriPermission(Uri, int, int, int)
*/
- public abstract int checkCallingUriPermission(Uri uri, int modeFlags);
+ public abstract int checkCallingUriPermission(Uri uri, @Intent.GrantUriMode int modeFlags);
/**
* Determine whether the calling process of an IPC <em>or you</em> has been granted
@@ -2622,7 +2711,8 @@
*
* @see #checkCallingUriPermission
*/
- public abstract int checkCallingOrSelfUriPermission(Uri uri, int modeFlags);
+ public abstract int checkCallingOrSelfUriPermission(Uri uri,
+ @Intent.GrantUriMode int modeFlags);
/**
* Check both a Uri and normal permission. This allows you to perform
@@ -2634,7 +2724,7 @@
* @param readPermission The permission that provides overall read access,
* or null to not do this check.
* @param writePermission The permission that provides overall write
- * acess, or null to not do this check.
+ * access, or null to not do this check.
* @param pid The process ID being checked against. Must be > 0.
* @param uid The user ID being checked against. A uid of 0 is the root
* user, which will pass every permission check.
@@ -2646,8 +2736,9 @@
* is allowed to access that uri or holds one of the given permissions, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*/
- public abstract int checkUriPermission(Uri uri, String readPermission,
- String writePermission, int pid, int uid, int modeFlags);
+ public abstract int checkUriPermission(@Nullable Uri uri, @Nullable String readPermission,
+ @Nullable String writePermission, int pid, int uid,
+ @Intent.GrantUriMode int modeFlags);
/**
* If a particular process and user ID has not been granted
@@ -2669,7 +2760,7 @@
* @see #checkUriPermission(Uri, int, int, int)
*/
public abstract void enforceUriPermission(
- Uri uri, int pid, int uid, int modeFlags, String message);
+ Uri uri, int pid, int uid, @Intent.GrantUriMode int modeFlags, String message);
/**
* If the calling process and user ID has not been granted
@@ -2691,7 +2782,7 @@
* @see #checkCallingUriPermission(Uri, int)
*/
public abstract void enforceCallingUriPermission(
- Uri uri, int modeFlags, String message);
+ Uri uri, @Intent.GrantUriMode int modeFlags, String message);
/**
* If the calling process of an IPC <em>or you</em> has not been
@@ -2710,7 +2801,7 @@
* @see #checkCallingOrSelfUriPermission(Uri, int)
*/
public abstract void enforceCallingOrSelfUriPermission(
- Uri uri, int modeFlags, String message);
+ Uri uri, @Intent.GrantUriMode int modeFlags, String message);
/**
* Enforce both a Uri and normal permission. This allows you to perform
@@ -2722,7 +2813,7 @@
* @param readPermission The permission that provides overall read access,
* or null to not do this check.
* @param writePermission The permission that provides overall write
- * acess, or null to not do this check.
+ * access, or null to not do this check.
* @param pid The process ID being checked against. Must be > 0.
* @param uid The user ID being checked against. A uid of 0 is the root
* user, which will pass every permission check.
@@ -2734,8 +2825,15 @@
* @see #checkUriPermission(Uri, String, String, int, int, int)
*/
public abstract void enforceUriPermission(
- Uri uri, String readPermission, String writePermission,
- int pid, int uid, int modeFlags, String message);
+ @Nullable Uri uri, @Nullable String readPermission,
+ @Nullable String writePermission, int pid, int uid, @Intent.GrantUriMode int modeFlags,
+ @Nullable String message);
+
+ /** @hide */
+ @IntDef(flag = true,
+ value = {CONTEXT_INCLUDE_CODE, CONTEXT_IGNORE_SECURITY, CONTEXT_RESTRICTED})
+ @Retention(RetentionPolicy.SOURCE)
+ public @interface CreatePackageOptions {}
/**
* Flag for use with {@link #createPackageContext}: include the application
@@ -2793,7 +2891,7 @@
* the given package name.
*/
public abstract Context createPackageContext(String packageName,
- int flags) throws PackageManager.NameNotFoundException;
+ @CreatePackageOptions int flags) throws PackageManager.NameNotFoundException;
/**
* Similar to {@link #createPackageContext(String, int)}, but with a
@@ -2829,7 +2927,8 @@
*
* @return A {@link Context} with the given configuration override.
*/
- public abstract Context createConfigurationContext(Configuration overrideConfiguration);
+ public abstract Context createConfigurationContext(
+ @NonNull Configuration overrideConfiguration);
/**
* Return a new Context object for the current Context but whose resources
@@ -2849,7 +2948,7 @@
*
* @return A {@link Context} for the display.
*/
- public abstract Context createDisplayContext(Display display);
+ public abstract Context createDisplayContext(@NonNull Display display);
/**
* Gets the display adjustments holder for this context. This information