IntelliJ IDEA
 
Get IntelliJ IDEA
You are viewing the documentation for an earlier version of IntelliJ IDEA.

@Contract

Last modified: 10 August 2022

The @Contract annotation is used for defining a contract that a method must meet. This lets the IDE find problems in methods which call methods that you have annotated. You can use this annotation not only for annotating your own code but also for other existing libraries.

The @Contract annotation has two attributes — value and pure. The value attribute contains clauses describing causal relationship between arguments and the returned value.

The pure attribute is intended for methods that do not change the state of their objects, but just return a new value. If its return value is not used, removing its invocation will not affect program state or change the semantics, unless the method call throws an exception (exception is not considered to be a side effect).

A method should not be marked as pure if it does not produce a side effect by itself, but it could be used to establish the happens-before relation between an event in another thread, so that changes performed in another thread might become visible in current thread after invocation of this method. On the other hand, some synchronized methods could be marked as pure, because the purpose of synchronization here is to keep the collection internal integrity rather than to wait for an event in another thread. "Invisible" side effects (such as logging) that do not affect important program semantics are allowed.

A contract is a set of clauses that describe an input and an output. They are separated with the -> symbol: "A -> B". This forms a contract meaning that when you provide A to a method, you will always get B. Clauses in a contract must be separated with the ; (semicolon) symbol. For example: