This directory contains annotated stub files which can be merged into the main source files by metalava when it is producing API stubs. This mechanism is used instead of adding the annotations to the main source files, to avoid carrying patches against the upstream sources.

Directory structure

libcore/ojluni/annotations/sdk:

• Contains annotations to be included in the public SDK, for example annotations specifying additional details about method contracts.

libcore/ojluni/annotations/sdk/nullability:

• Contains annotations to be included in the public SDK specifically relating to nullability. Adding an annotated stub file to this subdirectory will cause the annotations to be validated for correctness and completeness.
• To add some new files under this directory:
  1. make openjdk-sdk-stubs-no-javadoc
  2. for FILE in your/package/and/Class.java another/package/AnotherClass.java; do unzip out/soong/.intermediates/libcore/openjdk-sdk-stubs-no-javadoc/android_common/metalava/openjdk-sdk-stubs-no-javadoc-stubs.srcjar ${FILE} -d libcore/ojluni/annotations/sdk/nullability/ && mv libcore/ojluni/annotations/sdk/nullability/$FILE libcore/ojluni/annotations/sdk/nullability/${FILE/%.java/.annotated.java}; done
  3. Add nullability annotations to the new files.
• To see the effect of the files under this directory:
  1. make api-stubs-docs
  2. Look for the file under out/soong/.intermediates/frameworks/base/api-stubs-docs/android_common/stubsDir/

libcore/ojluni/annotations/mmodule:

• Contains annotations which determine what is included in the core-platform and intra-core APIs. See the documentation in libcore/openjdk_java_files.bp.
• To add some new files under this directory:
  1. In libcore/openjdk_java_files.bp, move the files from the openjdk_internal_files filegroup to openjdk_mmodule_extra_files. DO NOT check in this change, it will have undesirable consequences until you reach step 4, below.
  2. make openjdk-mmodule-stubs-no-javadoc
  3. FILES="your/package/and/Class.java another/package/AnotherClass.java"; for FILE in $FILES; do mkdir -p libcore/ojluni/annotations/mmodule/$(dirname ${FILE}) && unzip out/soong/.intermediates/libcore/openjdk-mmodule-stubs-no-javadoc/android_common/metalava/openjdk-mmodule-stubs-no-javadoc-stubs.srcjar ${FILE} && mv ${FILE} libcore/ojluni/annotations/mmodule/${FILE/%.java/.annotated.java}; done
  4. Add @libcore.api.Hide to each class, methods and fields in the new files. This will prevent it from being added to the public API. A JavaDoc @hide tag will not work as metalava will ignore javadoc from the stub files.
  5. Add @android.annotation.SystemApi(client = MODULE_LIBRARIES) and @libcore.api.IntraCoreApi as desired to the classes and members.
• To see the effect of the files under this directory:
  1. make make core-platform-api-stubs core-intra-stubs
  2. Look for the files under out/soong/.intermediates/libcore/mmodules/core_platform_api/core-platform-api-stubs/android_common/stubsDir/ and out/soong/.intermediates/libcore/mmodules/intracoreapi/core-intra-stubs/android_common/stubsDir