@Documented @Retention(value=CLASS) @Target(value={PARAMETER,FIELD}) public @interface CompileTimeConstant
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:
null
, or
final
and has the CompileTimeConstant
annotation.
This constraint on call sites of methods or constructors that have one or more formal parameters with this annotation is enforced by error-prone.
For example, the following code snippet is legal:
public class C {
private static final S = "Hello";
void m(@CompileTimeConstant final String s) { }
void n(@CompileTimeConstant final String t) {
m(S + " World!");
m(null);
m(t);
}
}
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 one of the following conditions:
null
, or
final
and has the CompileTimeConstant
annotation.
This constraint on fields with this annotation is enforced by error-prone.
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.
Copyright © 2021 Google LLC. All rights reserved.