Annotation Type Contract
Method contract has the following syntax:
contract ::= (clause ';')* clause
clause ::= args '->' effect
args ::= ((arg ',')* arg )?
arg ::= value-constraint
value-constraint ::= '_' | 'null' | '!null' | 'false' | 'true'
effect ::= value-constraint | 'fail' | 'this' | 'new' | 'param<N>'
The constraints denote the following:
- _ - any value
- null - null value
- !null - a value statically proved to be not-null
- true - true boolean value
- false - false boolean value
The additional return values denote the following:
- fail - the method throws an exception, if the arguments satisfy argument constraints
- new - (supported in IntelliJ IDEA since version 2018.2) the method returns a non-null new object which is distinct from any other object existing in the heap prior to method execution. If method is also pure, then we can be sure that the new object is not stored to any field/array and will be lost if method return value is not used.
- this - (supported in IntelliJ IDEA since version 2018.2) the method returns its qualifier value (not applicable for static methods)
- param1, param2, ... - (supported in IntelliJ IDEA since version 2018.2) the method returns its first (second, ...) parameter value
Examples:
@Contract("_, null -> null")
- the method returns null if its second argument is null
@Contract("_, null -> null; _, !null -> !null")
- the method returns null if its second
argument is null and not-null otherwise
@Contract("true -> fail")
- a typical assertFalse
method which throws an
exception if true
is passed to it
@Contract("_ -> this")
- the method always returns its qualifier (e.g. StringBuilder.append(String)
). @Contract("null -> fail; _ -> param1")
- the method
throws an exception if the first argument is null, otherwise it returns the first argument (e.g.
Objects.requireNonNull
).
@Contract("!null, _ -> param1; null, !null -> param2; null, null -> fail")
- the method
returns the first non-null argument, or throws an exception if both arguments are null (e.g.
Objects.requireNonNullElse
in Java 9).
This annotation is the same provided with Jetbrains annotations and used by Nullaway for verifying nullness. We copy the annotation to avoid an external dependency.
This class is internal and is hence not for public use. Its APIs are unstable and can change at any time.
-
Optional Element Summary
Optional Elements
-
Element Details
-
value
String valueContains the contract clauses describing causal relations between call arguments and the returned value.- Default:
""
-