java.lang.Object
- Torello.JavaDoc.Messager.Messager

public class Messager
extends java.lang.Object

The Messager class is the top-level interface for emitting structured messages, warnings, and assertion failures to the user terminal. It exposes a static API (e.g., Messager.userError(...)) that can be called from anywhere in the application without requiring an explicit instance.

Thread-Local Field for Global, Thread-Safe, Accessibility

Internally, the Messager class uses a ThreadLocal<Messager> field to enable thread-isolated behavior while preserving global accessibility. This design allows for safe use in multi-threaded environments (such as future parallel tools), without requiring developers to pass around explicit Messager instances just to emit error messages.

This internal infrastructure delegates responsibility to three supporting classes:

PrintRecord — Maintains reusable buffers and context-state
PrintHeading — Renders headers, including information about program-execution locaton
PrintMessage — Assembles and prints complete message blocks to the terminal

The Messager was not originally designed to be thread-safe. However, the introduction of ThreadLocal isolation now ensures thread safety without altering its programming model.

A future release may introduce an explicit MsgInstance class for direct instancing, but such a design has not yet been implemented.

The following table lists all Method Parameters accepted by the core messaging functions provided by this class:

assertFail
assertFailContinue
userErrorHalt
userErrorContinue
userErrorContinueST
warning

Method Parameters

Parameter	Explanation
`String message`	A human-readable explanation describing the problem or warning condition being reported.
`String signature`	A textual representation of the method, field, or program element where the issue occurred. This parameter is especially useful in situations where no formal `Entity` instance is available. It may include a fully qualified method signature or field reference, as needed.
`Throwable t`	If the failure or warning is caused (or partially caused) by a caught `Exception` or `Error`, the relevant `Throwable` instance may be passed here. Its message and/or stack trace will be included in the terminal output.
`Where_Am_I WHERE_AM_I`	An instance of the `Where_Am_I` enumeration, indicating the current execution-path location in the application. This value is typically consumed by `PrintHeading`, which renders visual banners that mark positional context within terminal output.

Hi-Lited Source-Code:

View Here: Torello/JavaDoc/Messager/Messager.java
Open New Browser-Tab: Torello/JavaDoc/Messager/Messager.java

File Size: 17,185 Bytes Line Count: 478 '\n' Characters Found

Field Summary

Fields
Modifier and Type Field

static boolean DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL

Method Summary

Initialize a Thread-Local Messager Instance

Modifier and Type	Method
`static void`	`initializeThreadLocalInstance(int verbosityLevel, Appendable logAppendable)`

Print Text to Terminal
Modifier and Type	Method
`static void`	`print(String s)`
`static void`	`println()`
`static void`	`println(String s)`

Print Text for Lower Verbosity Settings
Modifier and Type	Method
`static void`	`printQuiet(String s)`
`static void`	`printSilent(boolean dotOrNewLine)`

Set Current Program Location
Modifier and Type	Method
`static void`	`setCurrentFileName(String fName, String fNameKind)`
`static void`	`setDeclaration(Declaration declaration)`
`static void`	`setTopDescriptionSection()`

Report User Error
Modifier and Type	Method
`static void`	`userErrorContinue(String message, String signature, Where_Am_I WHERE_AM_I)`
`static void`	`userErrorContinue(String message, Where_Am_I WHERE_AM_I)`
`static void`	`userErrorContinue(Throwable t, String message, Where_Am_I WHERE_AM_I)`
`static void`	`userErrorContinueST(Throwable t, String message, Where_Am_I WHERE_AM_I)`

Report User Error and Exit
Modifier and Type	Method
`static Error`	`userErrorHalt(String message, Where_Am_I WHERE_AM_I)`
`static Error`	`userErrorHalt(Throwable t, String message, Where_Am_I WHERE_AM_I)`

Report Warning
Modifier and Type	Method
`static void`	`warning(String message, Where_Am_I WHERE_AM_I)`

Report Assertion Failure and Exit
Modifier and Type	Method
`static Error`	`assertFail(String message, String signature, Where_Am_I WHERE_AM_I)`
`static Error`	`assertFail(String message, Where_Am_I WHERE_AM_I)`
`static Error`	`assertFail(Throwable t, String message, String signature, Where_Am_I WHERE_AM_I)`
`static Error`	`assertFail(Throwable t, String message, Where_Am_I WHERE_AM_I)`

Report Assertion Failure (Non-Fatal)
Modifier and Type	Method
`static void`	`assertFailContinue(String message, Where_Am_I WHERE_AM_I)`
`static void`	`assertFailContinue(Throwable t, String message, Where_Am_I WHERE_AM_I)`

Error State Query
Modifier and Type	Method
`static boolean`	`hadErrors()`

Conditional Output Checkpoint
Modifier and Type	Method
`static void`	`ifLogCheckPointLog()`
`static void`	`ifVerboseAppendVerbose()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL
  
  🡇 ⇈ ⮫ 🗕 🗗 🗖
```
public static boolean DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL
```
  When TRUE, requests that the stack trace be printed to terminl output for any Assertion-Failure Error-Message which contains an Exception-Throw
  Code:
  
  Exact Field Declaration Expression:
  
  public static boolean DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL = true;

Method Detail

initializeThreadLocalInstance

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void initializeThreadLocalInstance
            (int verbosityLevel,
             java.lang.Appendable logAppendable)

Initializes the ThreadLocal<Messager> instance for the current thread.

This method must be called exactly once per thread, before any of the static Messager printing methods (such as userError, assertionFailure, etc.) are invoked. It constructs and wires together the internal helper classes PrintRecord, PrintHeading, and PrintMessage, and binds the resulting Messager object to the current thread using ThreadLocal.set().

This design avoids the need to explicitly pass around Messager instances across the application and enables safe, isolated message formatting per thread. This is particularly useful for tools that may one day process multiple source files or build artifacts in parallel (e.g., future parallelization of the JDU tool).

This method must not be called more than once on the same thread. Doing so will result in an InternalError, as re-initialization would overwrite the existing Messager instance and compromise internal state.

Parameters:

verbosityLevel - The verbosity level for message output (must be between 0 and 3 inclusive). Higher levels enable more verbose diagnostic output.

logAppendable - The Appendable to which log output should be written. May be null if no log file output is needed. If so, Output-Text is not saved to disk.

Throws:

java.lang.InternalError - if this method is called more than once per thread and different assigned values to 'verbosityLevel' or 'logAppendable' are provided on the separate invocations.

This Error will also throw if the verbosityLevel is out of range

Code:

Exact Method Body:

 Messager m = tlInstance.get();


 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // Newer Addition: This method may be invoked multiple times
 // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
 // 
 // In order to facilitate calling some of the JDU's Features before the Upgrader has 
 // started running - which in the partiular case that forced this new addition was 
 // handling an Error by the File-HiLiter inside the "MoreHiliting" Class - the Messager 
 // has to be initialized before the Upgrader even starts it's primary "upgrade()" Method.
 // 
 // The default solution is to allow this method to be called as many times as are needed,
 // with the minor caveat that if the input values change in any way shape or form, then
 // an InternalError shall throw.

 if (m != null)
 {
     final boolean eqV = (m.printRecord.verbosityLevel == verbosityLevel);
     final boolean eqL = m.printRecord.checkEqualsLogAppendable(logAppendable);

     if (eqV && eqL) return;

     final String vStr = eqV
         ? ""
         :   "The input Verbosity-Level [" + verbosityLevel + "], does not equal the " +
             "previously assigned Verbosity-Level [" + m.printRecord.verbosityLevel + "]\n";

     final String lStr = eqL
         ? ""
         :   "The input Log-Appendable is a different instance / reference Object than " +
             "the previously assigned Log-Appendable.\n";

     throw new InternalError(
         "Messager.initializeThreadLocalInstance(int, Appendable) has been called " +
         "multiple times.  On this invocation:\n" + vStr + lStr
     );
 }

 if ((verbosityLevel < 0) || (verbosityLevel > 3)) throw new InternalError(
     "verbosityLevel=" + verbosityLevel + ", " +
     "but it must be between 0 and 3."
 );

 final PrintRecord   printRecord     = new PrintRecord(verbosityLevel, logAppendable);
 final PrintHeading  printHeading    = new PrintHeading(printRecord);
 final PrintMessage  printMessage    = new PrintMessage(printRecord, printHeading);
 final Messager      messager        = new Messager(printRecord, printMessage);

 tlInstance.set(messager);

print

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void print(java.lang.String s)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.print(s);

println

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void println(java.lang.String s)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.println(s);

println

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void println()

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.println();

printQuiet

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void printQuiet(java.lang.String s)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 if (m.printRecord.verbosityLevel == 1) m.printRecord.screenWriterSW.print(s);

printSilent

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void printSilent(boolean dotOrNewLine)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 if (m.printRecord.verbosityLevel == 0)
     m.printRecord.screenWriterSW.print(dotOrNewLine ? '.' : '\n');

ifVerboseAppendVerbose

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void ifVerboseAppendVerbose()

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 if (m.printRecord.verbosityLevel == 3)
     m.printRecord.screenWriterSW.print(MsgVerbose.getAndClear());

warning

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void warning(java.lang.String message,
                           Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.WARNING(message, WHERE_AM_I);
 m.printRecord.writeSBToScreen();

assertFail

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error assertFail(java.lang.String message,
                                         Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     null,   // signature
     true,   // FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new AssertFail();

assertFail

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error assertFail(java.lang.String message,
                                         java.lang.String signature,
                                         Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     signature,
     true, // FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new AssertFail();

assertFail

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error assertFail(java.lang.Throwable t,
                                         java.lang.String message,
                                         Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,
     message,
     null,   // signature
     true,   // FATAL
     DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL,
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new AssertFail();

assertFail

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error assertFail(java.lang.Throwable t,
                                         java.lang.String message,
                                         java.lang.String signature,
                                         Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,
     message,
     signature,
     true,   // FATAL
     DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL,
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new AssertFail();

assertFailContinue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void assertFailContinue(java.lang.String message,
                                      Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     null,   // signature
     false,  // NON-FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

assertFailContinue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void assertFailContinue(java.lang.Throwable t,
                                      java.lang.String message,
                                      Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,
     message,
     null,   // signature
     false,  // NON-FATAL
     false,  // Don't Show Stack-Trace
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

userErrorHalt

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error userErrorHalt(java.lang.String message,
                                            Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     null,       // signature    
     true,       // FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new MessagerGeneratedError();

userErrorHalt

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static java.lang.Error userErrorHalt(java.lang.Throwable t,
                                            java.lang.String message,
                                            Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,          // Exception that was thrown
     message,    // THE MESSAGE
     null,       // signature    
     true,       // FATAL
     true,       // Show Stack-Trace
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();
 throw new MessagerGeneratedError();

userErrorContinue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void userErrorContinue(java.lang.String message,
                                     Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     null,   // signature
     false,  // NON-FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

userErrorContinue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void userErrorContinue(java.lang.String message,
                                     java.lang.String signature,
                                     Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     message,
     signature,
     false, // NON-FATAL
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

userErrorContinue

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void userErrorContinue(java.lang.Throwable t,
                                     java.lang.String message,
                                     Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,
     message,
     null,   // signature
     false,  // NON-FATAL
     false,  // Don't Show Stack-Trace
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

userErrorContinueST

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void userErrorContinueST(java.lang.Throwable t,
                                       java.lang.String message,
                                       Where_Am_I WHERE_AM_I)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();

 m.printMessage.ERROR(
     t,
     message,
     null,   // signature
     false,  // NON-FATAL
     true,   // SHOW STACK TRACE
     WHERE_AM_I
 );

 m.printRecord.writeSBToScreen();

setCurrentFileName

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void setCurrentFileName(java.lang.String fName,
                                      java.lang.String fNameKind)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 m.printRecord.setCurrentFileName(fName, fNameKind);

setTopDescriptionSection

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void setTopDescriptionSection()

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 m.printRecord.setTopDescriptionSection();

setDeclaration

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static void setDeclaration(Declaration declaration)

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 m.printRecord.setDeclaration(declaration);

hadErrors

🡅 🡇 ⇈ ⮫ 🗕 🗗 🗖

public static boolean hadErrors()

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 return m.printRecord.hadErrors();

ifLogCheckPointLog

🡅 ⇈ ⮫ 🗕 🗗 🗖

public static void ifLogCheckPointLog()

Code:

Exact Method Body:

 final Messager m = tlInstance.get();
 if (! m.printRecord.hasLogAppendable) return;
 m.printRecord.checkPointLog();

Class Messager

Thread-Local Field for Global, Thread-Safe, Accessibility

Method Parameters

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL

Method Detail

initializeThreadLocalInstance

print

println

println

printQuiet

printSilent

ifVerboseAppendVerbose

warning

assertFail

assertFail

assertFail

assertFail

assertFailContinue

assertFailContinue

userErrorHalt

userErrorHalt

userErrorContinue

userErrorContinue

userErrorContinue

userErrorContinueST

setCurrentFileName

setTopDescriptionSection

setDeclaration

hadErrors

ifLogCheckPointLog