net.sf.staccatocommons.restrictions
Annotation Type Restriction

@Documented
@Inherited
@Retention(value=SOURCE)
@Target(value=ANNOTATION_TYPE)
public @interface Restriction

Restrictions is a meta-annotation for annotation types that express constraints over annotated elements.

Restrictions may express preconditions, postconditions or invariants, depending on the specific annotation type and on the annotated element:

• Preconditions means that client must not violate the restriction. Doing that is a client code bug, and the annotated element and its context may not behave normally. Implementors should throw a RuntimeException or any subclass of it when this occurs
• Postconditions and invariants means client code must assume the constraint the annotated element does not violate the constraint, and should not check it. If annotated element violates this postcondition, there is a bug in the implementor code. Implementors may throw an AssertionError

Annotations marked as Restriction obey the following rules

1. Restrictions should be annotation-processor-agnostic and documentation oriented, that is, its primary design goal is documenting the constraint. As a consequence, these annotations should be Documented. However, it is valid to process them
2. Restriction annotations must preserve their meaning in subtypes
3. 1. Preconditions restrictions inherited by subtypes mayrelax restrictions but must notintroduce new ones
   2. Postconditions and invariants restrictions inherited by subtypes must notrelax restrictions but mayintroduce new ones
4. 1. Restriction annotations should be explicit in code directly exposed to client, but may be implicit in the rest of the code
   2. Postconditions and invariants restrictions present on supertypes and absent on subtypes must be assumed to be still observed.
   3. Postconditions restrictions present on supertypes and absent on subtypes must be assumed to have being removed
5. Elements not annotated with restrictions in supertypes but that however observe constraints compatible with some Restriction, may be annotated with such Restriction

The concrete way this annotation is handled is by no means described here, and it depends exclusively on its static or dynamic processor. It may even not be processed at all, and server exclusively as documentation.