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 when the IDE is running in debug mode. In non-debug mode, calling the methods of this class has no effect.

The check and precondition methods will throw exceptions if checking is enabled. Checking is enabled by default in debug mode. To disable checking, use

-J-Dide.AssertCheckingDisabled=true

as a command-line option when starting JDeveloper, or add

ADDVMOPTION -Dide.AssertCheckingDisabled=true

to

$HOME/.jdeveloper/<product-version>/product.conf

on Unix or

%APPDATA%\JDeveloper\<product-version>\product.conf

on Windows.

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. Tracing output is enabled by default in debug mode. To disable tracing output, use

-J-Dide.AssertTracingDisabled=true

as a command-line option when starting JDeveloper, or add

ADDVMOPTION -Dide.AssertTracingDisabled=true

to

$HOME/.jdeveloper/<product-version>/product.conf

on Unix or

%APPDATA%\JDeveloper\<product-version>\product.conf

on Windows.

Since:

5.0

Method Summary

Methods

Modifier and Type	Method and Description
static void	check(boolean condition) This method only works in debug mode! Check a condition within a method body.
static void	check(boolean condition, java.lang.String description) This method only works in debug mode! Check a condition within a method body.
static void	checkAWTThread() This method only works in debug mode! Checks that the current thread is the AWT event dispatcher.
static void	checkTracking(java.lang.String key, java.lang.Object object) This method only works in debug mode! Call this method immediately after the potential object performed the time consuming operation.
static void	endTiming(java.lang.String key, java.lang.String msg, java.lang.String indent, boolean quietStart) This method only works in debug mode! 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) This method only works in debug mode! 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) This method only works in debug mode! 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) This method only works in debug mode! 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) This method only works in debug mode! Report the result of the tracking.
static void	endTracking(java.lang.String key, java.lang.String msg) This method only works in debug mode! Report the result of the tracking.
static void	execute(java.lang.Runnable runnable) This method only works in debug mode! Execute a runnable.
static void	exit(int code) This method only works in debug mode! Exit the IDE with an error code.
static void	fail() This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location.
static void	fail(java.lang.Exception exception) This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location.
static void	fail(java.lang.String description) This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location.
static void	markTracking(java.lang.String key) This method only works in debug mode! Call this method just before a potentional object is about to perform a lengthy operation.
static void	precondition(boolean condition) This method only works in debug mode! Assert a precondition before a method body run.
static void	precondition(boolean condition, java.lang.String description) This method only works in debug mode! Assert a precondition before a method body run.
static void	print(boolean condition, java.lang.String s) This method only works in debug mode! Print a string to standard error if a condition is true.
static void	print(boolean condition, java.lang.String trueString, java.lang.String falseString) This method only works in debug mode! Print a string to standard error based on the evaluation of a condition.
static void	print(java.lang.String s) This method only works in debug mode! Print a string to standard error.
static void	printHeader(java.lang.String msg) This method only works in debug mode! Print a header of the form: [--] msg...
static void	println(boolean condition, java.lang.String s) This method only works in debug mode! 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) This method only works in debug mode! Print a string and a newline to standard error based on the evaluation of a condition.
static void	println(java.lang.String s) This method only works in debug mode! Print a string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object param) This method only works in debug mode! Print a one parameter formatted message string and a newline to standard error.
static void	println(java.lang.String pattern, java.lang.Object[] params) This method only works in debug mode! 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) This method only works in debug mode! 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) This method only works in debug mode! Print a three parameter formatted message string and a newline to standard error.
static void	printStackTrace() This method only works in debug mode! Print a diagnostic stack trace of the current thread.
static void	printStackTrace(boolean condition, java.lang.String s) This method only works in debug mode! Print a diagnostic stack trace if the specified condition is true.
static void	printStackTrace(java.lang.String message) This method only works in debug mode! Print a diagnostic stack trace of the current thread.
static void	printStackTrace(java.lang.Throwable ex) This method only works in debug mode! Print the stack trace of a Throwable.
static void	printTiming(long time, java.lang.String msg, java.lang.String indent) This method only works in debug mode! 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 only works in debug mode! This method takes the time and the message and indent strings and formats them, then it prints them.
static int	printTimingThreshold() Get the default timing threshold; times are not printed out unless the time is larger than this threshold.
static void	startTiming(java.lang.String key, java.lang.String msg, boolean quietStart) This method only works in debug mode! 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) This method only works in debug mode! Starts timing of an event which will be reported using Assert
static void	startTracking(java.lang.String key) This method only works in debug mode! 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 java.lang.IllegalStateException

This method only works in debug mode! 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:

java.lang.IllegalStateException - when the IDE is in debug mode and condition is false

precondition

public static void precondition(boolean condition)
                         throws java.lang.IllegalStateException

This method only works in debug mode! 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:

java.lang.IllegalStateException - when the IDE is in debug mode and the condition is false

check

public static void check(boolean condition,
         java.lang.String description)
                  throws java.lang.IllegalStateException

This method only works in debug mode! 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:

java.lang.IllegalStateException - when the IDE is in debug mode and condition is false

check

public static void check(boolean condition)
                  throws java.lang.IllegalStateException

This method only works in debug mode! 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:

java.lang.IllegalStateException - when the IDE is in debug mode and condition is false

checkAWTThread

public static void checkAWTThread()
                           throws java.lang.IllegalStateException

This method only works in debug mode! Checks that the current thread is the AWT event dispatcher.

Throws:

java.lang.IllegalStateException - when the IDE is in debug mode and the check fails

fail

public static void fail(java.lang.String description)
                 throws java.lang.IllegalStateException

This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location.

Parameters:

description - The description of the failure

Throws:

java.lang.IllegalStateException - when the IDE is in debug mode

fail

public static void fail()
                 throws java.lang.IllegalStateException

This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location.

Throws:

java.lang.IllegalStateException - when the IDE is in debug mode

fail

public static void fail(java.lang.Exception exception)
                 throws java.lang.IllegalStateException

This method only works in debug mode! Shorthand for causing a check exception if the code reaches an unexpected location. Prints the stack trace of the exception and then throws an IllegalStateException with the cause the incoming exception

Parameters:

exception - An exception encapsulating the failure

Throws:

java.lang.IllegalStateException - when the IDE is in debug mode

exit

public static void exit(int code)

This method only works in debug mode! Exit the IDE with an error code.

Parameters:

code - the Exit code.

printStackTrace

public static void printStackTrace()

This method only works in debug mode! Print a diagnostic stack trace of the current thread.

printStackTrace

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

This method only works in debug mode! Print a diagnostic stack trace of the current thread.

printStackTrace

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

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! Print a string to standard error.

Parameters:

s - the string to print.

print

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

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! Print a one parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

Parameters:

pattern - the format pattern for the message.

param - an object to be formatted and substituted into the result string.

println

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

This method only works in debug mode! Print a two parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

Parameters:

pattern - the format pattern for the message.

param1 - an object to be formatted and substituted into the result string.

param2 - an object to be formatted and substituted into the result string.

println

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

This method only works in debug mode! Print a three parameter formatted message string and a newline to standard error. Convenience wrapper for println(String,Object[]).

Parameters:

pattern - the format pattern for the message.

param1 - an object to be formatted and substituted into the result string.

param2 - an object to be formatted and substituted into the result string.

param3 - an object to be formatted and substituted into the result string.

println

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

This method only works in debug mode! 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)

This method only works in debug mode! Execute a runnable.

Parameters:

runnable - The runnable to execute

startTiming

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

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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 only works in debug mode! This method takes the time and the message and indent strings and formats them, then it prints them.

Parameters:

time - The time to print

msg - The message to print

indent - The indent to use

printTiming

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

This method only works in debug mode! This method takes the time and the message and indent strings and formats them, then it prints them.

Parameters:

time - The time to print

msg - The message to print

indent - The indent to use

threshold - The threshold, time needs to be >= than this threshold and larger than the default threshold for printing to occur

printHeader

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

This method only works in debug mode! Print a header of the form: [--] msg...

Parameters:

msg - The message to print

printTimingThreshold

public static int printTimingThreshold()

Get the default timing threshold; times are not printed out unless the time is larger than this threshold. This threshold is 50msec by default, but can be adjusted by setting the PrintTimingThreshold System Property to an integer value

Returns:

The default timing threshold which will return a value no matter if the IDE is in debug mode or not

startTracking

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

This method only works in debug mode! 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)

This method only works in debug mode! Call this method 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)

This method only works in debug mode! Call this method immediately after the potential object performed the time consuming operation. This method will update 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)

This method only works in debug mode! 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)

This method only works in debug mode! 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.