Package Torello.JavaDoc.Messager
Interface Where_Am_I
-
public interface Where_Am_I
This interface is designed to be implemented, strictly, by Java'enum'
Types. The constants ofenum's
which implement the'Where_Am_I'
interface are intended to be used for BOTH giving a name to AND providing a simple description of the various points of program execution in a large scale Java-Application.
Hi-Lited Source-Code:- View Here: Torello/JavaDoc/Messager/Where_Am_I.java
- Open New Browser-Tab: Torello/JavaDoc/Messager/Where_Am_I.java
File Size: 3,182 Bytes Line Count: 79 '\n' Characters Found
-
-
Field Summary
Fields Modifier and Type Field Description static String
LABEL_COLOR
This field holds the Text-Color & Text Background-Color for the Labels which are printed to the Terminal-Window.
-
Method Summary
Returns a description for this location; must be implemented Modifier and Type Method Description String
getDescription()
Builds a formatted description string for use in enum constructors Modifier and Type Method Description static String
generateDescriptionStr(Enum<?> enumConstant, String categoryTitle, String description)
Formats the description with indentation; used internally by Messager Modifier and Type Method Description default String
messagerString(int indentation)
Prints the current location of program exeuction to an outputString
.
-
-
-
Field Detail
-
LABEL_COLOR
static final java.lang.String LABEL_COLOR
This field holds the Text-Color & Text Background-Color for the Labels which are printed to the Terminal-Window. Labels which use this color are utilized for rendering & displaying Program-Execution Location - specifically: "Where am I?" in the application which is being executed.- Code:
- Exact Field Declaration Expression:
static final String LABEL_COLOR = RED_BKGND + BWHITE;
-
-
Method Detail
-
messagerString
default java.lang.String messagerString(int indentation)
Prints the current location of program exeuction to an outputString
.- Parameters:
indentation
- The number / amount of Space-Characters (' '
) to use when indenting the Program-Execution Location-Text which is being printed to the Terminal-Window.- Returns:
- An output
String
which has been decorated using the UNIX-Terminal Color-Codes (offered in class'C'
) and explicates the Program / Applications current execution path / location. - Code:
- Exact Method Body:
return StrIndent.indent(this.getDescription(), indentation);
-
getDescription
java.lang.String getDescription()
To implement thegetDescription()
method required by theWhere_Am_I
interface, you must define anenum
that contains the following:- A
private final String description;
field - A constructor that initializes this field by calling
Where_Am_I.generateDescription(...)
- An implementation of
getDescription()
that returns the description
This approach enables simple, readable calls to yourMessager
methods, using enum constants to represent specific program locations.
For example:
Example:
public enum MyModule implements Torello.JavaDoc.Messager.Where_Am_I { // The "Where_Am_I" Enum-Constants. These may be passed to a Messager's error methods. ClassLocation1("This does some checking"), ClassLocation2("This does some data writing"); // All instances of Where_Am_I ought to define a field for "getDescription()"" private final String description; // This constructor computes the description and saves it to the internal field MyModule(String rawDescription) { this.description = Where_Am_I.generateDescription(this, "My Module 1", rawDescription); } // This is THE ONLY OBLIGATORY method located in the Where_Am_I interface. public String getDescription() { return this.description; } }
With this setup, your code can simply call:
Example:
// Checking for an error case in your code. If an error is detected, just pass the // Enum-Constant that correlates to the location in your code where this error was detected. // When the Messager prints this error, it shall include a brief header explaining the exact // location in the code where this error has occured. if (myBool == left) Messager.userErrorContinue( "Hey, your boolean turned out to be `left` rather than true or false!\n" + "How did you acheive that?", MyModule.ClassLocation1 );
- Returns:
- Returns the fully formatted description string that represents the program-execution
location corresponding to this enum constant.
This string is later used by the Messager class to label assertion-failure or user-error messages, typically as an indented header.
- A
-
generateDescriptionStr
static java.lang.String generateDescriptionStr (java.lang.Enum<?> enumConstant, java.lang.String categoryTitle, java.lang.String description)
Generates a fully formatted description string for a particular enum constant that represents a location in the user’s code.
This method is designed to be called from the constructor of anenum
that implementsWhere_Am_I
. It creates a standardized string used byMessager
to show clear and labeled execution locations during error reporting.
The generated string includes the enum name, a user-defined category label, and a wrapped description, all aligned and indented for clarity.- Parameters:
enumConstant
- The enum constant representing the code location. Its name will be used in the formatted output.categoryTitle
- A short label (e.g., "Parser Phase", "My Module") describing the module or context of the enum location.description
- A detailed explanation of what this program location represents. This text is automatically wrapped and indented.- Returns:
- Returns a formatted, indented string that includes:
- The category title as a label (e.g., "My Module", "Parser Phase")
- The enum constant name (e.g.,
ClassLocation1
) - The wrapped user-provided description text
This output is later consumed by thegetDescription()
method in user-defined enums, and ultimately used byMessager
to provide helpful error context. - Code:
- Exact Method Body:
final String title = ' ' + categoryTitle + ' '; return StrIndent.indentAfter2ndLine( LABEL_COLOR + title + RESET + " [" + BCYAN + enumConstant.name() + RESET + "]: " + StrPrint.wrap(description, 60, 80) + '\n', title.length() + 1, // "+1" Space-Character true, true );
-
-