oracle.javatools.util

Class Log

java.lang.Object

oracle.javatools.util.Log

public final class Log
extends java.lang.Object

A logger suitable for permanently embedding trace logging into production code. This class was originally used for error logging as well, and still has the static error methods, but Logger is suggested instead.

Log instances are created with a name and are enabled by name at application launch using the system property javatools.trace. When no logs are enabled, the overhead from even liberal use of trace logging is minimal, as long as the calling code takes advantage of the support for MessageFormat-style format strings to avoid formatting objects to text unnecessarily. Taking advantage of these also makes the tracing code visually less intrusive. For the really paranoid, the trace methods all return true: trace calls can be placed in an assert statement so that even the minimal disabled cost is only incurred when assertions are enabled.

The value of the javatools.trace property is a list of trace names to enable, separated by commas. By default, traces are logged to System.err (see below to change the default). To launch JDeveloper with the javatools.trace property set to "traversal", use the following command line:

   jdev -J-Djavatools.trace=traversal
 

If using the command line is not practical, adding the following line to jdev.conf (found in the same directory as jdev.exe) will accomplish the same thing:

   AddVMOption -Djavatools.trace=traversal
 

In addition to trace names, the property can also include directives as described below. Directives always start with the "#" character.

Trace logging is typically used as follows:

 private static final LOG = new Log("profile");
 .
 .
 public void save (URL url)
 {
   LOG.trace("saving profile to {0}", url);
   .
   .
   LOG.trace("completed saving profile {0}", url);
 }
 

or to allow different levels of detail:

 private static final LOG = new Log("profile", "profile-detail");
 private static final LOGDETAIL = new Log("profile-detail");
 .
 .
 public void save (URL url)
 {
   LOG.trace("saving profile to {0}", url);
   .
   .
   LOGDETAIL.trace("completed saving profile {0}", url);
 }
 

The second example shows how a log can be given multiple names. In it, enabling "profile" enables tracing using log LOG but not log LOGDETAIL; enabling "profile-detail" enables tracing to both logs.

When logging is enabled, and a trace is logged, parameters are converted to text and the message is formatted and written to the output stream. To minimize the runtime impact of enabled logging, pushing this work from the calling thread to a low priority background thread is desirable. However, because toString methods often reference mutable fields, parameter conversion by default is done synchronously in the calling thread, while message formatting and writing are done asynchronously in a background thread. If mutability is not a concern for a particular scenario, adding the "#asynchronous" directive to the javatools.trace property causes the parameter conversion to also be done asynchronously in the background thread. On the other hand, if it is desirable for tracing to be completely synchronous (e.g., to preserve the sequencing relationship with other output that does not use this class), adding the "#synchronous" directive to the javatools.trace causes parameter conversion, formatting, and output to all be done synchronously on the calling thread.

Sometimes, it is useful to see stack traces for some or all of the trace(java.lang.String) invocations. If javatools.trace includes the directive name "#stack" (or "#stacks"), each message will include the stack trace (of course, this is most useful when the trace volume is low). To trim the size of the stacks that are printed, a count or a stop filter can be appended to " #stack" with a colon or semicolon: a leading digit indicates that a count follows, any other leading character indicates that a fully-qualified class name prefix at which to stop the trace follows, e.g., "#stack:10" or "#stack:java.awt.EventQueue".

The formatting methods are public and can be used independently of the trace methods, for example to format the second expression of an assert statement. The formatting implementation supports only the basic {0}, {1}, etc, parameter substitution of MessageFormat, but is more robust in the face of null and insufficient arguments. Additionally, it allows custom formatters to be plugged in for specific value types. By default, custom formatters are defined for arrays to format them like collections.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Log.Formatter An object which formats a value into a StringBuffer.

Field Summary

Fields

Modifier and Type	Field and Description
static long	TIME_ZERO_MILLI Time, in milliseconds as given by System.currentTimeMillis(), at which this class was initialized.
static long	TIME_ZERO_NANO Time, in nanoseconds as given by System.nanoTime(), at which this class was initialized.

Constructor Summary

Constructors

Constructor and Description
Log(java.lang.String... names) Creates a named log with multiple names.
Log(java.lang.String name) Creates a named log.

Method Summary

Modifier and Type	Method and Description
static void	addFormatter(java.lang.Class type, Log.Formatter formatter) Sets a formatter for a type.
static java.lang.StringBuffer	append(java.lang.StringBuffer buffer, java.lang.Object object) Appends a text representation of an object to a string buffer.
static void	append(java.lang.StringBuffer buffer, java.lang.String message, java.lang.Object[] arguments) Appends a formatted string from a template string and an array of arguments to a StringBuffer.
static java.lang.StringBuffer	appendNow(java.lang.StringBuffer buffer) Format and append the current time.
static java.lang.StringBuffer	appendTime(java.lang.StringBuffer buffer, long nanoTime) Format and append a time.
static java.lang.StringBuffer	appendTranslatedTime(java.lang.StringBuffer buffer, long nanoTime) Format and append an already translated time.
static void	error(java.lang.String message)
static void	error(java.lang.String message, java.lang.Object p1) Logs an error message with one argument.
static void	error(java.lang.String message, java.lang.Object[] parameters) Logs an error message with an array of arguments.
static void	error(java.lang.String message, java.lang.Object p1, java.lang.Object p2) Logs an error message with two arguments.
static void	error(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3) Logs an error message with three arguments.
static void	error(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4) Logs an error message with four arguments.
static void	error(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5) Logs an error message with five arguments.
static java.lang.String	format(java.lang.String message, java.lang.Object[] arguments) Gets a formatted string from a template string and an array of arguments.
static java.lang.String	formatNow() Format the current time.
static java.lang.String	formatTime(long nanoTime) Format a time.
static java.lang.String	formatTranslatedTime(long nanoTime) Format an already translated time.
static Log.Formatter	getFormatter(java.lang.Class objectType) Gets the formatter for a type.
static Log.Formatter	getFormatter(java.lang.Object object) Gets the formatter for an object.
java.lang.String	getName() Gets the name of this log.
boolean	isEnabled() Gets whether this log is enabled.
boolean	stack(java.lang.String message, java.lang.Object... parameters) Trace a message with an arbitrary number of arguments and the current stack trace.
boolean	trace(java.lang.String message) Trace a message with no arguments.
boolean	trace(java.lang.String message, boolean p1)
boolean	trace(java.lang.String message, boolean p1, boolean p2)
boolean	trace(java.lang.String message, boolean p1, java.lang.Object p2)
boolean	trace(java.lang.String message, int p1)
boolean	trace(java.lang.String message, int p1, int p2)
boolean	trace(java.lang.String message, int p1, int p2, int p3)
boolean	trace(java.lang.String message, int p1, int p2, int p3, int p4)
boolean	trace(java.lang.String message, int p1, int p2, int p3, java.lang.Object p4)
boolean	trace(java.lang.String message, int p1, int p2, java.lang.Object p3)
boolean	trace(java.lang.String message, int p1, int p2, java.lang.Object p3, java.lang.Object p4)
boolean	trace(java.lang.String message, int p1, int p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5)
boolean	trace(java.lang.String message, int p1, java.lang.Object p2)
boolean	trace(java.lang.String message, int p1, java.lang.Object p2, java.lang.Object p3)
boolean	trace(java.lang.String message, int p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
boolean	trace(java.lang.String message, int p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5)
boolean	trace(java.lang.String message, long p1)
boolean	trace(java.lang.String message, long p1, java.lang.Object p2)
boolean	trace(java.lang.String message, java.lang.Object... parameters) Trace a message with an arbitrary number of arguments.
boolean	trace(java.lang.String message, java.lang.Object p1) Trace a message with one argument.
boolean	trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2) Trace a message with two arguments.
boolean	trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3) Trace a message with three arguments.
boolean	trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4) Trace a message with four arguments.
boolean	trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5) Trace a message with five arguments.

Methods inherited from class java.lang.Object

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

Field Detail

TIME_ZERO_NANO

public static final long TIME_ZERO_NANO

Time, in nanoseconds as given by System.nanoTime(), at which this class was initialized. This time is used as time zero for the time reported in the log messages; other classes can use it, for example in toString methods, to log time compatibly.

TIME_ZERO_MILLI

public static final long TIME_ZERO_MILLI

Time, in milliseconds as given by System.currentTimeMillis(), at which this class was initialized. This time corresponds as closely as possible to TIME_ZERO_NANO, which is time zero for the time reported in the log messages; other classes can use it, for example in toString methods, to log time derived from System.currentTimeMillis compatibly. Note however, that the two timers involved are not entirely compatible.

Constructor Detail

Log

public Log(java.lang.String name)

Creates a named log.

Parameters:

name - The name of this log.

Log

public Log(java.lang.String... names)

Creates a named log with multiple names.

Parameters:

names - The names of this log.

Method Detail

isEnabled

public boolean isEnabled()

Gets whether this log is enabled.

getName

public java.lang.String getName()

Gets the name of this log.

trace

public boolean trace(java.lang.String message)

Trace a message with no arguments.

trace

public boolean trace(java.lang.String message,
                     java.lang.Object p1)

Trace a message with one argument.

trace

public boolean trace(java.lang.String message,
                     int p1)

trace

public boolean trace(java.lang.String message,
                     long p1)

trace

public boolean trace(java.lang.String message,
                     boolean p1)

trace

public boolean trace(java.lang.String message,
                     java.lang.Object p1,
                     java.lang.Object p2)

Trace a message with two arguments.

trace

public boolean trace(java.lang.String message,
                     int p1,
                     java.lang.Object p2)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2)

trace

public boolean trace(java.lang.String message,
                     long p1,
                     java.lang.Object p2)

trace

public boolean trace(java.lang.String message,
                     boolean p1,
                     java.lang.Object p2)

trace

public boolean trace(java.lang.String message,
                     boolean p1,
                     boolean p2)

trace

public boolean trace(java.lang.String message,
                     java.lang.Object p1,
                     java.lang.Object p2,
                     java.lang.Object p3)

Trace a message with three arguments.

trace

public boolean trace(java.lang.String message,
                     int p1,
                     java.lang.Object p2,
                     java.lang.Object p3)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     java.lang.Object p3)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     int p3)

trace

public boolean trace(java.lang.String message,
                     java.lang.Object p1,
                     java.lang.Object p2,
                     java.lang.Object p3,
                     java.lang.Object p4)

Trace a message with four arguments.

trace

public boolean trace(java.lang.String message,
                     int p1,
                     java.lang.Object p2,
                     java.lang.Object p3,
                     java.lang.Object p4)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     java.lang.Object p3,
                     java.lang.Object p4)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     int p3,
                     java.lang.Object p4)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     int p3,
                     int p4)

trace

public boolean trace(java.lang.String message,
                     java.lang.Object p1,
                     java.lang.Object p2,
                     java.lang.Object p3,
                     java.lang.Object p4,
                     java.lang.Object p5)

Trace a message with five arguments.

trace

public boolean trace(java.lang.String message,
                     int p1,
                     java.lang.Object p2,
                     java.lang.Object p3,
                     java.lang.Object p4,
                     java.lang.Object p5)

trace

public boolean trace(java.lang.String message,
                     int p1,
                     int p2,
                     java.lang.Object p3,
                     java.lang.Object p4,
                     java.lang.Object p5)

trace

public boolean trace(java.lang.String message,
                     java.lang.Object... parameters)

Trace a message with an arbitrary number of arguments.

stack

public boolean stack(java.lang.String message,
                     java.lang.Object... parameters)

Trace a message with an arbitrary number of arguments and the current stack trace.

addFormatter

public static void addFormatter(java.lang.Class type,
                                Log.Formatter formatter)

Sets a formatter for a type.

format

public static java.lang.String format(java.lang.String message,
                                      java.lang.Object[] arguments)

Gets a formatted string from a template string and an array of arguments. The formatted string is the template string with occurrences of "{0}", "{1}", etcetera, replaced with the String representation of the corresponding argument.

append

public static void append(java.lang.StringBuffer buffer,
                          java.lang.String message,
                          java.lang.Object[] arguments)

Appends a formatted string from a template string and an array of arguments to a StringBuffer. The formatted string is the template string with occurrences of "{0}", "{1}", etcetera, replaced with the String representation of the corresponding argument.

append

public static java.lang.StringBuffer append(java.lang.StringBuffer buffer,
                                            java.lang.Object object)

Appends a text representation of an object to a string buffer. The text is formatted by the Log.Formatter returned by getFormatter().

getFormatter

public static Log.Formatter getFormatter(java.lang.Object object)

Gets the formatter for an object.

getFormatter

public static Log.Formatter getFormatter(java.lang.Class objectType)

Gets the formatter for a type.

error

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

error

public static void error(java.lang.String message,
                         java.lang.Object p1)

Logs an error message with one argument.

error

public static void error(java.lang.String message,
                         java.lang.Object p1,
                         java.lang.Object p2)

Logs an error message with two arguments.

error

public static void error(java.lang.String message,
                         java.lang.Object p1,
                         java.lang.Object p2,
                         java.lang.Object p3)

Logs an error message with three arguments.

error

public static void error(java.lang.String message,
                         java.lang.Object p1,
                         java.lang.Object p2,
                         java.lang.Object p3,
                         java.lang.Object p4)

Logs an error message with four arguments.

error

public static void error(java.lang.String message,
                         java.lang.Object p1,
                         java.lang.Object p2,
                         java.lang.Object p3,
                         java.lang.Object p4,
                         java.lang.Object p5)

Logs an error message with five arguments.

error

public static void error(java.lang.String message,
                         java.lang.Object[] parameters)

Logs an error message with an array of arguments.

formatNow

public static java.lang.String formatNow()

Format the current time. The time is translated by TIME_ZERO_NANO and formatted as decimal seconds with microsecond precision.

Returns:

The formatted string.

formatTime

public static java.lang.String formatTime(long nanoTime)

Format a time. The time is translated by TIME_ZERO_NANO and formatted as decimal seconds with microsecond precision.

Parameters:

nanoTime - A time in nanoseconds, e.g., from System.nanoTime().

Returns:

The formatted string.

formatTranslatedTime

public static java.lang.String formatTranslatedTime(long nanoTime)

Format an already translated time. The time is formatted as decimal seconds with microsecond precision.

Parameters:

nanoTime - A time in nanoseconds, e.g., from System.nanoTime().

Returns:

The formatted string.

appendNow

public static java.lang.StringBuffer appendNow(java.lang.StringBuffer buffer)

Format and append the current time. The time is translated by TIME_ZERO_NANO and formatted as decimal seconds with microsecond precision.

appendTime

public static java.lang.StringBuffer appendTime(java.lang.StringBuffer buffer,
                                                long nanoTime)

Format and append a time. The time is translated by TIME_ZERO_NANO and formatted as decimal seconds with microsecond precision.

Parameters:

nanoTime - A time in nanoseconds, e.g., from System.nanoTime().

appendTranslatedTime

public static java.lang.StringBuffer appendTranslatedTime(java.lang.StringBuffer buffer,
                                                          long nanoTime)

Format and append an already translated time. The time is formatted as decimal seconds with microsecond precision.

Parameters:

nanoTime - A time in nanoseconds, e.g., from System.nanoTime().