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