org.vishia.msgDispatch

Interface LogMessage

All Superinterfaces:

java.lang.Appendable, java.lang.AutoCloseable, java.io.Closeable

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, java.io.Closeable

An interface to write messages or log entries to any destination. This interface is universal, it supports also numbered messages and simple messages. Hence it is possible to use both in an application (the focus may be changed while development) and it should be also possible to use both forms for the message output.
An output class for the message to files and possible System.out, System.err is supported by LogMessageStream. That uses LogMessageBase which adapts the operations here to more simple outputs.
But MsgDispatcher implements this interface for full numbered messages with selection of the messages by number.

Simple messages:
For more simple appications it is only intend to write info, warnings and errors. For that the operations writeInfoln(CharSequence) etc. are responsible.
Simple messages with arguments, write newline first:
There are two aspects for the 6 operations

• writeInfo(String, Object...), writeInfoAdd(String, Object...)
• writeWarning(String, Object...), writeWarningAdd(String, Object...)
• writeError(String, Object...), writeErrorAdd(String, Object...)

First it is simply possible to have some arguments for the message. String.format(String, Object...) formats it.
Second the newline concept is changed:

• On output always first a new line should be output, the message should start left.
• ...add(...) should append to this line, for further outputs in the program flow.
• The message can immediately shown on a display or write to a file.
• But if the message is forwarded as a whole (inclusively later added texts), then the implementation should wait a little bit if ...add(msg) comes, then transmit all.

A second topic may be the message number for info, error, warning. It can be decide by the implementation.

Full qualified messages:
For this messages the operations sendMsg(int, CharSequence, Object...), sendMsgTime(int, OS_TimeStamp, CharSequence, Object...), sendMsgVaList(int, OS_TimeStamp, CharSequence, Va_list) are responsible.
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

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 text, java.lang.Object... args) Writes a beginning new line with the prepared text to an error output.
void	writeError(java.lang.String CharSequence, java.lang.Throwable exc) Writes an error line caused by an exception.
void	writeErrorAdd(java.lang.String text, java.lang.Object... args) Writes an additional information for the error message after the already outputted error line in the same line.
void	writef(java.lang.String text, java.lang.Object... args) Writes the prepared text to the log as information.
void	writeInfo(java.lang.CharSequence sInfo) Appends an info to the end of the previous info, @see writeInfoln(CharSequence).
void	writeInfo(java.lang.String text, java.lang.Object... args) Writes the prepared text to the log as information.
void	writeInfoAdd(java.lang.String text, java.lang.Object... args) Writes an additional information for the info message after the already output info line in the same line.
void	writeInfoln(java.lang.CharSequence sInfo) Writes an info line.
void	writeWarning(java.lang.CharSequence sError) Writes an error line.
void	writeWarning(java.lang.String text, java.lang.Object... args) Writes a beginning new line with the prepared text to an standard or warning output.
void	writeWarningAdd(java.lang.String text, java.lang.Object... args) Writes an additional information for the warning message after the already outputt warning line in the same 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(CharSequence).

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);

writef

void writef(java.lang.String text,
            java.lang.Object... args)

Writes the prepared text to the log as information.

Parameters:

text - should begin with "\n", can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first.

writeInfo

void writeInfo(java.lang.String text,
               java.lang.Object... args)

Writes the prepared text to the log as information.

Parameters:

text - should begin with "\n", can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first.

writeInfoAdd

void writeInfoAdd(java.lang.String text,
                  java.lang.Object... args)

Writes an additional information for the info message after the already output info line in the same line.

Parameters:

text - can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first using writeError(String, Object...)

writeWarning

void writeWarning(java.lang.String text,
                  java.lang.Object... args)

Writes a beginning new line with the prepared text to an standard or warning output.

Parameters:

text - can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first.

writeWarningAdd

void writeWarningAdd(java.lang.String text,
                     java.lang.Object... args)

Writes an additional information for the warning message after the already outputt warning line in the same line.

Parameters:

text - can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first using writeError(String, Object...)

writeError

void writeError(java.lang.String text,
                java.lang.Object... args)

Writes a beginning new line with the prepared text to an error output.

Parameters:

text - can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first.

writeErrorAdd

void writeErrorAdd(java.lang.String text,
                   java.lang.Object... args)

Writes an additional information for the error message after the already outputted error line in the same line.

Parameters:

text - can be contain format placeholder, String.format(String, Object...) is used

args - The args for the placeholder.

Since:

2024-04. The difference is here: The newline is output first using writeError(String, Object...)

writeError

void writeError(java.lang.String CharSequence,
                java.lang.Throwable exc)

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);

exc - 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.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

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