@Target(value={CONSTRUCTOR,METHOD}) public @interface RestrictedApi
Callers that are not whitelisted will cause a configurable compiler diagnostic. Whitelisting 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
.
public {@literal @}interface LegacyUnsafeFooBar{}
public {@literal @}interface ReviewedFooBar{
public string reviewer();
public string comments();
}
public class Foo {
{@literal @}RestrictedApi(
explanation="You could shoot yourself in the foot with Foo.bar if you aren't careful",
link="http://edsger.dijkstra/foo_bar_consider_harmful.html",
allowedOnPath="testsuite/.*", // Unsafe behavior in tests is ok.
whitelistAnnotations = {ReviewedFooBar.class},
whitelistWithWarningAnnotations = {LegacyUnsafeFooBar.class})
public void bar() {
if (complicatedCondition) {
shoot_your_foot();
} else {
solve_your_problem();
}
}
boolean complicatedCondition = true;
{@literal @}ReviewedFooBar(
reviewer="bangert",
comments="Makes sure complicatedCondition isn't true, so bar is safe!"
)
public void safeBar() {
if (!complicatedCondition) {
bar();
}
}
{@literal @}LegacyUnsafeFooBar
public void someOldCode() {
// ...
bar()
// ...
}
}
Modifier and Type | Required Element and Description |
---|---|
String |
explanation
Explanation why the API is restricted, to be inserted into the compiler output.
|
String |
link
Link explaining why the API is restricted
|
Modifier and Type | Optional Element and Description |
---|---|
String |
allowedOnPath
Allow the restricted API on paths matching this regular expression.
|
Class<? extends Annotation>[] |
whitelistAnnotations
Allow calls to the restricted API in methods or classes with this annotation.
|
Class<? extends Annotation>[] |
whitelistWithWarningAnnotations
Emit warnings, not errors, on calls to the restricted API for callers with this annotation.
|
public abstract String explanation
public abstract String link
public abstract String allowedOnPath
Leave empty (the default) to enforce the API restrictions on all paths.
public abstract Class<? extends Annotation>[] whitelistAnnotations
public abstract Class<? extends Annotation>[] whitelistWithWarningAnnotations
This should only be used if callers should aggressively move away from this API (or change to a whitelist annotation after review). Too many warnings will lead to ALL warnings being ignored, so tread very carefully.
Copyright © 2021. All rights reserved.