Annotation Type StaticFunctional

  • @Retention(SOURCE)
@Target(TYPE)
public @interface StaticFunctional
    Genuine Java Annotation:
    This is the actual annotation that a user may place in a '.java' file. This annotation may only be placed on a type (or inner-type) - and only on a class or interface.

    Target:
    Specifically: @Target(ElementType.TYPE)

    has been placed on this @interface definition!    , however, the Annotation-Processor used for use of this @interface (annotation) will generate an error if it encounters a non-class or non-interface type that has had this annotation placed on it.
    Java-Annotation: A Java-Annotation for marking classes as 'Stateless Classes' - used to insert 'The Spaghetti Report' into Java Doc Pages.

    This is a marker used in Java-HTML to identify classes that do not maintain any state. Likely three out of every four classes in the Java-HTML Library are annotated with this annotation.

    The purpose of the @StaticFunnctional Annotation is to provide some amount of confidence that unexplained state-ful behavior is not occuring in the background of a class or interface. Although there are likely numerous definitions for the concept of 'Stateful Behavior', here it is used to imply that for any given set of inputs to a function, the returned-result of the function shall always be identical. Object-Oriented programming is an invaluable tool in a programmer's repertoire, but for most library and utility packages, functional programming that does not contain any 'Porgram State' is usually much easier to analyze and understand.

    The rules for the @StaticFunctional Annotation are listed, here, below. These rules are checked by the class SFProcessor at compile time for any class that utilizes the annotation. Note that the Java HTML Jar Library, which contains a META-INF directory that specifies the location of this Annotation Processor, must be in the CLASSPATH at the time of compilation in order for this checker to operate successfully.

    • There must be exactly one constructor. It must be declared using the 'private' modifier, and it must accept precisely zero arguments.
    • All methods offered by the class must use the 'static' modifier.
    • All fields inside the class must be declared both 'static' and 'final'
    • In some situations pertaining to simple or basic configurations, debugging and logging a field may be declared 'static', but not include the 'final' modifier. In such situations, if the @StaticFunctional Annotation is to be employed, those fields must be explicitly 'excused' from 'The Spaghetti Report'


    The image-capture, below, shows the use of the @StaticFunctional Annotation, including the 'Excused' (non-final) fields inside this class:

    Example @StaticFunctional Use

    When classes are annotated, as in the image-example above, the JavaDoc Upgrader Tool will insert a summary report on the stateful-ness of the class that resembles the image-capture below (if the user does, indeed, invoke the JavaDoc Upgrader). The Annotation, by iteself, will not be used by the original 'javadoc' Utility, the Upgrader must be used to get the report, below, included into the output documentation pages.

    StatelessClass Example


    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element
      String[] Excused
      Excuse[] Excuses

    • Element Detail

      • Excused

        java.lang.String[] Excused
        This must contain the names of fields in this class or interface that have been declared static, but have not been declared final.

        NOTE: The values in the 'Excused' array must be parallel to the values in the 'Excuses' array.
        Default:
        {}

      • Excuses

        Excuse[] Excuses
        This must contain instances of the Enumerated-Type 'Excuses'. These excuses should explain the reason why the named field has not been declared 'final' in any class or interface that has been marked with the @StaticFunction annotation.

        NOTE: The values in the 'Excuses' array must be parallel to the values in the 'Excused' array.
        Default:
        {}