Annotation Type CompileTimeConstant


@Documented @Retention(CLASS) @Target({PARAMETER,FIELD}) public @interface CompileTimeConstant
Annotation for method parameter and class field declarations, which denotes that corresponding actual values must be compile-time constant expressions.

When the formal parameter of a method or constructor is annotated with the CompileTimeConstant type annotation, the corresponding actual parameter must be an expression that satisfies one of the following conditions:

  1. The expression is one for which the Java compiler can determine a constant value at compile time, or
  2. the expression consists of the literal null, or
  3. the expression consists of a single identifier, where the identifier is a formal method parameter or class field that is declared final and has the CompileTimeConstant annotation, or
  4. the expression is a String, and formed from the concatenation of symbols which meet these conditions, or
  5. the expression is a ternary condition, where both branches satisfy these conditions, or
  6. the expression is an immutable collection with all values known to satisfy these conditions (for example, ImmutableSet.of("a", "b", "c")).

For example, the following code snippet is legal:


 public class C {
   private static final String S = "Hello";
   void m(@CompileTimeConstant final String s) {}
   void n(@CompileTimeConstant final String t) {
     m(S + " World!");
     m(null);
     m(t);
   }
   void o(boolean enabled) {
     m(enabled ? "on" : "off");
   }
 }
 

In contrast, the following is illegal:


 public class C {
   void m(@CompileTimeConstant final String s) {}
   void n(String t) {
     m(t);
   }
 }
 

When a class field is annotated with the CompileTimeConstant type annotation, the field must also be declared to be final, and the corresponding initialised value must be an expression that satisfies the conditions above.

For example, the following code snippet is legal:


 public class C {
   @CompileTimeConstant final String s;
   public C(@CompileTimeConstant String s) {
     this.s = s;
   }
   void m(@CompileTimeConstant final String s) {}
   void n() {
     m(s);
   }
 }
 

In contrast, the following are illegal:


 public class C {
   @CompileTimeConstant String S;
   public C(@CompileTimeConstant String s) {
     this.S = s;
   }
   void m(@CompileTimeConstant final String s) { }
   void n() {
     m(S);
   }
 }
 

 public class C {
   @CompileTimeConstant final String S;
   public C(String s) {
     this.S = s;
   }
 }
 

Compile-time constant values are implicitly under the control of the trust domain of the application whose source code they are part of. Hence, this annotation is useful to constrain the use of APIs that may only be safely called with values that are under application control.

The current implementation of the @CompileTimeConstant checker cannot reason about more complex scenarios, for example, returning compile-time-constant values from a method, or storing compile-time-constant values in a collection. APIs will typically accommodate such use cases via domain-specific types that capture domain-specific aspects of trustworthiness that arise from values being under application control.

These constraints are enforced by error-prone.