001package Torello.JavaDoc.Annotations;
002
003import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;
004
005import java.lang.annotation.*;
006
007
008// @StaticFunctional Annotation
009// 
010// EXPORTS:
011//      public Excuse[] excuses() default {};
012//      public String[] excused() default {};
013// 
014// * Torello.JDUInternal.SimpleFeatures.StatelessClasses
015//      This class is the "Work-Horse" for the Static-Function JDU-API User-Annotation.  This class
016//      does the actual work of inserting an HTML-Message into a Java-Doc '.html'-File which 
017//      explains that the User wants to inform his/her user's that a particular class/type does not
018//      maintain any state.
019
020/**
021 * <B STYLE='color:darkred;'>Java-Annotation:</B>
022 * 
023 * A Java-Annotation for marking classes as 'Stateless Classes' -  used to insert 'The Spaghetti
024 * Report' into Java Doc Pages.
025 * 
026 * <EMBED CLASS='external-html' DATA-FILE-ID=STATIC_FUNC>
027 */
028@Retention(RetentionPolicy.SOURCE)
029@Target(ElementType.TYPE)
030public @interface StaticFunctional
031{
032    /**
033     * This must contain the names of fields in this {@code class} or {@code interface} that
034     * have been declared {@code static}, but have not been declared {@code final}.
035     * 
036     * <BR /><BR /><DIV CLASS=JDHint>
037     * The values in the {@code 'Excused'} array must be parallel to the values in the
038     * {@code 'Excuses'} array.
039     * </DIV>
040     */
041    String[] Excused() default { };
042
043    /**
044     * This must contain instances of the Enumerated-Type {@code 'Excuses'}.  These excuses
045     * should explain the reason why the named field has not been declared {@code 'final'} in any
046     * {@code class} or {@code interface} that has been marked with the {@code @StaticFunction}
047     * annotation.
048     * 
049     * <BR /><BR /><DIV CLASS=JDHintAlt>
050     * The values in the {@code 'Excuses'} array must be parallel to the values in the
051     * {@code 'Excused'} array.
052     * </DIV>
053     */
054    Excuse[] Excuses() default { };
055
056
057    /**
058     * An enumeration used by the {@link StaticFunctional} annotation for explaining
059     * non-{@code static} fields in a type.
060     * 
061     * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE>
062     */
063    public enum Excuse
064    {
065        /**
066         * Indicates that a field inside of a class that has been decorated with the
067         * {@link StaticFunctional} annotation is being used as a "Configuration Flag" for that class.
068         * 
069         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_FLAG>
070         */
071        FLAG,
072
073        /**
074         * Indicates the field isn't marked with the {@code 'final'} modifier because it is used as a
075         * simple-configuration.
076         * 
077         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_CONFIG>
078         */
079        CONFIGURATION,
080
081        /**
082         * Indicates that an excused, non-{@code final}, field contains a singleton instance of a
083         * {@code class}, and could conceivably be changed or swapped after the class-loading phase.
084         * 
085         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_SINGLE>
086         */
087        SINGLETON,
088
089        /**
090         * Indicates that a field is excused from the {@code 'final'} modifier because that field is
091         * solely used for logging purposes.
092         * 
093         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_LOGGING>
094         */
095        LOGGING,
096
097        /**
098         * Indicates that an excused field is not marked with the {@code 'final'} modifier because it
099         * is intended to be used solely for debugging purposes (only!).
100         * 
101         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_DEBUG>
102         */
103        DEBUGGING,
104
105        /**
106         * Indicates that a field inside of a class annotated by {@code StaticFunctional}, is
107         * non-{@code final} because the field's value isn't actually loaded at class-initialization
108         * time by the {@code ClassLoader}.
109         * 
110         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_LAZY_LD>
111         */
112        LAZY_LOADING,
113
114        /**
115         * Since ensuring that the Garbage-Collector runs does not constitute program state, this excuse
116         * is provided for any field that doesn't declare the {@code 'final'} modifier because it is
117         * involved in calls to {@code System.gc()}.
118         * 
119         * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_GARBAGE>
120         */
121        GARBAGE_COLLECTION;
122    }
123}