net.sf.staccatocommons.restrictions.Restriction Maven / Gradle / Ivy
/**
* Copyright (c) 2011, The Staccato-Commons Team
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; version 3 of the License.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*/
package net.sf.staccatocommons.restrictions;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* {@link Restriction}s 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 {@link 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 {@link AssertionError}
*
*
*
* Annotations marked as {@link Restriction} obey the following rules
*
* - 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 {@link Documented}.
* However, it is valid to process them
* - Restriction annotations must preserve their meaning in
* subtypes
* -
*
* - Preconditions restrictions inherited by subtypes
* mayrelax restrictions but must
* notintroduce new ones
* - Postconditions and invariants restrictions inherited by subtypes
* must notrelax restrictions but mayintroduce
* new ones
*
*
* -
*
* - Restriction annotations should be explicit in code
* directly exposed to client, but may be implicit in the rest
* of the code
*
- Postconditions and invariants restrictions present on supertypes and
* absent on subtypes must be assumed to be still observed.
* - Postconditions restrictions present on supertypes and absent on subtypes
* must be assumed to have being removed
*
* - Elements not annotated with restrictions in supertypes but that however
* observe constraints compatible with some {@link 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.
*
*/
@Documented
@Inherited
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Restriction {
}