LogMessage

All Superinterfaces:

java.lang.Appendable

All Known Subinterfaces:

MainCmd_ifc, MainCmdLogging_ifc, Report

All Known Implementing Classes:

Bin2Data.CmdLine, C2DataDeps, CheckDeps_Old.Cmdline, CmdHeader2Reflection, Csv2Data.CmdHandler, DocuGen.CmdLine, Filecmd.Cmdline, GenXmlCfgJavaData.CmdLine, GenZbnfJavaData.CmdLine, JZtxtcmd.CmdLine, LogMessageBase, LogMessageFile, LogMessageStream, MainCmd, MainCmd.LogMessageImplConsole, MainCmd.LogMessageImplErrConsole, MainCmd.LogMessageImplFile, MainCmdLoggingStream, MsgDispatcher, MsgDispatcherCore, MsgRedirectConsole, ReportWrapperLog, SampleCmdLine.CmdLine, Xsltpre.CmdLine, Zbnf2Text.CmdLineText, Zbnf2Xml.CmdLine, Zmake.CmdLine
```
public interface LogMessage
extends java.lang.Appendable
```
An interface to write messages or log entries to any destination. The basic idea is: The messages and logs are dispatched via a number. The number have two aspects:
- The number identifies the message or kind of log entry.
- The number is used to select receiver(s) of the message or log entry.
Any message can be dispatched to one or more destinations which evaluate or store the message, or the message can be ignored. A log entry is a special using of a message: It should only written in a log file or display, without any forcing of reactions. But a log can also be dispatched to one or more destinations (log files) or can be ignored. Whether a message is only a log, or the message forces actions at destination, is determined by the destination itself. The source produces the message only. The source doesn't determine the using of it.

A Message comprises the possibility of "coming" and "going" of the associated state. If the message are "coming", the state is activated, if it is "going", the state is released. To tag the state, the identNumber is given positive for "coming" and negative for "going". It is a simple economization of calling arguments, because mostly or by first using, there is no state identify of the message. Only some chosen messages have a state identify, or a state comes with the message in continue of implementations.

A Message has a text. The text is used immediate if it is a textual saved log entry, readable by human. The text may be unused if the message forces actions in a technical system. The text may be unused also, if a destination medium has its own text processor. If the message should be evaluated not only as human read, the identNumber have to be the correct identification. The text should only be a comment, human readable.

A message has some values. The values should be displayed in the textual representation. The String.format(String, Object...)-Method should used to display the text. But the values may be also important for evaluating the message in the destination. The meaning of the values depends on the kind of message, identified by the number.

A message has a time stamp. The time stamp may be built automatically at the time while creating the message. But it is possible to supply a time stamp to the message. It is important, if the signal or event associated to the message has a deterministic time stamp created for example in hardware. Following common usages the time stamp is an absolute time in milliseconds, represented by a java.util.Date Object. In a realtime system, compiled with C-Language, the struct Date may have a microsecond resolution and another base year, but it should be absolute.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.text.SimpleDateFormat`	`dateFormat` It should be implemented especially for a File-Output to flush or close the file in a raster of some seconds.
`static int`	`debug` report level to indicate the report should be written to detect problems in software.
`static int`	`error` report level to indicate the report should be written anytime and anyway.
`static int`	`fineDebug` report level to indicate all report should be written to detect problems in software with finely and heavyset reports.
`static int`	`fineInfo` report level to indicate the report should be written if a user is interested on the order of the events finely.
`static int`	`info` report level to indicate the report should be written if a user is interested on notes of the progression of programm is working.
`static java.text.SimpleDateFormat`	`minSecondsFormat`
`static int`	`mNeverOutputToDisplay` Mask bit to indicate, do not write to display.
`static int`	`mReportLevel` Mask for the in fact reportlevel, other bits may have another meaning.
`static java.lang.String`	`sVersion` Version, history and license.
`static int`	`warning` report level to indicate the report should be written if a user is interested on warnings.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`close()` A call of this method closes the devices, which processed the message.
`void`	`flush()` A call of this method causes an activating of transmission of all messages since last flush.
`void`	`flushReport()` Writes the content in the physical medium.
`int`	`getReportLevel()` access to the level of report.
`int`	`getReportLevelFromIdent(int ident)` gets the associated report level to a report identifier.
`boolean`	`isOnline()` Checks whether the message output is available.
`static java.lang.String`	`msgSec(java.lang.String msg, long ms)` It prepares a message part with given mm:ss.SSS (till millisec accuracy) with a given absolute time.
`void`	`report(java.lang.CharSequence startText, java.lang.Throwable exception)` report of a excpetion (in a new line)
`void`	`report(int nLevel, java.lang.CharSequence string)` report inside a line
`void`	`reportln(int nLevel, java.lang.CharSequence string)` report begins at a new a line
`void`	`reportln(int nLevel, int nLeftMargin, java.lang.CharSequence string)` report begins at a new a line with left margin
`boolean`	`sendMsg(int identNumber, java.lang.CharSequence text, java.lang.Object... args)` Sends a message.
`boolean`	`sendMsgTime(int identNumber, OS_TimeStamp creationTime, java.lang.CharSequence text, java.lang.Object... args)` Sends a message.
`boolean`	`sendMsgVaList(int identNumber, OS_TimeStamp creationTime, java.lang.CharSequence text, Va_list args)` Sends a message.
`int`	`setReportLevel(int level)` Set another level inside programming.
`void`	`setReportLevelToIdent(int ident, int nLevelActive)` Sets a dedicated level number to the known output priorities.
`static java.lang.String`	`timeCurr(java.lang.String msg)` It prepares a message with the current time and a String after it.
`static java.lang.String`	`timeMsg(long ms, java.lang.String msg)` This is a simple static output operation independent of the log system.
`void`	`writeError(java.lang.CharSequence sError)` Writes an error line.
`void`	`writeError(java.lang.String CharSequence, java.lang.Throwable exception)` Writes an error line caused by an exception.
`void`	`writeInfo(java.lang.CharSequence sInfo)` Appends an info to the end of the previous info, @see #writeInfoln.
`void`	`writeInfoln(java.lang.CharSequence sInfo)` Writes an info line.
`void`	`writeWarning(java.lang.CharSequence sError)` Writes an error line.

Methods inherited from interface java.lang.Appendable
append, append, append

- Field Detail
  - sVersion
```
static final java.lang.String sVersion
```
    Version, history and license.
    - 2022-12-25 Hartmut new: Some enhancements with nice static operations: timeCurr(String) etc.
    - 2022-12-25 Hartmut new: timeMsg(long, String) as helper for simple preparation an String with timestamp in absolute in ms.
    - 2022-12-25 Hartmut chg: the log texts are now CharSequence, not String. This allows give a StringBuilder reference immediately. For post processing also usual a CharSequence is sufficient. This is a refactoring in all message and log sources. But it does not influence user sources. Note that a String is also a CharSequence.
    - 2022-09-23 Hartmut new: Most of the operations from the MainCmdLogging_ifc are moved to this. It makes possible that some programs such as ZbnfParser now uses the basically LogMessage instead the older and more complex MainCmdLogging_ifc. Default implementations for all additional operations are contains in LogMessageBase.
    - 2022-09-23 Hartmut new: #writeError(String) is declared in MainCmd_ifc and used sometimes. It is also yet defined here, but redirected to Appendable.append(CharSequence) in the new LogMessageBase implementation.
    - 2022-09-23 Hartmut new: extends now Appendable, hence usefull for more approaches, see also changes in LogMessageStream.
    - 2014-06-17 Hartmut chg: meaning of return value of #sendMsg(int, String, Object...) described. It was not defined and maybe not used in the last 8 years.
    - 2008-02-03 Hartmut new: method isOnline
    - 2006- created. Concept in Java and C/C++ especially for debug on runtime.
    Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:
    1. You can use this source without any restriction for any desired purpose.
    2. You can redistribute copies of this source to everybody.
    3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
    4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
    5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.
    If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.
    See Also:
    
    Constant Field Values
  - error
```
static final int error
```
    report level to indicate the report should be written anytime and anyway. Useable especially for errors
    
    See Also:
    
    Constant Field Values
  - warning
```
static final int warning
```
    report level to indicate the report should be written if a user is interested on warnings.
    
    See Also:
    
    Constant Field Values
  - info
```
static final int info
```
    report level to indicate the report should be written if a user is interested on notes of the progression of programm is working.
    
    See Also:
    
    Constant Field Values
  - fineInfo
```
static final int fineInfo
```
    report level to indicate the report should be written if a user is interested on the order of the events finely.
    
    See Also:
    
    Constant Field Values
  - debug
```
static final int debug
```
    report level to indicate the report should be written to detect problems in software.
    
    See Also:
    
    Constant Field Values
  - fineDebug
```
static final int fineDebug
```
    report level to indicate all report should be written to detect problems in software with finely and heavyset reports.
    
    See Also:
    
    Constant Field Values
  - mReportLevel
```
static final int mReportLevel
```
    Mask for the in fact reportlevel, other bits may have another meaning.
    
    See Also:
    
    Constant Field Values
  - mNeverOutputToDisplay
```
static final int mNeverOutputToDisplay
```
    Mask bit to indicate, do not write to display. This bit is used internally in MainCmd. It is outside the mReportLevel-mask.
    
    See Also:
    
    Constant Field Values
  - dateFormat
```
static final java.text.SimpleDateFormat dateFormat
```
    It should be implemented especially for a File-Output to flush or close the file in a raster of some seconds. This routine should be called only in the same thread like the queued output, It is called inside the MsgDispatcher.DispatcherThread.run().
  - minSecondsFormat
```
static final java.text.SimpleDateFormat minSecondsFormat
```
- Method Detail
  - sendMsg
```
boolean sendMsg(int identNumber,
                java.lang.CharSequence text,
                java.lang.Object... args)
```
    Sends a message. The timestamp of the message is build with the system time. All other parameter are identically see #sendMsg(int, OS_TimeStamp, String, Object...).
    
    Parameters:
    
    identNumber - of the message. If it is negative, it is the same message as positive number, but with information 'going state', where the positive number is 'coming state'.
    
    text - The text representation of the message, format string, see java.lang.String.format(..).
    
    args - 0, 1 or more arguments of any type. The interpretation of the arguments is controlled by param text.
    
    Returns:
    
    true if the message will be dispatched, false if it is suppressed
  - sendMsgTime
```
boolean sendMsgTime(int identNumber,
                    OS_TimeStamp creationTime,
                    java.lang.CharSequence text,
                    java.lang.Object... args)
```
    Sends a message.
    
    Parameters:
    
    identNumber - of the message. If it is negative, it is the same message as positive number, but with information 'going state', where the positive number is 'coming state'.
    
    creationTime - absolute time stamp. @Java2C=perValue.
    
    text - The text representation of the message, format string, see java.lang.String.format(..).
    
    args - 0, 1 or more arguments of any type. The interpretation of the arguments is controlled by param text.
    
    Returns:
    
    true if the message will be dispatched, false if it is suppressed
  - sendMsgVaList
```
boolean sendMsgVaList(int identNumber,
                      OS_TimeStamp creationTime,
                      java.lang.CharSequence text,
                      Va_list args)
```
    Sends a message. The functionality and the calling parameters are identically with #sendMsg(int, OS_TimeStamp, String, Object...), but the parameter args is varied:
    
    Parameters:
    
    identNumber -
    
    creationTime -
    
    text - The text of the message: Hint for Java2C: This is a StringJc, not a simple char const*. That is necessary because the String may be replaced.
    
    typeArgs - Type chars, ZCBSIJFD for boolean, char, byte, short, int, long, float double.
    
    args - Reference to a buffer which contains the values for a variable argument list.
    In C implementation it is a reference either to the stack, or to a buffer elsewhere, but the reference type is appropriate to provide the values in stack for calling routines with variable argument list such as vprintf(buffer, text, args). The referenced instance shouldn't accepted as persistent outside processing time of the called routine. Therefore stack content is able to provide.
    In Java it is a special class wrapping a Object[] tantamount to a Object... as variable argument list. Using of this wrapper class is only a concession to C-programming, because in Java an Object[] would adequate.
    
    Returns:
    
    true than okay. It is possible, that a destination for dispatching is not available yet. Than the routine returns false. That is for special outputs of message dispatcher. Normally the user shouldn't realize false here and react anywise. If a message isn't able to transport, it is not visible in the creating thread. It is possible that a message is lost anywhere in transportation way. In Generally, to secure a complex systems functionality, any timeouts, repeats and backup strategies are necessary in the supervise software above sending a single message.
  - writeInfoln
```
void writeInfoln(java.lang.CharSequence sInfo)
```
    Writes an info line. This method should be used instead a directly write via System.out.println(...). The using of System.out writes the output directly on console window of the command line, but in general, the user mostly don't want to write to the console, he only will give an information out. In a GUI-application, this information can be displayed in a status line or scrolling output window. It may also be possible to write the information in a file additional. The implementation of this method writes the output in the conformed way to the application frame.
    Before output, the previous line is terminated by a newline, or a status line will be cleared.
    
    Parameters:
    
    sInfo - String to be written.
  - writeInfo
```
void writeInfo(java.lang.CharSequence sInfo)
```
    Appends an info to the end of the previous info, @see #writeInfoln.
    
    Parameters:
    
    sInfo - String to be written.
  - writeWarning
```
void writeWarning(java.lang.CharSequence sError)
```
    Writes an error line. This method should be used instead a directly write via System.err.println(...). The using of System.err writes the output directly on console window of the command line, but in general, the user mostly don't want to write to the console, he will give an information out. In a GUI-application, this information can be displayed in a status line or scrolling output window. It may also be possible to write the information in a file additional. The implementation of this method writes the output in the conformed way to the application frame.
    Before output, the previous line is terminated by a newline, or a status line will be cleared.
    
    Parameters:
    
    sError - The error text, it should be without such hot spot words line "!!!WARNING!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("file is empty: " + sFileName);
  - writeError
```
void writeError(java.lang.CharSequence sError)
```
    Writes an error line. This method should be used instead a directly write via System.err.println(...). The using of System.err writes the output directly on console window of the command line, but in general, the user mostly don't want to write to the console, he will give an information out. In a GUI-application, this information can be displayed in a status line or scrolling output window. It may also be possible to write the information in a file additional. The implementation of this method writes the output in the conformed way to the application frame.
    Before output, the previous line is terminated by a newline, or a status line will be cleared.
    
    Parameters:
    
    sError - The error text, it should be without such hot spot words line "!!!ERROR!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("cannot create file: " + sFileName);
  - writeError
```
void writeError(java.lang.String CharSequence,
                java.lang.Throwable exception)
```
    Writes an error line caused by an exception. This method should be used instead a directly write via System.err.println(...) and by catching an exception. The using of System.err writes the output directly on console window of the command line, but in general, the user mostly don't want to write to the console, he will give an information out. In a GUI-application, this information can be displayed in a status line or scrolling output window. It may also be possible to write the information in a file additional. The implementation of this method writes the output in the conformed way to the application frame.
    Before output, the previous line is terminated by a newline, or a status line will be cleared.
    
    Parameters:
    
    sError - The error text, it should be without such hot spot words line "!!!ERROR!!!", because the distinction in display should be done by the implementation of this method. A good sample is writeErrorln("cannot create file: " + sFileName);
    
    exception - The catched Exception. The getMessage()-part of the exception is written after sError. The stacktrace of the exception is written to report.
  - report
```
void report(int nLevel,
            java.lang.CharSequence string)
```
    report inside a line
  - reportln
```
void reportln(int nLevel,
              int nLeftMargin,
              java.lang.CharSequence string)
```
    report begins at a new a line with left margin
    
    Parameters:
    
    nLevel - write the report only if the demand level is greater or equal.
    
    nLeftMargin - determins a left margin. First a new line is outputted, followed by '*' and spaces.
    
    string - String to write.
  - reportln
```
void reportln(int nLevel,
              java.lang.CharSequence string)
```
    report begins at a new a line
    
    Parameters:
    
    nLevel - write the report only if the demand level is greater or equal.
    
    string - String to write.
  - report
```
void report(java.lang.CharSequence startText,
            java.lang.Throwable exception)
```
    report of a excpetion (in a new line)
  - getReportLevel
```
int getReportLevel()
```
    access to the level of report. With the knowledge of the maximal reportlevel the user can decide on some actions in context of report.
    
    Returns:
    
    The report level, defined by user invoking.
  - flushReport
```
void flushReport()
```
    Writes the content in the physical medium. The implementation of flush is in the best way as possible. It depends on the possibilities of the output medium.
  - setReportLevelToIdent
```
void setReportLevelToIdent(int ident,
                           int nLevelActive)
```
    Sets a dedicated level number to the known output priorities. This method helps to define several levels to dispatch it.
    Parameters:
    
    nLevel - The number identifying a dedicated level. This number should be greater than the known priority levels, it means >= 10 or >=1000. Use dedicated group of numbers for an application.
    nLevelActive - Ones of the known priotity levels Report.error to Report.fineDebug.
    Example of using:
    class MyModule { /**Define module-specific numbers to identify a level. * The numbers should be define regarding a band of numbers in the application. * / static final int myReportLevel1 = 3500, myReportLevel2=3501; void init() { setLevelActive(myReportLevel1, Report.info); //This reports should be outputted always setLevelActive(myReportLevel2, Report.debug); //This reports are debug infos. } void processAnything() { report.reportln( myReportLevel1, "InfoText"); //It depends on the report level settings report.reportln( myReportLevel2, "DebugText");//whether it is outputed or not. }
  - setReportLevel
```
int setReportLevel(int level)
```
    Set another level inside programming. It is advisable to restore the old level after the designated operation.
    
    Parameters:
    
    newLevel - The level to be set, use one of the defines info to fineDebug
    
    Returns:
    
    the current level, usefull to restore it.
  - getReportLevelFromIdent
```
int getReportLevelFromIdent(int ident)
```
    gets the associated report level to a report identifier.
    
    Parameters:
    
    ident - The identifier.
    
    Returns:
    
    the level.
  - close
```
void close()
```
    A call of this method closes the devices, which processed the message. It is abstract. It depends from the kind of device, what close mean. If the device is a log file writer it should be clearly. close may mean, the processing of messages is finite temporary. An open occurs automatically, if a new message is dispatched.
  - flush
```
void flush()
```
    A call of this method causes an activating of transmission of all messages since last flush. It is abstract. It depends from the kind of device, what flush mean. If the device is a log file writer it should be clearly. flush may mean, the processing of messages is ready to transmit yet.
  - isOnline
```
boolean isOnline()
```
    Checks whether the message output is available.
  - timeMsg
```
static java.lang.String timeMsg(long ms,
                                java.lang.String msg)
```
    This is a simple static output operation independent of the log system.
    
    Parameters:
    
    ms - Milliseconds after 1970
    
    msg -
    
    Returns:
  - msgSec
```
static java.lang.String msgSec(java.lang.String msg,
                               long ms)
```
    It prepares a message part with given mm:ss.SSS (till millisec accuracy) with a given absolute time.
    
    Parameters:
    
    msg - Text before, shold have the form "time=" or "at " or such.
    
    ms - absolute time for the millisec
    
    Returns:
    
    It shows msg 13:45.124
  - timeCurr
```
static java.lang.String timeCurr(java.lang.String msg)
```
    It prepares a message with the current time and a String after it.
    
    Parameters:
    
    msg - any text.
    
    Returns:
    
    String to log

Interface LogMessage

Field Summary

Method Summary

Methods inherited from interface java.lang.Appendable

Field Detail

sVersion

error

warning

info

fineInfo

debug

fineDebug

mReportLevel

mNeverOutputToDisplay

dateFormat

minSecondsFormat

Method Detail

sendMsg

sendMsgTime

sendMsgVaList

writeInfoln

writeInfo

writeWarning

writeError

writeError

report

reportln

reportln

report

getReportLevel

flushReport

setReportLevelToIdent

setReportLevel

getReportLevelFromIdent

close

flush

isOnline

timeMsg

msgSec

timeCurr