com.google.errorprone.annotations

Annotation Type RestrictedApi

@Target(value={CONSTRUCTOR,METHOD})
public @interface RestrictedApi

Restrict this method to callsites with a whitelist annotation.

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()
      // ...
   }
 }
 

Required Element Summary

Required Elements

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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	allowedOnPath Allow the restricted API on paths matching this regular expression.
String	checkerName Very short name for the diagnostic message.
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.

Element Detail

explanation

public abstract String explanation

Explanation why the API is restricted, to be inserted into the compiler output.

link

public abstract String link

Link explaining why the API is restricted

checkerName

public abstract String checkerName

Very short name for the diagnostic message. Used in error-prone.

Default:

"RestrictedApi"

allowedOnPath

public abstract String allowedOnPath

Allow the restricted API on paths matching this regular expression.

Leave empty (the default) to enforce the API restrictions on all paths.

Default:

""

whitelistAnnotations

public abstract Class<? extends Annotation>[] whitelistAnnotations

Allow calls to the restricted API in methods or classes with this annotation.

Default:

{}

whitelistWithWarningAnnotations

public abstract Class<? extends Annotation>[] whitelistWithWarningAnnotations

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 whitelist annotation after review). Too many warnings will lead to ALL warnings being ignored, so tread very carefully.

Default:

{}