Annotation Type RestrictedApi
-
@Target({CONSTRUCTOR,METHOD}) public @interface RestrictedApi
Restrict this method to callsites with a allowlist annotation.Callers that are not allowlisted will cause a configurable compiler diagnostic. Allowlisting can either allow the call outright, or make the compiler emit a warning when the API is called. Paths matching a regular expression, e.g. unit tests, can also be excluded.
The following example shows a hypothetical, potentially unsafe
Foo.bar
method. It is marked with the@RestrictedApi
annotations such that callers annotated with@LegacyUnsafeFooBar
raise a warning, whereas the@ReviewedFooBar
annotation silently allows the call.The
@LegacyUnsafeFooBar
annotation can be used to allow existing call sites until they are refactored, while prohibiting new call-sites. Call-sites determined to be acceptable, for example through code review, could be marked@ReviewedFooBar
.{@code public @interface LegacyUnsafeFooBar{} public @interface ReviewedFooBar{ public string reviewer(); public string comments(); } public class Foo {
-
-
Required Element Summary
Required Elements Modifier and Type Required Element Description java.lang.String
explanation
Explanation why the API is restricted, to be inserted into the compiler output.
-
Optional Element Summary
Optional Elements Modifier and Type Optional Element Description java.lang.String
allowedOnPath
Allow the restricted API on paths matching this regular expression.java.lang.Class<? extends java.lang.annotation.Annotation>[]
allowlistAnnotations
Allow calls to the restricted API in methods or classes with this annotation.java.lang.Class<? extends java.lang.annotation.Annotation>[]
allowlistWithWarningAnnotations
Emit warnings, not errors, on calls to the restricted API for callers with this annotation.java.lang.String
link
Optional link explaining why the API is restricted.
-
-
-
-
allowlistWithWarningAnnotations
java.lang.Class<? extends java.lang.annotation.Annotation>[] allowlistWithWarningAnnotations
Emit warnings, not errors, on calls to the restricted API for callers with this annotation.This should only be used if callers should aggressively move away from this API (or change to a allowlist annotation after review). Too many warnings will lead to ALL warnings being ignored, so tread very carefully.
- Default:
- {}
-
-