oracle.javatools.util
Class Log

java.lang.Object
  oracle.javatools.util.Log

public final class Log
extends java.lang.Object

A simple error and trace log. Error logging is always enabled and is done through the static error methods. Trace logging is disabled by default and is done through the non-static trace methods.

Log instances used for trace logging are created with a name and are enabled by name at application launch using the System property audit.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 audit.trace property is a list of trace names to enable, separated by commas. By default, traces are logged to System.err. If a name begins with "!", the rest of that name is interpreted as the name of the file to which to log; the names "!output" and "!error" are mapped to System.out and System.err, respectively. To launch JDeveloper with the audit.trace property set to "traversal", use the following command line:

   jdev -J-Daudit.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 -Daudit.trace=traversal
 

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 DETAILLOG = new Log("profile-detail");
 .
 .
 public void save (URL url)
 {
   LOG.trace("saving profile to {0}", url);
   .
   .
   DETAILLOG.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 DETAILLOG; enabling "profile-detail" enables tracing to both logs.

To minimize the runtime impact of enabled logging, by default, formatting and output are not done in the calling thread, but in a minimal priority background thread. An important consequence of this is that objects passed as parameters should generally be immutable, or more precisely, the state used by their toString methods should be immutable.

It is sometimes desirable for the logging output to be synchronous (e.g., to preserve the sequencing relationship with other output that does not use this class). If audit.trace includes the pseudo trace name "!synchronous", output will be done synchronously.

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}, etcetera, 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

static interface

Log.Formatter An object which formats a value into a StringBuffer.

Field Summary

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 nanonseconds as given by System.nanoTime(), at which this class was initialized.

Constructor Summary

Log(java.lang.String name)
Creates a named log.

Log(java.lang.String[] names)
Creates a named log with multiple names.

Log(java.lang.String name1, java.lang.String name2)
Creates a named log with two names.

Log(java.lang.String name1, java.lang.String name2, java.lang.String name3)
Creates a named log with three names.

Method Summary

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 void	appendTime(java.lang.StringBuffer buffer, long time, char[] timeBuffer)
static void	error(java.lang.String message) Logs an error message with no arguments.
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	formatTime(long time)
static java.lang.String	formatTranslatedTime(long 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	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 p1) Trace a message with one argument.
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, 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 nanonseconds 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 posible 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 to 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 name1,
           java.lang.String name2)

Creates a named log with two names.

Parameters:

name1 - A name of this log.

name2 - A name of this log.

Log

public Log(java.lang.String name1,
           java.lang.String name2,
           java.lang.String name3)

Creates a named log with three names.

Parameters:

name1 - A name of this log.

name2 - A name of this log.

name3 - A 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

error

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

Logs an error message with no arguments.

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.

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.

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.

formatTime

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

formatTranslatedTime

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

appendTime

public static void appendTime(java.lang.StringBuffer buffer,
                              long time,
                              char[] timeBuffer)