1 /*
2 * EL4J, the Extension Library for the J2EE, adds incremental enhancements to
3 * the spring framework, http://el4j.sf.net
4 * Copyright (C) 2006 by ELCA Informatique SA, Av. de la Harpe 22-24,
5 * 1000 Lausanne, Switzerland, http://www.elca.ch
6 *
7 * EL4J is published under the GNU Lesser General Public License (LGPL)
8 * Version 2.1. See http://www.gnu.org/licenses/
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * For alternative licensing, please contact info@elca.ch
16 */
17 package ch.elca.el4j.util.codingsupport.annotations;
18
19 import java.lang.annotation.Retention;
20 import java.lang.annotation.RetentionPolicy;
21
22 /**
23 * States an assumption made by the annotated element's implementation.
24 * Assumptions are statements that are considered true for the purpose of
25 * writing code but whose truth is unknown.
26 *
27 * <p>The long term vision is that an automatic tool can process the source
28 * code to collect the assumptions made, permitting efficient review in case
29 * requirements change. Even in the absence of such a tool, source code
30 * information systems such as eclipse can efficiently search assumptions.
31 *
32 * <p> Assumption bear some similarity with "to do" items, but differ
33 * in that they are conditional: An assumption only needs to be removed if it is
34 * false. In contrast, a "to do" item needs to be taken care of unconditionally.
35 *
36 * <p>Assumptions that can easily be formulated as Java expressions should be
37 * stated as assertions/preconditions instead (to enable runtime checking).
38 *
39 * <p>Assumptions document code, not behavior, and are therefore not included
40 * in the API documentation. Like comments, they are discarded by the compiler.
41 *
42 * <h4>Example</h4>
43 * <pre>
44 * @assumes("the name uniquely identifies a person")
45 * Object getKey() {return this.name;}
46 * </pre>
47 *
48 * @svnLink $Revision: 3875 $;$Date: 2009-08-04 14:35:53 +0200 (Di, 04. Aug 2009) $;$Author: swismer $;$URL: https://el4j.svn.sourceforge.net/svnroot/el4j/branches/el4j_3_1/el4j/framework/modules/core/src/main/java/ch/elca/el4j/util/codingsupport/annotations/ImplementationAssumption.java $
49 *
50 * @see ch.elca.el4j.util.codingsupport.Reject
51 * @author Adrian Moos (AMS)
52 */
53 @Retention(RetentionPolicy.SOURCE)
54 public @interface ImplementationAssumption {
55 /** text describing the assumption. */
56 String value();
57 }