oracle.ide.util
Class Assert

java.lang.Object
  oracle.ide.util.Assert

public final class Assert
extends java.lang.Object

The Assert class provides basic assertion and tracing support. All of the methods in this class are static and return void; this allows the OJC compiler to optionally exclude calls to these methods made from other classes. Thus, Assert method calls can be present in debug builds and not in release builds.

The check and precondition methods will throw exceptions if checking is enabled. Checking is enabled by default. To disable checking, pass the flag

-Dide.AssertCheckingDisabled=true

to the VM when starting up by using an AddVMOption entry in the jdev.conf file or passing the flag on the command line if invoking directly.

For command line programs based on the IDE code base that write to standard output and error, the voluminous output that passes through the trace methods makes it difficult to use and test these programs. To disable tracing output, pass the flag

-Dide.AssertTracingDisabled=true

to the VM when starting up by using an AddVMOption entry in the jdev.conf file or passing the flag on the command line if invoking directly.

Since:

5.0

See Also:

precondition(boolean), precondition(boolean, String), check(boolean), check(boolean, String)

Method Summary

static void	check(boolean condition) Check a condition within a method body.
static void	check(boolean condition, java.lang.String description) Check a condition within a method body.
static void	checkAWTThread() Checks that the current thread is the AWT event dispatcher.
static void	checkTracking(java.lang.String key, java.lang.Object object) Call this method immediately after the potential object tasks performs a time consuming operation.
static void	endTiming(java.lang.String key, java.lang.String msg, java.lang.String indent, boolean quietStart) Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert.
static void	endTiming(java.lang.String key, java.lang.String msg, java.lang.String indent, boolean quietStart, boolean prefixThread) Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert.
static void	endTiming(java.lang.String key, java.lang.String msg, java.lang.String indent, boolean quietStart, boolean prefixThread, long timeThreshold) Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert.
static void	endTiming(java.lang.String key, java.lang.String msg, java.lang.String indent, boolean quietStart, long timeThreshold) Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert.
static void	endTracking(java.lang.String key) Report the result of the tracking.
static void	endTracking(java.lang.String key, java.lang.String msg) Report the result of the tracking.
static void	execute(java.lang.Runnable runnable)
static void	exit(int code) Exit the IDE with an error code.
static void	fail() Shorthand for causing a check exception if the code reaches an unexpected location.
static void	fail(java.lang.Exception exception) Shorthand for causing a check exception if the code reaches an unexpected location.
static void	fail(java.lang.String description) Shorthand for causing a check exception if the code reaches an unexpected location.
static void	markTracking(java.lang.String key) Call this object just before a potentional object is about to perform a lengthy operation.
static void	precondition(boolean condition) Assert a precondition before a method body run.
static void	precondition(boolean condition, java.lang.String description) Assert a precondition before a method body run.
static void	print(boolean condition, java.lang.String s) Print a string to standard error if a condition is true.
static void	print(boolean condition, java.lang.String trueString, java.lang.String falseString) Print a string to standard error based on the evaluation of a condition.
static void	print(java.lang.String s) Print a string to standard error.
static void	printHeader(java.lang.String msg) Print a header of the form: [--] msg.
static void	println(boolean condition, java.lang.String s) Print a string and a newline to standard error if a condition is true
static void	println(boolean condition, java.lang.String trueString, java.lang.String falseString) Print a string and a newline to standard error based on the evaluation of a condition.
static void	println(java.lang.String s) Print a string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object param) Print a one parameter formatted message string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object[] params) Print a multiple parameter formatted message string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object param1, java.lang.Object param2) Print a two parameter formatted message string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object param1, java.lang.Object param2, java.lang.Object param3) Print a three parameter formatted message string and a newline to standard error.
static void	printStackTrace() Print a diagnostic stack trace of the current thread.
static void	printStackTrace(boolean condition, java.lang.String s) Print a diagnostic stack trace if the specified condition is true.
static void	printStackTrace(java.lang.String message) Print a diagnostic stack trace of the current thread.
static void	printStackTrace(java.lang.Throwable ex) Print the stack trace of a Throwable.
static void	printTiming(long time, java.lang.String msg, java.lang.String indent) This method takes the time and the message and indent strings and formats them, then it prints them.
static void	printTiming(long time, java.lang.String msg, java.lang.String indent, long threshold) This method takes the time and the message and indent strings and formats them, then it prints them.
static int	printTimingThreshold()
static void	startTiming(java.lang.String key, java.lang.String msg, boolean quietStart) Starts timing of an event which will be reported using Assert.endTiming() The name of the currently executing thread is prefixed to the name of the key passed in.
static void	startTiming(java.lang.String key, java.lang.String msg, boolean quietStart, boolean prefixThread) Starts timing of an event which will be reported using Assert
static void	startTracking(java.lang.String key) Get ready to track the time taken by a list of tasks.

Methods inherited from class java.lang.Object

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

Method Detail

precondition

public static void precondition(boolean condition,
                                java.lang.String description)
                         throws oracle.ide.util.Assert.PreconditionException

Assert a precondition before a method body run. Use this to describe assumed state and parameter values. A precondition is raised if the given condition is not true. An error here usually indicates a problem with the use of the class.

Parameters:

condition - The condition being asserted.

description - The description of the failed assertion

Throws:

oracle.ide.util.Assert.PreconditionException

precondition

public static void precondition(boolean condition)
                         throws oracle.ide.util.Assert.PreconditionException

Assert a precondition before a method body run. Use this to describe assumed state and parameter values. A precondition is raised if the given condition is not true. An error here usually indicates a problem with the use of the class.

Parameters:

condition - The condition being asserted.

Throws:

oracle.ide.util.Assert.PreconditionException

check

public static void check(boolean condition,
                         java.lang.String description)
                  throws oracle.ide.util.Assert.CheckException

Check a condition within a method body. Use this to describe assumed results and state after internal operations. A check is raised if the given condition is not true. An error here usually indicates an internal problem with the class.

Parameters:

condition - The condition being asserted.

description - The description of the failed assertion

Throws:

oracle.ide.util.Assert.CheckException

check

public static void check(boolean condition)
                  throws oracle.ide.util.Assert.CheckException

Check a condition within a method body. Use this to describe assumed results and state after internal operations. A check is raised if the given condition is not true. An error here usually indicates an internal problem with the class.

Parameters:

condition - The condition being asserted.

Throws:

oracle.ide.util.Assert.CheckException

checkAWTThread

public static void checkAWTThread()
                           throws oracle.ide.util.Assert.CheckException

Checks that the current thread is the AWT event dispatcher.

Throws:

oracle.ide.util.Assert.CheckException

fail

public static void fail(java.lang.String description)
                 throws oracle.ide.util.Assert.CheckException

Shorthand for causing a check exception if the code reaches an unexpected location.

Parameters:

description - The description of the failure

Throws:

oracle.ide.util.Assert.CheckException

fail

public static void fail()
                 throws oracle.ide.util.Assert.CheckException

Shorthand for causing a check exception if the code reaches an unexpected location.

Throws:

oracle.ide.util.Assert.CheckException

fail

public static void fail(java.lang.Exception exception)
                 throws oracle.ide.util.Assert.CheckException

Shorthand for causing a check exception if the code reaches an unexpected location.

Parameters:

exception - An exception encapsulating the failure

Throws:

oracle.ide.util.Assert.CheckException

exit

public static void exit(int code)

Exit the IDE with an error code.

Parameters:

code - the Exit code.

printStackTrace

public static void printStackTrace()

Print a diagnostic stack trace of the current thread.

printStackTrace

public static void printStackTrace(java.lang.String message)

Print a diagnostic stack trace of the current thread.

printStackTrace

public static void printStackTrace(java.lang.Throwable ex)

Print the stack trace of a Throwable.

Parameters:

ex - The Throwable with the stack trace info.

printStackTrace

public static void printStackTrace(boolean condition,
                                   java.lang.String s)

Print a diagnostic stack trace if the specified condition is true.

Parameters:

condition - the condition that determines whether to print the stack trace.

s - the string to print before the stack trace.

print

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

Print a string to standard error.

Parameters:

s - the string to print.

print

public static void print(boolean condition,
                         java.lang.String s)

Print a string to standard error if a condition is true.

Parameters:

condition - the condition to evaluate

s - the string to print.

print

public static void print(boolean condition,
                         java.lang.String trueString,
                         java.lang.String falseString)

Print a string to standard error based on the evaluation of a condition.

Parameters:

condition - the condition to evaluate

trueString - the string to print if condition is true.

falseString - the string to print if condition is false.

println

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

Print a string and a newline to standard error.

Parameters:

s - the string to print

println

public static void println(boolean condition,
                           java.lang.String s)

Print a string and a newline to standard error if a condition is true

Parameters:

condition - the condition to evaluate

s - the string to print.

println

public static void println(boolean condition,
                           java.lang.String trueString,
                           java.lang.String falseString)

Print a string and a newline to standard error based on the evaluation of a condition.

Parameters:

condition - the condition to evaluate

trueString - the string to print if condition is true.

falseString - the string to print if condition is false.

println

public static void println(java.lang.String pattern,
                           java.lang.Object param)

Print a one parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

println

public static void println(java.lang.String pattern,
                           java.lang.Object param1,
                           java.lang.Object param2)

Print a two parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

println

public static void println(java.lang.String pattern,
                           java.lang.Object param1,
                           java.lang.Object param2,
                           java.lang.Object param3)

Print a three parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

println

public static void println(java.lang.String pattern,
                           java.lang.Object[] params)

Print a multiple parameter formatted message string and a newline to standard error.

Parameters:

pattern - the format pattern for the message.

params - an array of objects to be formatted and substituted into the result string.

See Also:

MessageFormat.format(String,Object...)

execute

public static void execute(java.lang.Runnable runnable)

startTiming

public static void startTiming(java.lang.String key,
                               java.lang.String msg,
                               boolean quietStart)

Starts timing of an event which will be reported using Assert.endTiming() The name of the currently executing thread is prefixed to the name of the key passed in.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - An optional message to print. If null nothing will be printed, only the start time will be stored

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

startTiming

public static void startTiming(java.lang.String key,
                               java.lang.String msg,
                               boolean quietStart,
                               boolean prefixThread)

Starts timing of an event which will be reported using Assert

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - An optional message to print. If null nothing will be printed, only the start time will be stored

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

prefixThread - true if the key should be prefixed by the name of the currently executing thread; false otherwise

endTiming

public static void endTiming(java.lang.String key,
                             java.lang.String msg,
                             java.lang.String indent,
                             boolean quietStart)

Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert. The name of the currently executing thread is prefixed to the name of the key passed in.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - the message to print

indent - A string of spaces to be used for indenting the message. Null is allowed and will mean no indentation.

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

endTiming

public static void endTiming(java.lang.String key,
                             java.lang.String msg,
                             java.lang.String indent,
                             boolean quietStart,
                             long timeThreshold)

Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert. The name of the currently executing thread is prefixed to the name of the key passed in.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - the message to print

indent - A string of spaces to be used for indenting the message. Null is allowed and will mean no indentation.

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

timeThreshold - minimum number of elapsed milliseconds by the operation being timed to have the message being displayed, any operation that takes less than timeThreshold will not have their time displayed

endTiming

public static void endTiming(java.lang.String key,
                             java.lang.String msg,
                             java.lang.String indent,
                             boolean quietStart,
                             boolean prefixThread)

Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert. The name of the currently executing thread is prefixed to the name of the key passed in.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - the message to print

indent - A string of spaces to be used for indenting the message. Null is allowed and will mean no indentation.

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

prefixThread - true if the key should be prefixed by the name of the currently executing thread; false otherwise

endTiming

public static void endTiming(java.lang.String key,
                             java.lang.String msg,
                             java.lang.String indent,
                             boolean quietStart,
                             boolean prefixThread,
                             long timeThreshold)

Ends timing of an event and prints the elapsed time between the time stored with startTiming() and endTiming() using Assert. The name of the currently executing thread is prefixed to the name of the key passed in.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - the message to print

indent - A string of spaces to be used for indenting the message. Null is allowed and will mean no indentation.

quietStart - true if you want to store timing information and print it using endTiming(); false otherwise.

prefixThread - true if the key should be prefixed by the name of the currently executing thread; false otherwise

timeThreshold - minimum number of elapsed milliseconds by the operation being timed to have the message being displayed, any operation that takes less than timeThreshold will not have their time displayed

printTiming

public static void printTiming(long time,
                               java.lang.String msg,
                               java.lang.String indent)

This method takes the time and the message and indent strings and formats them, then it prints them.

printTiming

public static void printTiming(long time,
                               java.lang.String msg,
                               java.lang.String indent,
                               long threshold)

This method takes the time and the message and indent strings and formats them, then it prints them.

printHeader

public static void printHeader(java.lang.String msg)

Print a header of the form: [--] msg.

printTimingThreshold

public static int printTimingThreshold()

startTracking

public static void startTracking(java.lang.String key)

Get ready to track the time taken by a list of tasks. The slowest task will be reported when endTracking(String) or endTracking(String, String)is called.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent"). Key is prefixed with the name of the currently executing thread.

markTracking

public static void markTracking(java.lang.String key)

Call this object just before a potentional object is about to perform a lengthy operation. The method records the start time.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent"). Key is prefixed with the name of the currently executing thread.

checkTracking

public static void checkTracking(java.lang.String key,
                                 java.lang.Object object)

Call this method immediately after the potential object tasks performs a time consuming operation. This method will updated the task time if the operation took longer than all other previous checks.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

object - the object performing the operation or task.

endTracking

public static void endTracking(java.lang.String key)

Report the result of the tracking. Only the slowest task time will be reported.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

endTracking

public static void endTracking(java.lang.String key,
                               java.lang.String msg)

Report the result of the tracking.

Parameters:

key - typically the fully-qualified class name with the method name at the end (eg, "oracle.ide.Ide.fireEvent")

msg - An optional message to indicate that the total time taken by all the tasks should be reported. If null is specified, only the slowest task time will be reported. Key is prefixed with the name of the currently executing thread.