org.vishia.util

Class ExcUtil

java.lang.Object

org.vishia.util.ExcUtil

Direct Known Subclasses:

CheckVs

public class ExcUtil
extends java.lang.Object

Field Summary

Fields

Modifier and Type	Field and Description
private static ExcUtil	assertObject
private static java.io.PrintStream	err The System.err and System.out standard console outputs are copied to this class able to use in its original output.
private static java.io.PrintStream	out The System.err and System.out standard console outputs are copied to this class able to use in its original output.
static java.lang.String	version Version, history and license.

Constructor Summary

Constructors

Constructor and Description
ExcUtil()

Method Summary

Modifier and Type	Method and Description
protected void	assertion(boolean shouldTrue) This routine can handle a assertion to support debugging or reporting.
protected void	assertion(boolean shouldTrue, java.lang.String msg) This routine can handle a assertion to support debugging or reporting.
protected void	assertMsg(boolean shouldTrue, java.lang.CharSequence msg) Assert the condition, writes a message to System.err if it is false.
static void	check(boolean shouldTrue) Checks whether an assertion is met.
static void	checkMsg(boolean shouldTrue, java.lang.String msg) Checks whether an assertion is met.
static void	consoleErr(java.lang.String text, java.lang.Object... args) Output to the original System.err channel though System.setErr(PrintStream) was invoked with another channel after first usage of this class.
static void	consoleOut(java.lang.String text, java.lang.Object... args) Output to the original System.out channel though System.setOut(PrintStream) was invoked with another channel after first usage of this class.
static java.lang.CharSequence	exceptionInfo(java.lang.CharSequence startText, java.lang.Throwable exc, int firstLevel, int nrofLevels) Prepares an exception information inclusively some levels of stack trace in a short (one line) form.
static java.lang.CharSequence	exceptionInfo(java.lang.CharSequence startText, java.lang.Throwable exc, int firstLevel, int nrofLevels, boolean bWithExceptiontext) Prepares an exception information inclusively some levels of stack trace in a short (one line) form.
static void	setAssertionInstance(ExcUtil instance) This routine instantiates the assertion handling with a special user instance.
static java.lang.CharSequence	stackInfo(java.lang.CharSequence startText, int nrofLevel) Prepares an information about the stack trace without occurring of a exception in a short (one line) form.
static java.lang.CharSequence	stackInfo(java.lang.CharSequence startText, int firstLevel, int nrofLevel) Prepares an information about the stack trace without occurring of a exception in a short (one line) form.
static void	stop() This is only a debug helper, an empty instruction.
static void	throwCompleteExceptionMessage(java.lang.String sAdd, java.lang.Exception exc) Throws with the given exception but with a modified exception text and with a modified exception type.
static void	throwUnexpect(java.lang.Exception exc) This routine can be used in a catch block of an unexpected exception.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

version

public static final java.lang.String version

Version, history and license.

• 2020-03-22 Hartmut exceptionInfo(CharSequence, Throwable, int, int, boolean) without newline on end. It should be clarified from the application. This is a feature change, should be adapted in the application. Generally a function should not determine too much by itself. Whether of not the line should be terminated is not a decision by exceptionInfo(), it is a decision by the application.
• 2020-03-22 Hartmut moved from CheckVs, a better name.
• 2020-03-22 Hartmut moved from org.vishia.util.Assert to this class because name clash with junit..Assert
• 2013-07-14 Hartmut chg: #stackInfo(String, int, int) produces a text which supports hyperlinking in Eclipse output output console window, like Throwable.printStackTrace().
• 2013-07-14 Hartmut new: throwCompleteExceptionMessage(String, Exception)
• 2013-01-26 Hartmut new: consoleErr(String, Object...), consoleOut(String, Object...): Possibility to use the original System.out channel even System.setErr() etc. may be invoked.
• 2013-01-26 Hartmut chg: assertion(boolean) etc. are protected now and commented. That are the methods which can be overridden in another class which is used by setAssertionInstance(ExcUtil).
• 2012-11-19 Hartmut new: stop() as dummy routine here now.
• 2012-09-02 Hartmut new #exceptionInfo(String, Throwable, int, int) and #stackInfo(String, int) to support a short info output for example for messages. Not the whole stacktrace!
• 2012-08-30 Hartmut some enhancements, especially assert with send a message to System.err.
• 2012-01-19 Hartmut created. The reason was: set an individual breakpoint on assertion statement. The second reason: flexibility for debugging. The java language 'assert' is too less in functionality.

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 ist 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

out

private static java.io.PrintStream out

The System.err and System.out standard console outputs are copied to this class able to use in its original output. The System.out and System.err may be overridden by invocation of System.setErr(PrintStream) with any other output channel, which may be redirected to the message system itself. If any output should be done while dispatching a message, a loop may be caused. In this case it is wrong to use System.err or System.out. Then this references can be used. Any user can use this references if an output should be done definitely without usage the message system.
This references are set when this interface is used the first time. In this time the System.err and System.out are not changed by the message System itself, because this interface was not used before.

err

private static java.io.PrintStream err

The System.err and System.out standard console outputs are copied to this class able to use in its original output. The System.out and System.err may be overridden by invocation of System.setErr(PrintStream) with any other output channel, which may be redirected to the message system itself. If any output should be done while dispatching a message, a loop may be caused. In this case it is wrong to use System.err or System.out. Then this references can be used. Any user can use this references if an output should be done definitely without usage the message system.
This references are set when this interface is used the first time. In this time the System.err and System.out are not changed by the message System itself, because this interface was not used before.

assertObject

private static ExcUtil assertObject

Constructor Detail

ExcUtil

public ExcUtil()

Method Detail

stop

public static void stop()

This is only a debug helper, an empty instruction.

throwUnexpect

public static void throwUnexpect(java.lang.Exception exc)

This routine can be used in a catch block of an unexpected exception. With the given Exception now a RuntimeException is thrown. That is because the Exception is intrinsically unexpected. It should throw to detect the unexpected behavior, but the Exception should not need specifically declared to prevent effort in calling levels for unexpected stuff.
Note: On usage in ctor with initializing final variables in a try block the original RuntimeException line should be written instead, can be copied from here. Because:
The java compiler can detect the throw new RuntimeException as satisfaction of non set final variable, the ctor is aborted. If this operation is called instead, an compiler error comes with the message, that final variable are uninitialized.

Parameters:

exc - The originally thrown Exception.

setAssertionInstance

public static void setAssertionInstance(ExcUtil instance)

This routine instantiates the assertion handling with a special user instance. All invocations of the static assertion call ExcUtil.check(boolean) invokes the user assertion(boolean) routine up to now.

Parameters:

instance - The users assertion instance.

check

public static void check(boolean shouldTrue)

Checks whether an assertion is met. This routine can invoke a special handling of assertion, if

Parameters:

shouldTrue -

checkMsg

public static void checkMsg(boolean shouldTrue,
                            java.lang.String msg)

Checks whether an assertion is met. This routine can invoke a special handling of assertion, if

Parameters:

shouldTrue -

exceptionInfo

public static java.lang.CharSequence exceptionInfo(java.lang.CharSequence startText,
                                                   java.lang.Throwable exc,
                                                   int firstLevel,
                                                   int nrofLevels)

Prepares an exception information inclusively some levels of stack trace in a short (one line) form.

Parameters:

startText - Any start text of the returned text. If this refers a StringBuilder, it is used to prepare the output text. Note that the StringBuilder should be used only locally for that. That is a typical practice if the text is assembled before. It saves dynamic memory allocation operations.

exc - The exception, its getMessage() will be appended

firstLevel - First level of stack. 0 is the routine where the exception is thrown, 1 the caller etc.

nrofLevels - maximum of numbers of levels to show in stack. Use for example 10 to prevent to long lines if it may be deeper.

Returns:

A string in form of CharSequence. Use ...toString() to build a String if necessary.

exceptionInfo

public static java.lang.CharSequence exceptionInfo(java.lang.CharSequence startText,
                                                   java.lang.Throwable exc,
                                                   int firstLevel,
                                                   int nrofLevels,
                                                   boolean bWithExceptiontext)

Prepares an exception information inclusively some levels of stack trace in a short (one line) form.

Parameters:

startText - Any start text of the returned text. If this refers a StringBuilder, it is used to prepare the output text. Note that the StringBuilder should be used only locally for that. That is a typical practice if the text is assembled before. It saves dynamic memory allocation operations.

exc - The exception, its getMessage() will be appended

firstLevel - First level of stack. 0 is the routine where the exception is thrown, 1 the caller etc.

nrofLevels - maximum of numbers of levels to show in stack. Use for example 10 to prevent to long lines if it may be deeper.

Returns:

A string in form of CharSequence ended with newline (0x0a). Use ...toString() to build a String if necessary.

throwCompleteExceptionMessage

public static void throwCompleteExceptionMessage(java.lang.String sAdd,
                                                 java.lang.Exception exc)
                                          throws java.io.IOException

Throws with the given exception but with a modified exception text and with a modified exception type. The sAdd will be added in front of the exception messages - it may be a hint where the exception was thrown.

Exception types: There may be less exception types for evaluation.

• FileNotFoundException: thrown
• IOException: thrown
• All other exception types causes a RuntimeException.

The thrown exception does not contain the stackTrace of the inputed Excpetion.

Parameters:

sAdd -

exc -

Throws:

IOException, - RuntimeException

java.io.IOException

stackInfo

public static java.lang.CharSequence stackInfo(java.lang.CharSequence startText,
                                               int nrofLevel)

Prepares an information about the stack trace without occurring of a exception in a short (one line) form.

Parameters:

startText - Any start text of the returned text If this refers a StringBuilder, it is used to prepare the output text. Note that the StringBuilder should be used only locally for that. That is a typical practice if the text is assembled before. It saves dynamic memory allocation operations.

nrofLevels - maximum of numbers of levels to show in stack. Use for example 10 to prevent to long lines if it may be deeper. The first level is the caller of this routine.

Returns:

A string in form of CharSequence. Use ...toString() to build a String if necessary.

stackInfo

public static java.lang.CharSequence stackInfo(java.lang.CharSequence startText,
                                               int firstLevel,
                                               int nrofLevel)

Prepares an information about the stack trace without occurring of a exception in a short (one line) form.

Parameters:

startText - Any start text of the returned text If this refers a StringBuilder, it is used to prepare the output text. Note that the StringBuilder should be used only locally for that. That is a typical practice if the text is assembled before. It saves dynamic memory allocation operations.

firstLevel - First level of stack. 0 is this routine, 1 the caller etc.

nrofLevels - maximum of numbers of levels to show in stack. Use for example 10 to prevent to long lines if it may be deeper.

Returns:

A string in form of CharSequence. Use ...toString() to build a String if necessary.

assertion

protected void assertion(boolean shouldTrue)

This routine can handle a assertion to support debugging or reporting. The Stacktrace can help to detect where the assertion occurs. This routine can be overridden with any other instance to provide a special assertion handling.

Parameters:

shouldTrue -

assertion

protected void assertion(boolean shouldTrue,
                         java.lang.String msg)

This routine can handle a assertion to support debugging or reporting. The Stacktrace can help to detect where the assertion occurs. This routine can be overridden with any other instance to provide a special assertion handling.

Parameters:

shouldTrue -

assertMsg

protected void assertMsg(boolean shouldTrue,
                         java.lang.CharSequence msg)

Assert the condition, writes a message to System.err if it is false. This routine can be overridden with any other instance to provide a special assertion handling.

Parameters:

shouldTrue -

msg - If it is null, an info from stacktrace is build.

consoleOut

public static void consoleOut(java.lang.String text,
                              java.lang.Object... args)

Output to the original System.out channel though System.setOut(PrintStream) was invoked with another channel after first usage of this class. Note that the user should invoke any action from ExcUtil, for example ExcUtil.check(true); as a first instruction in main(). Then this class saves the original System.out PrintStream object in this class to use in this method.
Note that the System.out may be redirected for any other reason, for example usage for Message Dispatching with MsgPrintStream. This method is independent of them.

Parameters:

text - Text to output. One should use "\n" to force a line feed. Format character can be used in the same kind as PrintStream.printf(String, Object...).

args - The arguments for the formatted text.

consoleErr

public static void consoleErr(java.lang.String text,
                              java.lang.Object... args)

Output to the original System.err channel though System.setErr(PrintStream) was invoked with another channel after first usage of this class. Note that the user should invoke any action from ExcUtil, for example ExcUtil.check(true); as a first instruction in main(). Then this class saves the original System.err PrintStream object in this class to use in this method.
The System.err may be redirected for any other reason, for example usage for Message Dispatching with MsgPrintStream. This method is independent of them.

Parameters:

text - Text to output. One should use "\n" to force a line feed. Format character can be used in the same kind as PrintStream.printf(String, Object...).

args - The arguments for the formatted text.