Package: groovy.contracts

## [Java] Annotation Type Requires

- groovy.contracts.Requires

-     @Documented
      @Retention(RetentionPolicy.RUNTIME)
      @Target({ElementType.CONSTRUCTOR, ElementType.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

- - ### Element Summary

    Required Element Summary
    Type | Name and Description
    --- | ---
    `Class` | `value` Returns the closure class that evaluates the precondition expression.

    Optional Element Summary
    Type | Name and 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.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Element Detail

    - #### public 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

    - #### public Class value

      Returns the closure class that evaluates the precondition expression.

      Returns:
        the generated closure class backing the precondition

    - #### public 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