001package Torello.JavaDoc;
002
003/**
004 * An enumeration used by the {@link StaticFunctional} annotation for explaining
005 * non-{@code static} fields in a type.
006 * 
007 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE>
008 */
009public enum Excuse
010{
011    /**
012     * Indicates that a field inside of a class that has been decorated with the
013     * {@code StaticFunctional} annotation is being used as a "Configuration Flag" for that class.
014     * 
015     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_FLAG>
016     */
017    FLAG,
018
019    /**
020     * Indicates the field isn't marked with the {@code 'final'} modifier because it is used as a
021     * simple-configuration.
022     * 
023     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_CONFIG>
024     */
025    CONFIGURATION,
026
027    /**
028     * Indicates that an excused, non-{@code final}, field contains a singleton instance of a
029     * {@code class}, and could conceivably be changed or swapped after the class-loading phase.
030     * 
031     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_SINGLE>
032     */
033    SINGLETON,
034
035    /**
036     * Indicates that a field is excused from the {@code 'final'} modifier because that field is
037     * solely used for logging purposes.
038     * 
039     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_LOGGING>
040     */
041    LOGGING,
042
043    /**
044     * Indicates that an excused field is not marked with the {@code 'final'} modifier because it
045     * is intended to be used solely for debugging purposes (only!).
046     * 
047     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_DEBUG>
048     */
049    DEBUGGING,
050
051    /**
052     * Indicates that a field inside of a class annotated by {@code StaticFunctional}, is
053     * non-{@code final} because the field's value isn't actually loaded at class-initialization
054     * time by the {@code ClassLoader}.
055     * 
056     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_LAZY_LD>
057     */
058    LAZY_LOADING,
059
060    /**
061     * Since ensuring that the Garbage-Collector runs does not constitute program state, this excuse
062     * is provided for any field that doesn't declare the {@code 'final'} modifier because it is
063     * involved in calls to {@code System.gc()}.
064     * 
065     * <EMBED CLASS='external-html' DATA-FILE-ID=EXCUSE_GARBAGE>
066     */
067    GARBAGE_COLLECTION;
068}