Pave the way for external mainline module API annotations.
This change prepares for adding mainline mode API annotations
(@CorePlatformApi etc.) supplied in external .annotated.java files so
they are not carried as patches in ojluni source files.
No real annotations are introduced in this change, and it has no
effect on the generated stubs for any of the affected targets (except,
seemingly, a few trivial whitespace changes).
Specifically, this change does the following:
- Adds a placeholder .annotated.java file (to be removed as soon as we
have any real ones).
- Adds a @libcore.api.Hide annotation we can use as an alternative to
the @hide javadoc tag.
- Changes the relevant mainline module API droidstubs rules to merge
in the .annotated.java annotations and to respect the @Hide
annotation.
- Refactors the openjdk_java_files targets to create a new category of
source file, those which are annotated for the mainline module APIs
but are not part of the public API. (The alternative to doing this
would be to move them into the public category and change all the
public API droidstubs to merge in the .annotated.java annotations
and to respect @Hide, which would be significantly more invasive.)
- Changes the relevant mainline module API droidstubs rules use the
new source categories.
Bug: 115746226
Test: `make core-platform-api-stubs core-intra-stubs core-libart+oj-intra-stubs`
Change-Id: I33e80603686112d3eb5a05debb58f13764b819b6
diff --git a/JavaLibrary.bp b/JavaLibrary.bp
index 4276511..559cb74 100644
--- a/JavaLibrary.bp
+++ b/JavaLibrary.bp
@@ -78,7 +78,11 @@
}
// The set of files in core that have been marked up with @hide and API-related
-// annotations.
+// annotations. Note that this includes the intra-core and core-platform APIs as
+// well as the public APIs. Some source files in :openjdk_mmodule_extra_files
+// are annotated by applying annotation to the .annotated.java stubs files in
+// ojluni/annotated/mmodules and rather than in the original source. See the
+// comments in openjdk_java_files.bp for more details.
filegroup {
name: "core_api_files",
srcs: [
@@ -88,6 +92,7 @@
":core_libart_api_files",
":core_simple_java_files",
":okhttp_api_files",
+ ":openjdk_mmodule_extra_files",
],
}
@@ -489,6 +494,10 @@
name: "ojluni-annotated-sdk-stubs",
path: "ojluni/annotations/sdk",
}
+droiddoc_exported_dir {
+ name: "ojluni-annotated-mmodule-stubs",
+ path: "ojluni/annotations/mmodule",
+}
// A file containing the list of tags that are "known" to us from the OpenJdk
// source code and so should not cause an error or warning.
diff --git a/luni/src/main/java/libcore/api/Hide.java b/luni/src/main/java/libcore/api/Hide.java
new file mode 100644
index 0000000..f87ff11
--- /dev/null
+++ b/luni/src/main/java/libcore/api/Hide.java
@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2018 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 libcore.api;
+
+import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that an API is hidden by default, in a similar fashion to the
+ * <pre>@hide</pre> javadoc tag.
+ *
+ * <p>Note that, in order for this to work, metalava has to be invoked with
+ * the flag {@code --hide-annotation libcore.api.Hide}.
+ *
+ * <p>This annotation should be used in {@code .annotated.java} stub files which
+ * contain API inclusion information about {@code libcore/ojluni} classes, to
+ * avoid patching the source files with <pre>@hide</pre> javadoc tags. All
+ * build targets which consume these stub files should also apply the above
+ * metalava flag.
+ *
+ * @hide
+ */
+@Target({TYPE, FIELD, METHOD, CONSTRUCTOR, ANNOTATION_TYPE})
+@Retention(RetentionPolicy.SOURCE)
+public @interface Hide {
+}
diff --git a/mmodules/core_platform_api/Android.bp b/mmodules/core_platform_api/Android.bp
index 523601d..21c6402 100644
--- a/mmodules/core_platform_api/Android.bp
+++ b/mmodules/core_platform_api/Android.bp
@@ -24,7 +24,9 @@
no_framework_libs: true,
installable: false,
- args: "--show-single-annotation libcore.api.CorePlatformApi",
+ args: "--hide-annotation libcore.api.Hide "
+ + "--show-single-annotation libcore.api.CorePlatformApi",
+ merge_inclusion_annotations_dirs: ["ojluni-annotated-mmodule-stubs"],
api_filename: "api.txt",
removed_api_filename: "removed.txt",
diff --git a/mmodules/intracoreapi/Android.bp b/mmodules/intracoreapi/Android.bp
index b54d721..e3b607c 100644
--- a/mmodules/intracoreapi/Android.bp
+++ b/mmodules/intracoreapi/Android.bp
@@ -26,7 +26,9 @@
api_filename: "api.txt",
installable: false,
- args: "--show-single-annotation libcore.api.IntraCoreApi",
+ args: "--hide-annotation libcore.api.Hide "
+ + "--show-single-annotation libcore.api.IntraCoreApi",
+ merge_inclusion_annotations_dirs: ["ojluni-annotated-mmodule-stubs"],
}
// A library containing the {public SDK + intra-core} API stubs for the
diff --git a/mmodules/libart_oj/Android.bp b/mmodules/libart_oj/Android.bp
index 807f255..28ed5cc 100644
--- a/mmodules/libart_oj/Android.bp
+++ b/mmodules/libart_oj/Android.bp
@@ -66,11 +66,14 @@
srcs: [
":core_libart_api_files",
":core_oj_api_files",
+ ":openjdk_mmodule_extra_files",
],
no_framework_libs: true,
installable: false,
- args: "--show-single-annotation libcore.api.IntraCoreApi",
+ args: "--hide-annotation libcore.api.Hide "
+ + "--show-single-annotation libcore.api.IntraCoreApi",
+ merge_inclusion_annotations_dirs: ["ojluni-annotated-mmodule-stubs"],
}
// A library containing the {public SDK + intra-core} API stubs for
diff --git a/non_openjdk_java_files.bp b/non_openjdk_java_files.bp
index d0b6d3d..0a07b23 100644
--- a/non_openjdk_java_files.bp
+++ b/non_openjdk_java_files.bp
@@ -157,6 +157,7 @@
"luni/src/main/java/javax/xml/xpath/XPathFunctionResolver.java",
"luni/src/main/java/javax/xml/xpath/XPathVariableResolver.java",
"luni/src/main/java/libcore/api/CorePlatformApi.java",
+ "luni/src/main/java/libcore/api/Hide.java",
"luni/src/main/java/libcore/api/IntraCoreApi.java",
"luni/src/main/java/libcore/mmodule/libart/DemoLibartClass.java",
"json/src/main/java/org/json/JSON.java",
diff --git a/ojluni/annotations/mmodule/Placheholder.annotated.java b/ojluni/annotations/mmodule/Placheholder.annotated.java
new file mode 100644
index 0000000..50c398f
--- /dev/null
+++ b/ojluni/annotations/mmodule/Placheholder.annotated.java
@@ -0,0 +1,5 @@
+// This file doesn't contain any code!
+// It exists to allow the :ojluni-annotated-mmodule-stubs target to exist
+// before any real .annotated.java files have been checked in.
+
+// TODO: Delete this when the first real files go in.
diff --git a/openjdk_java_files.bp b/openjdk_java_files.bp
index 3307923..c555fdc 100644
--- a/openjdk_java_files.bp
+++ b/openjdk_java_files.bp
@@ -1,3 +1,5 @@
+// Classes which are part of the public API, except where classes and
+// members are hidden using @hide javadoc tags.
filegroup {
name: "openjdk_javadoc_files",
export_to_make_var: "openjdk_javadoc_files",
@@ -1346,8 +1348,8 @@
"ojluni/src/main/java/javax/sql/StatementEventListener.java",
"ojluni/src/main/java/sun/reflect/CallerSensitive.java",
],
-
}
+
// Stubs needed to satisfy javac's dependencies when compiling lambda code. These are
// not used on Android devices or required by the Jack compiler.
//
@@ -1366,7 +1368,6 @@
"ojluni/src/lambda/java/java/lang/invoke/SerializedLambda.java",
],
}
-
filegroup {
name: "openjdk_lambda_duplicate_stub_files",
export_to_make_var: "openjdk_lambda_duplicate_stub_files",
@@ -1380,11 +1381,24 @@
],
}
-// NOTE: Files in java/lang/invoke are listed here because they're not being made public
-// until the entire package is available for use.
+// Classes which are exposed in the intra-core or core-platform APIs but not in
+// the public APIs. Unless they are annotated, these classes and all their
+// members will be exposed in all such APIs. To avoid patching the main ojluni
+// sources, these API annotations can be placed in .annotated.java stub files
+// under ojluni/annotations/mmodule. Classes must be hidden using the
+// libcore.api.Hide annotation, and then the class and the members to be exposed
+// must be annotated with libcore.api.CorePlatformApi and/or
+// libcore.api.IntraCoreApi.
filegroup {
- name: "openjdk_java_files",
- export_to_make_var: "openjdk_java_files",
+ name: "openjdk_mmodule_extra_files",
+ path: "ojluni/src/lambda/java",
+ srcs: [
+ ],
+}
+
+// Classes not exposed in any API (either public or mmodule).
+filegroup {
+ name: "openjdk_internal_files",
path: "ojluni/src/lambda/java",
srcs: [
"ojluni/src/main/java/com/sun/net/ssl/internal/ssl/X509ExtendedTrustManager.java",
@@ -1776,7 +1790,18 @@
"ojluni/src/main/java/sun/util/logging/PlatformLogger.java",
"ojluni/src/main/java/sun/util/ResourceBundleEnumeration.java",
"ojluni/src/main/java/sun/util/resources/OpenListResourceBundle.java",
+ ],
+}
+
+// All classes, whether exposed in any API or not.
+filegroup {
+ name: "openjdk_java_files",
+ export_to_make_var: "openjdk_java_files",
+ path: "ojluni/src/lambda/java",
+ srcs: [
":openjdk_javadoc_files",
+ ":openjdk_mmodule_extra_files",
+ ":openjdk_internal_files",
":openjdk_lambda_stub_files",
],
}