net.sf.staccatocommons.restrictions.Restriction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of staccatissimo-restrictions Show documentation

Library of annotations that express restrictions, that can be used to indicate preconditions, postconditions and invariants over objects and messages, focused on documentation reuse.

The newest version!

/**
 *  Copyright (c) 2010-2012, The StaccatoCommons 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 {

}