Package groovy.contracts

# Annotation Interface Requires

@Documented @Retention(RUNTIME) @Target({CONSTRUCTOR,METHOD}) @Precondition @AnnotationProcessorImplementation(RequiresAnnotationProcessor.class) @Repeatable(RequiresConditions.class) public @interface Requires

Represents a method precondition.

A precondition is a condition that must be met by clients of this class. Whenever the precondition can be satisfied, it is guaranteed that the supplier will fulfil the method's postcondition.

A method's precondition is executed as the first statement within a method call. A successor's precondition weakens the precondition of its parent class, e.g. if A.someMethod declares a precondition and B.someMethod overrides the method the preconditions are combined with a boolean OR.

Example:

       @Requires({ argument1 != argument2 && argument2 >= 0 })
       void someOperation(def argument1, def argument2)  {
         ...
       }

Since:
  4.0.0

- ## Required Element Summary

  Required Elements
  Modifier and Type
  Required Element
  Description
  `Class`
  `value`
  Returns the closure class that evaluates the precondition expression.

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `boolean`
  `direct`
  Information for readers and tools, with no effect on bytecode; ignored (implicitly `true`) for woven preconditions.
  `boolean`
  `woven`
  `true` (default): weave the precondition assertion — the current behaviour, a violating caller observes a `PreconditionViolation`.

- ## Element Details

  - ### value

    Class value
    Returns the closure class that evaluates the precondition expression.
    Returns:
      the generated closure class backing the precondition

- - ### woven

    boolean woven
    `true` (default): weave the precondition assertion — the current behaviour, a violating caller observes a `PreconditionViolation`. `false`: the obligation is already enforced (see `direct` for where) — no assertion is generated, and a violating caller observes whatever the existing enforcement does (for example the `NullPointerException` of an `Objects.requireNonNull`) rather than a `PreconditionViolation`. The annotation remains the caller's documented obligation, consumable by readers and tools (verifiers discharge it at call sites regardless of where enforcement lives). An unwoven precondition never contributes to generated assertions — including the inherited precondition weaving of overriding methods.
    Returns:
      whether the precondition assertion is generated
    Since:
      6.0.0
    Default:
      true

  - ### direct

    boolean direct
    Information for readers and tools, with no effect on bytecode; ignored (implicitly `true`) for woven preconditions. `true` (default): a hand-written check enforces the obligation in this body. `false`: the obligation is enforced by code this method executes — a validator call such as `Objects.requireNonNull` or Guava's `Preconditions`, possibly transitively — so there is no check to find in this body. Most users never set this; a verification or analysis tool unable to find the claimed enforcement is the usual prompt.
    Returns:
      whether the body itself contains the enforcement
    Since:
      6.0.0
    Default:
      true