public final class Log
extends java.lang.Object
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);
// Do the work
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);
// Do the work
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.
Modifier and Type | Class and Description |
---|---|
static interface |
Log.Formatter
An object which formats a value into a
StringBuffer . |
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 and Description |
---|
Log(java.lang.String... names)
Creates a named log with multiple names.
|
Log(java.lang.String name)
Creates a named log.
|
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.
|
public static final long TIME_ZERO_NANO
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.public static final long TIME_ZERO_MILLI
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.public Log(java.lang.String name)
name
- The name of this log.public Log(java.lang.String... names)
names
- The names of this log.public boolean isEnabled()
public java.lang.String getName()
public boolean trace(java.lang.String message)
public boolean trace(java.lang.String message, java.lang.Object p1)
public boolean trace(java.lang.String message, int p1)
public boolean trace(java.lang.String message, long p1)
public boolean trace(java.lang.String message, boolean p1)
public boolean trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2)
public boolean trace(java.lang.String message, int p1, java.lang.Object p2)
public boolean trace(java.lang.String message, int p1, int p2)
public boolean trace(java.lang.String message, long p1, java.lang.Object p2)
public boolean trace(java.lang.String message, boolean p1, java.lang.Object p2)
public boolean trace(java.lang.String message, boolean p1, boolean p2)
public boolean trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
public boolean trace(java.lang.String message, int p1, java.lang.Object p2, java.lang.Object p3)
public boolean trace(java.lang.String message, int p1, int p2, java.lang.Object p3)
public boolean trace(java.lang.String message, int p1, int p2, int p3)
public boolean trace(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
public boolean trace(java.lang.String message, int p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
public boolean trace(java.lang.String message, int p1, int p2, java.lang.Object p3, java.lang.Object p4)
public boolean trace(java.lang.String message, int p1, int p2, int p3, java.lang.Object p4)
public boolean trace(java.lang.String message, int p1, int p2, int p3, int p4)
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)
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)
public boolean trace(java.lang.String message, int p1, int p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5)
public boolean trace(java.lang.String message, java.lang.Object... parameters)
public boolean stack(java.lang.String message, java.lang.Object... parameters)
public static void addFormatter(java.lang.Class type, Log.Formatter formatter)
public static java.lang.String format(java.lang.String message, java.lang.Object[] arguments)
public static void append(java.lang.StringBuffer buffer, java.lang.String message, java.lang.Object[] arguments)
public static java.lang.StringBuffer append(java.lang.StringBuffer buffer, java.lang.Object object)
Log.Formatter
returned by getFormatter().public static Log.Formatter getFormatter(java.lang.Object object)
public static Log.Formatter getFormatter(java.lang.Class objectType)
public static void error(java.lang.String message)
public static void error(java.lang.String message, java.lang.Object p1)
public static void error(java.lang.String message, java.lang.Object p1, java.lang.Object p2)
public static void error(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
public static void error(java.lang.String message, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
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)
public static void error(java.lang.String message, java.lang.Object[] parameters)
public static java.lang.String formatNow()
TIME_ZERO_NANO
and formatted as decimal seconds with microsecond precision.public static java.lang.String formatTime(long nanoTime)
TIME_ZERO_NANO
and
formatted as decimal seconds with microsecond precision.nanoTime
- A time in nanoseconds, e.g., from System.nanoTime().public static java.lang.String formatTranslatedTime(long nanoTime)
nanoTime
- A time in nanoseconds, e.g., from System.nanoTime().public static java.lang.StringBuffer appendNow(java.lang.StringBuffer buffer)
TIME_ZERO_NANO
and formatted as decimal seconds with microsecond
precision.public static java.lang.StringBuffer appendTime(java.lang.StringBuffer buffer, long nanoTime)
TIME_ZERO_NANO
and formatted as decimal seconds with microsecond precision.nanoTime
- A time in nanoseconds, e.g., from System.nanoTime().public static java.lang.StringBuffer appendTranslatedTime(java.lang.StringBuffer buffer, long nanoTime)
nanoTime
- A time in nanoseconds, e.g., from System.nanoTime().