 |
ALox
V. 2402 R. 0
|
This class provides a simple facility to collect what is called a 'report'. Reports are maintenance messages, mostly error and warning messages, but is not aiming to replace any sort of error handling. (In ALib itself, sending a 'report' usually precedes raising an error.) Also, reports are not replacing any debug or release logging facility, which is not part of ALib. Much more, logging libraries might provide a derived object of type ReportWriter to plug into ALib report facility. This way, the concepts of logging and reports get unified. (As a sample, ALox Logging Library which builds on ALib does so.)
While a process can create different objects of this class, usually, the default instance, received by getDefault. is sufficient and all warnings and errors will be directed to this one. ALib itself directs all internal reports to the default instance.
This class uses a singleton of type ReportWriter to actually write the reports. By default, an object of type ReportWriterStdIO is attached.
The reporting method, doReport will check the flags provided with pushHaltFlags for message types 0 (errors) and 1 (warnings), and may invoke assert(). Such assertions are effective only in the debug compilation of the library/executable. Custom 'ReportWriters' might take action (e.g. for security reasons) and e.g. terminate the application also in release compilations.
To simplify things, a set of static methods are defined in class ALIB which are deemed to be pruned in release versions of the compilation unit. These are:
The use of these methods is recommended and preferred over the direct use of class Report whenever pure debug reports are intended.
Inner Classes | |
| class | Message |
Public Static Methods | |
| static Report | getDefault () |
Public Methods | |
| Report () | |
| synchronized void | doReport (int type, Object... msg) |
| synchronized ReportWriter | peekWriter () |
| synchronized void | popHaltFlags () |
| synchronized void | popWriter (ReportWriter checkWriter) |
| synchronized void | pushHaltFlags (boolean haltOnErrors, boolean haltOnWarnings) |
| synchronized void | pushWriter (ReportWriter newWriter) |
Protected Static Fields | |
| static Report | defaultReport =new Report() |
Protected Fields | |
| Deque< Integer > | haltAfterReport =new LinkedList<Integer>() |
| boolean | recursionBlocker =false |
| Deque< ReportWriter > | writers =new LinkedList<ReportWriter>() |
| Report | ( | ) |
Constructor
| synchronized void doReport | ( | int | type, |
| Object... | msg | ||
| ) |
Reports the given message to the current ReportWriter in place. The default ReportWriter will print the message on the process console. Furthermore, in debug execution the flags provided with pushHaltFlags is checked. If this is set for the type of message, the program halts or suspends into the debugger (platform and language specific).
If parameter is '0', the report is considered a severe error, otherwise a warning. User defined implementations of class ReportWriter may interpret this field arbitrarily.
-enableassertions to the Java virtual machine.| type | The report type. |
| msg | The report message. |
|
static |
Receives the default report object used by ALib and processes that rely on ALib.
| synchronized ReportWriter peekWriter | ( | ) |
Retrieves the actual report writer.
| synchronized void popHaltFlags | ( | ) |
Restores the previous values after an invocation to pushHaltFlags.
| synchronized void popWriter | ( | ReportWriter | checkWriter | ) |
Restores the previous writer after setting a new one using pushWriter. It is important to keep the right order when pushing and popping writers, as there lifetime is externally managed. (In standard use-cases, only one, app-specific writer should be pushed anyhow). To give a little assurance, this method popWriter takes the same parameter as pushWriter does, to verify if the one to be removed is really the topmost.
| checkWriter | The previously pushed writer (for checking of call order). |
| synchronized void pushHaltFlags | ( | boolean | haltOnErrors, |
| boolean | haltOnWarnings | ||
| ) |
Writes new values to the internal flags that decide if calls to doReport with report type '0' (errors), respectively report type '>0' (warnings) cause to halt program execution by calling assert(false). The previous values can be restored using popHaltFlags.
| haltOnErrors | Specifies if halting on errors is wanted. |
| haltOnWarnings | Specifies if halting on warnings is wanted. |
| synchronized void pushWriter | ( | ReportWriter | newWriter | ) |
Sets a new writer. The actual writer is implemented as a stack. It is important to keep the right order when pushing and popping writers, as there lifetime is externally managed. (In standard use-cases, only one, app-specific writer should be pushed anyhow). To give a little assurance, method popWriter takes the same parameter as this method does, to verify if if the one to be removed is really the topmost.
| newWriter | The writer to use. |
The default Report used internally by ALib and usually by processes that rely on ALib.
|
protected |
A stack of integers. The topmost value is used to decide, whether program execution is halted on message of type 'error' (type 0, bit 0) or of type 'warning' (type 1, bit 1). Can be set at runtime using methods pushHaltFlags and popHaltFlags.
|
protected |
This is a flag that avoids recursion. Recursion might occur when a more sophisticated report writer sends a report (e.g. an ALIB Error or Warning). Recursive calls are rejected without further notice.
|
protected |
A stack of writers. The topmost one is the actual. Can be set at runtime using methods pushWriter and popWriter.
1.8.16