Module marid.intellij.annotations

Package org.jetbrains.annotations

Annotation Type Contract

@Documented
@Retention(CLASS)
@Target(METHOD)
public @interface Contract

Specifies some aspects of the method behavior depending on the arguments. Can be used by tools for advanced data flow analysis. Note that this annotation just describes how the code works and doesn't add any functionality by means of code generation.

Method contract has the following syntax:
contract ::= (clause ';')* clause
clause ::= args '->' effect
args ::= ((arg ',')* arg )?
arg ::= value-constraint
value-constraint ::= 'any' | 'null' | '!null' | 'false' | 'true'
effect ::= value-constraint | 'fail'

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
• fail - the method throws an exception, if the arguments satisfy argument constraints

Examples:

@Contract("_, null -> null") - method returns null if its second argument is null
@Contract("_, null -> null; _, !null -> !null") - 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

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
boolean	pure	Specifies that the annotated method has no visible side effects, in the following sense.
String	value	Contains the contract clauses describing causal relations between call arguments and the returned value

Element Detail

value

String value

Contains the contract clauses describing causal relations between call arguments and the returned value

Default:

""

pure

boolean pure

Specifies that the annotated method has no visible side effects, in the following sense. If its return value is not used, removing its invocation won't affect program state and change the semantics. Exception throwing is not considered to be a side effect. "Invisible" side effects (such as logging) that don't affect the "important" program semantics are allowed.

This annotation may be used for more precise data flow analysis, and to check that the method's return value is actually used in the call place.

Default:

false