Package org.springframework.lang

# Annotation Interface Contract

@Documented @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.

Inspired by `org.jetbrains.annotations.Contract`, this variant has been introduced in the `org.springframework.lang` package to avoid requiring an extra dependency, while still following the same semantics.

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` - the method returns a non-null new object which is distinct from any other object existing in the heap prior to method execution. If the method has no visible side effects, then we can be sure that the new object is not stored to any field/array and will be lost if the method's return value is not used.
- `this` - the method returns its qualifier value (not applicable for static methods)
- `param1, param2, ...` - 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`).

Since:
  6.2
Author:
  Sebastien Deleuze
See Also:
  - org.jetbrains.annotations.Contract
  - NullAway custom contract annotations

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`String`
`value`
Contains the contract clauses describing causal relations between call arguments and the returned value.

## Element Details

### value

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

Default:
  ""