diff options
author | Samiul Islam <samiul@google.com> | 2024-02-16 11:30:34 +0000 |
---|---|---|
committer | Samiul Islam <samiul@google.com> | 2024-02-20 17:06:08 +0000 |
commit | 9a200dde1f1f96c264c183d43800056eee937153 (patch) | |
tree | 28c7eed43d824b91202d4cea0652c21278cceee7 | |
parent | ffbd55810e145b0c5c684b74eac706fc28f0c676 (diff) | |
download | modules-utils-9a200dde1f1f96c264c183d43800056eee937153.tar.gz |
Create @RestrictedFor annotation
The annotation will be used to annotate classes and methods that are
restricted in certain environments.
Bug: 320445933
Test: atest AndroidAnnotationTests
Change-Id: I61498486641ab5a6b0510e112c7ef22e60090a17
-rw-r--r-- | java/android/annotation/RestrictedFor.java | 78 | ||||
-rw-r--r-- | javatests/android/annotation/Android.bp | 34 | ||||
-rw-r--r-- | javatests/android/annotation/AndroidManifest.xml | 23 | ||||
-rw-r--r-- | javatests/android/annotation/RestrictedForTests.java | 88 |
4 files changed, 223 insertions, 0 deletions
diff --git a/java/android/annotation/RestrictedFor.java b/java/android/annotation/RestrictedFor.java new file mode 100644 index 0000000..94a8895 --- /dev/null +++ b/java/android/annotation/RestrictedFor.java @@ -0,0 +1,78 @@ +/* + * Copyright (C) 2024 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 android.annotation; + + +import static java.lang.annotation.ElementType.TYPE; + +import java.lang.annotation.Repeatable; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Indicates if an API is restricted in certain environments. + * + * <p> + * The explicit annotation aids in surfacing the restriction to the developers of the environments + * in multiple ways: + * </p> + * + * <ul> + * <li>Metalava will consume these annotations to generate appropriate javadocs.</li> + * <li>Linters will consume these annotation to show warning to developers on their IDE.</li> + * <li>Tests will consume these annotation to verify restricted APIs have been annotated.</li> + * </ul> + * + * @hide + */ +@Target({TYPE}) +@Retention(RetentionPolicy.RUNTIME) +@Repeatable(RestrictedFor.Container.class) +public @interface RestrictedFor { + + /** List of environments where the entity is restricted. */ + Environment[] environments(); + + /** + * SDK version since when the restriction started. + * + * Possible values are defined in {@link android.os.Build.VERSION_CODES}. + */ + int from(); + + enum Environment { + /** + * See {@link android.app.sdksandbox.SdkSandboxManager} + */ + SDK_SANDBOX { + @Override + public String toString() { + return "SDK Runtime"; + } + } + } + + /** + * Container for {@link RestrictedFor} that allows it to be applied repeatedly to types. + */ + @Retention(RetentionPolicy.RUNTIME) + @Target(TYPE) + @interface Container { + RestrictedFor[] value(); + } +} diff --git a/javatests/android/annotation/Android.bp b/javatests/android/annotation/Android.bp new file mode 100644 index 0000000..f793cbb --- /dev/null +++ b/javatests/android/annotation/Android.bp @@ -0,0 +1,34 @@ +// Copyright (C) 2024 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 { + default_applicable_licenses: ["Android-Apache-2.0"], +} + +android_test { + name: "AndroidAnnotationTests", + sdk_version: "module_current", + srcs: ["*.java"], + static_libs: [ + "androidx.test.rules", + "androidx.test.runner", + "framework-annotations-lib", + "truth", + ], + libs: [ + "android.test.runner", + "framework-annotations-lib", + ], + test_suites: ["general-tests"], +} diff --git a/javatests/android/annotation/AndroidManifest.xml b/javatests/android/annotation/AndroidManifest.xml new file mode 100644 index 0000000..5284aa1 --- /dev/null +++ b/javatests/android/annotation/AndroidManifest.xml @@ -0,0 +1,23 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + ~ Copyright (C) 2022 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. + --> + +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="android.annotation.test"> + + <instrumentation android:name="androidx.test.runner.AndroidJUnitRunner" + android:targetPackage="android.annotation.test"/> +</manifest> diff --git a/javatests/android/annotation/RestrictedForTests.java b/javatests/android/annotation/RestrictedForTests.java new file mode 100644 index 0000000..a2b932f --- /dev/null +++ b/javatests/android/annotation/RestrictedForTests.java @@ -0,0 +1,88 @@ +/* + * Copyright (C) 2024 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 android.annotation; + +import static com.google.common.truth.Truth.assertThat; + +import android.annotation.RestrictedFor.Environment; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; + +@RunWith(JUnit4.class) +public class RestrictedForTests { + + @Test + public void testAnnotationAvailableInRuntime() throws Exception { + ClassWithAnnotation clz = new ClassWithAnnotation(); + RestrictedFor annotation = clz.getClass().getAnnotation(RestrictedFor.class); + + assertThat(annotation).isNotNull(); + } + + @Test + public void testAnnotationIsRepeatable() throws Exception { + ClassWithRepeatedAnnotation clz = new ClassWithRepeatedAnnotation(); + RestrictedFor[] annotations = clz.getClass().getAnnotationsByType(RestrictedFor.class); + + assertThat(annotations).hasLength(2); + } + + @Test + public void testAnnotationParameters() throws Exception { + ClassWithAnnotation clz = new ClassWithAnnotation(); + RestrictedFor annotation = clz.getClass().getAnnotation(RestrictedFor.class); + + Environment[] e = annotation.environments(); + assertThat(e).asList().containsExactly(Environment.SDK_SANDBOX); + int from = annotation.from(); + assertThat(from).isEqualTo(33); + } + + @Test + public void testAnnotationParameters_environmentToString() throws Exception { + ClassWithAnnotation clz = new ClassWithAnnotation(); + RestrictedFor annotation = clz.getClass().getAnnotation(RestrictedFor.class); + + Environment e = annotation.environments()[0]; + assertThat(e).isEqualTo(Environment.SDK_SANDBOX); + assertThat(e.toString()).isEqualTo("SDK Runtime"); + } + + @Test + public void testAnnotationParameters_environment_multipleEnvironments() throws Exception { + ClassWithMultipleEnvironment clz = new ClassWithMultipleEnvironment(); + RestrictedFor annotation = clz.getClass().getAnnotation(RestrictedFor.class); + + Environment[] e = annotation.environments(); + assertThat(e).asList().containsExactly(Environment.SDK_SANDBOX, Environment.SDK_SANDBOX); + } + + @RestrictedFor(environments=Environment.SDK_SANDBOX, from=33) + private static class ClassWithAnnotation { + } + + @RestrictedFor(environments=Environment.SDK_SANDBOX, from=0) + @RestrictedFor(environments=Environment.SDK_SANDBOX, from=0) + private static class ClassWithRepeatedAnnotation { + } + + @RestrictedFor(environments={Environment.SDK_SANDBOX, Environment.SDK_SANDBOX}, from=0) + private static class ClassWithMultipleEnvironment { + } +} |