- All Implemented Interfaces:
An enumeration used by the
StaticFunctionalannotation for explaining non-
staticfields in a type.
These explanations are placed into the JavaDoc Documentation HTML Page whenever a
interfaceis declared @StaticFunctional, and contains fields which are declared
static, but are not declaraed final.
- View Here: Torello/HTML/Tools/JavaDoc/Excuse.java
- Open New Browser-Tab: Torello/HTML/Tools/JavaDoc/Excuse.java
Convert String to Enum Constant Modifier and Type Method
List all Enum Constants Modifier and Type Method
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
Enum Constant Detail
FLAGIndicates that a field inside of a class that has been decorated with the
StaticFunctionalannotation is being used as a "Configuration Flag" for that class.
The reasons for excusing a non-
finalfield as a
FLAGare essentially the same as those for the
CONFIGURATIONexcuse. Mainly, this excuse gives an alternate name to a similar concept, and should be used for strictly 'on' or 'off' (
public static final Excuse CONFIGURATIONIndicates the field isn't marked with the
'final'modifier because it is used as a simple-configuration.
An example of a
@StaticFunctionalclass which designates a non-final field as a
Configurationfield may be found in class
Scrapeclass is primarily a wrapper for the JDK classes inside the packages
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
POSTcommand. In class
Scrape, the field
USER_AGENTallows the programmer to specify which browser is being mimicked.
Yes, in a real sense, this means that
Scrapeis not perfectly 'stateless.' It even means that, technically, class
Scrapeis not really, fundamentally, thread-safe! This configuration-field is a non-
staticfield 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
Scrapein order to use it! A simple call to
Scrape.scrapePage(for instance) is sufficient.
Remember, any pitfalls that might arise from using
Scrapewithin multiple-threads may be easily avoided with a simple
synchronized-block and some common-object lock (for instance, using the object
Scrape.classas 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
CONFIGURATIONa simple non-
staticfield 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.
SINGLETONIndicates 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
parserdeclared 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.
LOGGINGIndicates that a field is excused from the
'final'modifier because that field is solely used for logging purposes.
Both the classes
GSUTILhave a field that allows the output generated by the operating-system calls they make to be sent to an internal
Appendableinstance for logging. Both of these classes are also declared 'stateless' using the
As mentioned several times, rather than forcing a programmer to use constructors or factories to create instances of class
GSUTIL, the methods in these classes are all declared
'static', and simply calling those methods using (for instance)
GSUTIL.CP(...)saves a tremendous amount of time, work & complexity.
DEBUGGINGIndicates 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
Debuggingfield - is the class
StrCmpris just a simple conglomerate of
String-utilities, similar to the Apache-Commons class
StringUtils, but a little bit more comprehensive. The non-
DEBUGis 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
Obviously, because this field is a
finalfield, 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
MyClassOnewants its debug steps to be printed, but code inside
MyClassTwodoesn'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
falseis 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
staticfield 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
booleandebug-flag at all, anyways.
public static final Excuse LAZY_LOADINGIndicates that a field inside of a class annotated by
StaticFunctional, is non-
finalbecause the field's value isn't actually loaded at class-initialization time by the
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_LOADINGexcuse, 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
descriptionsarray is loaded from the JAR file, and assigned to that internal,
finalfield. This really doesn't 'violate the expressed contract' of the
@StaticFunctionalannotation, but rather simply provides a little leeway.
public static final Excuse GARBAGE_COLLECTIONSince 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
Any field in a class which is excused as non-
finalbecause 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.
MainFilesProcessorhas a field that is excused as non-final because it is merely keeping a count on the number of times that its main entry-point method has been invoked. Processing HTML can occasionally create many thousands of instances of
HTMLNode'sand the external
JavaParserlibrary 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
@StaticFunctionalis to assert that a class is stateless, which is almost nearly true - with the exception of requests for keeping up with calls to
valuesReturns 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);
- an array containing the constants of this enum type, in the order they are declared
valueOfReturns 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.)
name- the name of the enum constant to be returned.
- the enum constant with the specified name
java.lang.IllegalArgumentException- if this enum type has no constant with the specified name
java.lang.NullPointerException- if the argument is null