Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.1.0)

E17493-02

oracle.javatools.util
Class Log

java.lang.Object
  extended by 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 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. 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 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
 

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, parameters are converted to text and the message is formatted and then written to the output stream. To minimize the runtime impact of enabled logging, formatting and writing are not done in the calling thread by default, but in a minimal priority background thread. Mutable fields make it unreliable in general to do parameter conversion on the background thread, but if javatools.trace includes the pseudo trace name "!asynchronous", then even parameter conversion will be deferred to the background thread.

Sometimes it is desirable tracing to be completely synchronous (e.g., to preserve the sequencing relationship with other output that does not use this class). If javatools.trace includes the pseudo trace name "!synchronous", parameter conversion, formatting, and output will be all be done in the calling thread.

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 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 void appendTime(java.lang.StringBuffer buffer, long time, char[] timeBuffer)
           
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)
          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 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 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 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 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.


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

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().

appendTime

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

Oracle Fusion Middleware Java API Reference for Oracle Extension SDK
11g Release 2 (11.1.2.1.0)

E17493-02

Copyright © 1997, 2011, Oracle. All rights reserved.