Enum Excuse

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Excuse>
    public enum Excuse
extends java.lang.Enum<Excuse>
    An enumeration used by the StaticFunctional annotation for explaining non-static fields in a type.

    These explanations are placed into the JavaDoc Documentation HTML Page whenever a class or interface is declared @StaticFunctional, and contains fields which are declared static, but are not declaraed final.


    • Method Summary

       
      Convert String to Enum Constant
      Modifier and Type Method
      static Excuse valueOf​(String name)
       
      List all Enum Constants
      Modifier and Type Method
      static Excuse[] values()

      • Methods inherited from class java.lang.Enum

        clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Enum Constant Detail

      • FLAG

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse FLAG
        Indicates that a field inside of a class that has been decorated with the StaticFunctional annotation is being used as a "Configuration Flag" for that class.

        The reasons for excusing a non-final field as a FLAG are essentially the same as those for the CONFIGURATION excuse. Mainly, this excuse gives an alternate name to a similar concept, and should be used for strictly 'on' or 'off' (boolean) static and non-final fields.

      • CONFIGURATION

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse CONFIGURATION
        Indicates the field isn't marked with the 'final' modifier because it is used as a simple-configuration.

        An example of a @StaticFunctional class which designates a non-final field as a Configuration field may be found in class Scrape.

        The Scrape class is primarily a wrapper for the JDK classes inside the packages java.net & java.io.  Scrape (hopefully) reduces some of the tedium required to retrieve HTML from Web-Servers. Some web-servers like to know the exact name of a browser when returning HTML to a browser after a GET or POST command. In class Scrape, the field USER_AGENT allows the programmer to specify which browser is being mimicked.

        Yes, in a real sense, this means that Scrape is not perfectly 'stateless.' It even means that, technically, class Scrape is not really, fundamentally, thread-safe! This configuration-field is a non-final and static field because it allows the class to avoid one major pitfall: using the class doesn't requiring invoking any constructors or factory methods to create instances of class Scrape in order to use it! A simple call to Scrape.scrapePage (for instance) is sufficient.

        Remember, any pitfalls that might arise from using Scrape within multiple-threads may be easily avoided with a simple synchronized-block and some common-object lock (for instance, using the object Scrape.class as a lock). In such a scenario, if and when two different threads which are vying for use of the scraper, each of which would like to masquerade itself as different "web browser" (USER_AGENT), those threads may employ any one of a number of different synchronized-techniques to do so.

        The benefits of making a CONFIGURATION a simple non-final and static field far outweigh the costs. Forcing users to call constructor's and/or factory-methods (and then work with those instances, instead!) would make using the class feel a lot more complicated than it really needs to be.

      • SINGLETON

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse SINGLETON
        Indicates that an excused, non-final, field contains a singleton instance of a class, and could conceivably be changed or swapped after the class-loading phase.

        An example of a SINGLETON-field may be found in the class HTMLPage, as seen by the field parser declared in that class.

        It would be extremely unlikely that a programmer would need to 'swap parsers' for parsing HTML, but if such a need were to arise (which it never has), assigning a new parser to that field would allow a user to possibly optimize or manipulate HTML parsing.

      • LOGGING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse LOGGING
        Indicates that a field is excused from the 'final' modifier because that field is solely used for logging purposes.

        Both the classes Shell and GSUTIL have a field that allows the output generated by the operating-system calls they make to be sent to an internal Appendable instance for logging. Both of these classes are also declared 'stateless' using the @StaticFunctional annotation.

        As mentioned several times, rather than forcing a programmer to use constructors or factories to create instances of class Shell or GSUTIL, the methods in these classes are all declared 'static', and simply calling those methods using (for instance) Shell.CP(...) or GSUTIL.CP(...) saves a tremendous amount of time, work & complexity.

      • DEBUGGING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse DEBUGGING
        Indicates that an excused field is not marked with the 'final' modifier because it is intended to be used solely for debugging purposes (only!).

        An example of a 'stateless' class annotated with @StaticFunctional - and has designated a non-final field as a Debugging field - is the class StrCmpr.

        The class StrCmpr is just a simple conglomerate of String-utilities, similar to the Apache-Commons class StringUtils, but a little bit more comprehensive. The non-final and static field DEBUG is merely just a setting that a programmer may make use of (when necessary) to print up debug-information while that class' search loops are checking for String-matches.

        Obviously, because this field is a static and non-final field, its setting applies to any code (and even any thread!) that wants to utilize the search and test routines in StrCmpr. If one block of code in MyClassOne wants its debug steps to be printed, but code inside MyClassTwo doesn't need to do so, it really only requires a modicum of effort to turn the field 'off' (by setting it to false) immediately after the requsite debugging information has been printed.

        As mentioned elsewhere, requiring a user to call constructors or a factory-builder method for something this straight-forward makes this small amount of extra work well worth it. Furthermore, the overhead time-cost that is incurred when toggling a boolean-field true and false is extremely low.

        In a multi-threaded environment, synchronizing code on an object's monitor is extra effort, and even slightly more costly than setting the static field over and over again; however, when the debugging-phase of a development-cycle is finished, there really shouldn't be any need to use the boolean debug-flag at all, anyways.

      • LAZY_LOADING

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse LAZY_LOADING
        Indicates that a field inside of a class annotated by StaticFunctional, is non-final because the field's value isn't actually loaded at class-initialization time by the ClassLoader.

        Some classes maintain tables or lists that are stored inside data-files with the Java HTML JAR Distribution. Some of those tables contain information that is seldom (or even never) used. A class which can perform nearly all of its duties without loading a particular table, array or list from disk can save a good amount of time and memory by waiting to load ('lazily-loading') such data from disk until it is actually necessary.

        When a field is declared as excused from the 'final' modifier using the LAZY_LOADING excuse, it means that the field simply cannot be initialized by the class' static-initializers (or the ClassLoader) because, under normal operation, that field's value will likely never be used.

        An example of a field that is excused in this way may be found in class-field HTTPCodes.descriptions. Most of the 'data' that is actually needed by the methods there is already present inside the class' declaration. The data itself is only a few brief arrays. However, there is also a String[]-Array of "descriptions" - that is of little use to most programs, and normal operation. Unless a programmer has decided to start printing text-descriptions of HTTP Error-Codes that can occur when connecting to web-servers, this String[]-Array field is would never actually be needed, though neither would its value ever actually populated from disk!

        If the need does arise, the private descriptions array is loaded from the JAR file, and assigned to that internal, private and non-final field. This really doesn't 'violate the expressed contract' of the @StaticFunctional annotation, but rather simply provides a little leeway.

      • GARBAGE_COLLECTION

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final Excuse GARBAGE_COLLECTION
        Since ensuring that the Garbage-Collector runs does not constitute program state, this excuse is provided for any field that doesn't declare the 'final' modifier because it is involved in calls to System.gc().

        Any field in a class which is excused as non-final because it is part of an effort to invoke the Java Garbage Collector directly is generally of little relevance among independent code-blocks, or even among independent threads.

        Processing HTML can occasionally create many thousands of instances of HTMLNode's and the external JavaParser library creates an even greater number of AST (Abstract Syntax Tree) nodes.

        Forcing the JRE to run its garbage-collection routines more often than it normally would does require a very minor amount of "Program State." The purpose of the @StaticFunctional is to assert that a class is stateless, which is almost nearly true - with the exception of requests for keeping up with calls to System.gc()

    • Method Detail

      • values

        🡅  🡇  ⇈   🗕  🗗  🗖 
        public static Excuse[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (Excuse c : Excuse.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        🡅  ⇈   🗕  🗗  🗖 
        public static Excuse valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null