From abe61584313af40691ce5a0759a2e26b20138ab9 Mon Sep 17 00:00:00 2001 From: Jiyong Park Date: Wed, 4 Dec 2019 17:17:48 +0900 Subject: [PATCH 1/3] SystemApi is parameterized We have decided to reuse the existing annotation @SystemApi for all Java APIs regardless of whether they are for apps or platform internal modules. This was because introducing new annotation types every time when we have to create new API surfaces will only increase the confusion without giving much benefit. Instead, to differenciate the different API surfaces of @SystemApi, the annotation type is parameterized. Specifically, it has to axises. client: specifies the intended client of the API. process: specifies the process(es) that the API is available. The default for client and process are priv-apps and all, respectively, which corresponds to the today's @SystemApi for privileged apps like GMS. Exempt-From-Owner-Approval: cherry-pick from internal Bug: 140202860 Test: m Merged-In: I3305b71e22970e80db95f3daf3d7713603c7d68d (cherry picked from commit 119afc0695cf7632700119bab62a965793c34fd1) Change-Id: I3305b71e22970e80db95f3daf3d7713603c7d68d --- Android.bp | 10 ++++----- core/java/android/annotation/SystemApi.java | 25 +++++++++++++++++++++ media/Android.bp | 2 +- services/Android.bp | 2 +- 4 files changed, 32 insertions(+), 7 deletions(-) diff --git a/Android.bp b/Android.bp index 7d95b9a1b1fbb..486d9bd7dedeb 100644 --- a/Android.bp +++ b/Android.bp @@ -1123,7 +1123,7 @@ droidstubs { arg_files: [ "core/res/AndroidManifest.xml", ], - args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi ", + args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) ", write_sdk_values: true, } @@ -1434,7 +1434,7 @@ droidstubs { merge_annotations_dirs: [ "metalava-manual", ], - args: " --show-annotation android.annotation.SystemApi", + args: " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\)", } java_library_static { @@ -1456,7 +1456,7 @@ droidstubs { removed_dex_api_filename: "removed-dex.txt", args: metalava_framework_docs_args + " --show-unannotated " + - " --show-annotation android.annotation.SystemApi " + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) " + " --show-annotation android.annotation.TestApi ", } @@ -1475,7 +1475,7 @@ droidstubs { " --hide ReferencesHidden " + " --hide UnhiddenSystemApi " + " --show-unannotated " + - " --show-annotation android.annotation.SystemApi " + + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) " + " --show-annotation android.annotation.TestApi ", } @@ -1519,7 +1519,7 @@ droidstubs { arg_files: [ "core/res/AndroidManifest.xml", ], - args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi", + args: metalava_framework_docs_args + " --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\)", check_api: { current: { api_file: "api/system-current.txt", diff --git a/core/java/android/annotation/SystemApi.java b/core/java/android/annotation/SystemApi.java index e96ff01d0850f..f589cc5704b42 100644 --- a/core/java/android/annotation/SystemApi.java +++ b/core/java/android/annotation/SystemApi.java @@ -41,4 +41,29 @@ import java.lang.annotation.Target; @Target({TYPE, FIELD, METHOD, CONSTRUCTOR, ANNOTATION_TYPE, PACKAGE}) @Retention(RetentionPolicy.RUNTIME) public @interface SystemApi { + enum Client { + /** + * Specifies that the intended clients of a SystemApi are privileged apps. + * This is the default value for {@link #client}. + */ + PRIVILEGED_APPS, + } + + enum Process { + /** + * Specifies that the SystemAPI is available in every Java processes. + * This is the default value for {@link #process}. + */ + ALL, + } + + /** + * The intended client of this SystemAPI. + */ + Client client() default android.annotation.SystemApi.Client.PRIVILEGED_APPS; + + /** + * The process(es) that this SystemAPI is available + */ + Process process() default android.annotation.SystemApi.Process.ALL; } diff --git a/media/Android.bp b/media/Android.bp index a768b81731eb3..d7cd054ddc3a3 100644 --- a/media/Android.bp +++ b/media/Android.bp @@ -66,7 +66,7 @@ metalava_updatable_media_args = " --error UnhiddenSystemApi " + "--hide MissingPermission --hide BroadcastBehavior " + "--hide HiddenSuperclass --hide DeprecationMismatch --hide UnavailableSymbol " + "--hide SdkConstant --hide HiddenTypeParameter --hide Todo --hide Typo " + - "--hide HiddenTypedefConstant --show-annotation android.annotation.SystemApi " + "--hide HiddenTypedefConstant --show-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.PRIVILEGED_APPS,process=android.annotation.SystemApi.Process.ALL\\) " droidstubs { name: "updatable-media-stubs", diff --git a/services/Android.bp b/services/Android.bp index 5290ebb85f3a1..72c13747e011a 100644 --- a/services/Android.bp +++ b/services/Android.bp @@ -110,7 +110,7 @@ droidstubs { srcs: [":services-sources"], installable: false, // TODO: remove the --hide options below - args: " --show-single-annotation android.annotation.SystemApi" + + args: " --show-single-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.INTERNAL,process=android.annotation.SystemApi.Process.SYSTEM_SERVER\\)" + " --hide-annotation android.annotation.Hide" + " --hide-package com.google.android.startop.iorap" + " --hide ReferencesHidden" + From 5ed5a04385cf7fa2910f59fac7f798277bc3ff0d Mon Sep 17 00:00:00 2001 From: Jiyong Park Date: Fri, 13 Dec 2019 14:53:14 +0900 Subject: [PATCH 2/3] Add more enums for the client and process attributes of SystemApi For the client attribute, we have - MODULE_APPS for representing APKs implementing modules which are considered part of the platform - MODULE_LIBRARIES for representing jars inside modules. For the process attribute, we have - SYSTEM_SERVER for representing the system_server process. For example, @SystemApi(client=MODULE_LIBRARIES,process=ALL) actually means that the API is meant to be available for classes in the bootclasspath but not to the classes from the app classloader. Bug: 140202860 Test: m Exempt-From-Owner-Approval: cherry-picked from internal Merged-In: Iba6a564a0967e4d109164849ee6d6500d46469de (cherry picked from commit 88d5e494c48318c2de047511ea7494428e4aeb1e) Change-Id: Iba6a564a0967e4d109164849ee6d6500d46469de --- core/java/android/annotation/SystemApi.java | 22 ++++++++++++++++++++- services/Android.bp | 2 +- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/core/java/android/annotation/SystemApi.java b/core/java/android/annotation/SystemApi.java index f589cc5704b42..2cb93e4f8cea7 100644 --- a/core/java/android/annotation/SystemApi.java +++ b/core/java/android/annotation/SystemApi.java @@ -44,9 +44,24 @@ public @interface SystemApi { enum Client { /** * Specifies that the intended clients of a SystemApi are privileged apps. - * This is the default value for {@link #client}. + * This is the default value for {@link #client}. This implies + * MODULE_APPS and MODULE_LIBRARIES as well, which means that APIs will also + * be available to module apps and jars. */ PRIVILEGED_APPS, + + /** + * Specifies that the intended clients of a SystemApi are modules implemented + * as apps, like the NetworkStack app. This implies MODULE_LIBRARIES as well, + * which means that APIs will also be available to module jars. + */ + MODULE_APPS, + + /** + * Specifies that the intended clients of a SystemApi are modules implemented + * as libraries, like the conscrypt.jar in the conscrypt APEX. + */ + MODULE_LIBRARIES } enum Process { @@ -55,6 +70,11 @@ public @interface SystemApi { * This is the default value for {@link #process}. */ ALL, + + /** + * Specifies that the SystemAPI is available only in the system server process. + */ + SYSTEM_SERVER } /** diff --git a/services/Android.bp b/services/Android.bp index 72c13747e011a..e83472e0be05b 100644 --- a/services/Android.bp +++ b/services/Android.bp @@ -110,7 +110,7 @@ droidstubs { srcs: [":services-sources"], installable: false, // TODO: remove the --hide options below - args: " --show-single-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.INTERNAL,process=android.annotation.SystemApi.Process.SYSTEM_SERVER\\)" + + args: " --show-single-annotation android.annotation.SystemApi\\(client=android.annotation.SystemApi.Client.MODULE_LIBRARIES,process=android.annotation.SystemApi.Process.SYSTEM_SERVER\\)" + " --hide-annotation android.annotation.Hide" + " --hide-package com.google.android.startop.iorap" + " --hide ReferencesHidden" + From 2d04b3dec63a62c13624e11649e3cbc0f89211af Mon Sep 17 00:00:00 2001 From: Jiyong Park Date: Wed, 18 Dec 2019 12:55:09 +0900 Subject: [PATCH 3/3] Hide com.android.server package with @hide javadoc tag Metalava currently doesn't respect @Hide annoation in package statement. Use the old @hide javadoc tag there temporarily until the problem is fixed. Bug: 146466118 Test: m Test: m after adding @SystemApi(client=MODULE_LIBRARIES,client=SYSTEM_SERVER) to some of the classes under frameworks/base/services Exempt-From-Owner-Approval: cherry-pick from internal Merged-In: I4af7380917fd2808bd6774b86fd4991485d6bfc6 (cherry picked from commit 5141f3790efba0bb5e3a0843038ddcf3b11b0339) Change-Id: I4af7380917fd2808bd6774b86fd4991485d6bfc6 --- services/core/java/com/android/server/package-info.java | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/services/core/java/com/android/server/package-info.java b/services/core/java/com/android/server/package-info.java index a783e8d61a329..dd94edd53c70d 100644 --- a/services/core/java/com/android/server/package-info.java +++ b/services/core/java/com/android/server/package-info.java @@ -13,5 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + +/** + * @hide + * TODO(b/146466118) remove this javadoc tag + */ @android.annotation.Hide package com.android.server;