@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) {
...
}
| Type | Name and Description |
|---|---|
Class |
valueReturns the closure class that evaluates the precondition expression. |
| Type | Name and Description |
|---|---|
boolean |
directInformation for readers and tools, with no effect on bytecode; ignored (implicitly true) for woven preconditions. |
boolean |
woventrue (default): weave the precondition assertion — the current
behaviour, a violating caller observes a
PreconditionViolation.
|
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 the closure class that evaluates the precondition expression.
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.