|
Oracle Fusion Middleware Java API Reference for Oracle Extension SDK 11g Release 2 (11.1.2.3.0) E17493-04 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object
oracle.javatools.util.Log
public final class Log
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 |
---|
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 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 |
---|
public Log(java.lang.String name)
name
- The name of this log.public Log(java.lang.String name1, java.lang.String name2)
name1
- A name of this log.name2
- A name of this log.public Log(java.lang.String name1, java.lang.String name2, java.lang.String name3)
name1
- A name of this log.name2
- A name of this log.name3
- A name of this log.public Log(java.lang.String[] names)
names
- The names of this log.Method Detail |
---|
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 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 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 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)
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 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().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.3.0) E17493-04 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |