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.

public @interface LegacyUnsafeFooBar{}

public @interface ReviewedFooBar{
 public string reviewer();
 public string comments();
}

public class Foo {
  @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.
     allowlistAnnotations = {ReviewedFooBar.class},
     allowlistWithWarningAnnotations = {LegacyUnsafeFooBar.class})
  public void bar() {
     if (complicatedCondition) {
         shoot_your_foot();
     } else {
         solve_your_problem();
     }
  }
  boolean complicatedCondition = true;

  @ReviewedFooBar(
     reviewer="bangert",
     comments="Makes sure complicatedCondition isn't true, so bar is safe!"
  )
  public void safeBar() {
     if (!complicatedCondition) {
         bar();
     }
  }

  @LegacyUnsafeFooBar
  public void someOldCode() {
     // ...
     bar()
     // ...
  }
}