This package defines the following classes:
Each process can have only one TraceLogger object. You must use the static TraceLogger.getTraceLogger method to access the TraceLogger object. An object of this class is created the first time you invoke the getTraceLogger method.
You can control the logging of messages in a number of ways, all of which control which messages get reported and where they are sent:
TraceLogger supports a single event: the LoggerChangedEvent. This event notifies registered objects when changes to the log settings are made. Any action that changes the flag settings or opens a new log stream will cause this event to be posted.
TraceLogger lets you specify whether to print a timestamp appended to the beginning of output log message by setting a configuration flag. To set this flag in the netbeans.logger.settings system property or using the modifyFlags method, specify the following setting: cfg:logger:5.
lgr.println(TraceLogger.ERROR, moduleId, LogFlags.DBG_DISTCON, 5, "Printing a message with objects included. {0}. {1}. {2}." new Integer(4), "Hi!", new Boolean(true));This code should print out:
Printing a messages with objects included. 4. Hi!. true.The put, putLine, print, and println methods are overloaded. The simpler versions print directly to all the open log streams. The more complex versions allow you to filter out specific messages based on message types and levels of detail. Filtering is described later.
The netbeans.logger.settings property can specify up to four types of filters for one or more log streams. The syntax for netbeans.logger.settings is
file_name(file_filter)[file_name(file_filter)...]For example, while developing and debugging an application, trace messages are particularly useful. You could set netbeans.logger.settings to specify that all trace messages are displayed on standard output, as follows:
%stdout(dbg:*)
Several files can be specified for logging messages. Multiple logging files are useful, for example, if general tracing is to be displayed on standard output (%stdout), but detailed tracing is to be logged to a file for later review.
On Windows only, the name %stdwin creates a simple, scrollable window for text output, which is particularly useful for specifying as an alternative file for the output.
(message_type[ :module_name[ :group_number[:level_number]]])
The four filter types are described in the next four sections as they are used in put and print method parameters. It is not necessary to use these filter types when you invoke a put or print method. However, if you want to specify a particular log stream, you must describe what kind of message is to be written. This description consists of 4 parameters:
TraceLogger Static field | Message Category | netbeans.logger.settings Value |
---|---|---|
ERROR | Error messages | err |
SECURITY | Security messages | sec |
RESOURCE | Resource allocation events | res |
AUDIT | Auditing messages | aud |
CONFIGURATION | Configuration settings that change how the program functions | cfg |
PERFORMANCE | Performance logging data | prf |
DEBUG | Diagnostic trace messages | dbg |
* | All message types | Can only be specified if a module name is also specified. |
For example, it can be significantly more efficient to structure the statements that print your messages as follows, because the TraceLogger only needs to test whether the specified resource flag is set if any resource flags have been set:
TraceLogger lgr = TraceLogger.getTraceLogger(); int modId = TraceLogger.getModuleId("com.myModule1"); if (TraceLogger.res) lgr.println(TraceLogger.RESOURCE, modId, 5, 25, "The database {0} has started with the following settings: {1}.", db.name, settings);
You can specify *; to indicate that you want the filter to apply to all modules if you also specify a specific message type. For example, you could specify dbg:* to indicate that all trace messages for modules be printed. This filter would be in effect for all modules as the default settings for all trace messages. However, if you then change the flags for a specific module, the most current change would be in effect. For example, if you specify for modifyFlags the settings "-(dbg:com.mymod1)", the original dbg:* settings would apply to all modules except com.mymod1.
For example, a module named com.module1 could be divided into three groups of messages about transactions in progress, queued work lists, and problem reports. If transactions in progress is group 2, and problem reports is group 4, the following TraceLogger specification puts performance information from group 2 into one file and trace information from group 4 into another file:
xactprog.prf(prf:com.module3:2) probrep.dbg(dbg:com.module3:4)The group number you specify in a put method can be a constant that you define. For example, if the literal 2 indicates the "transaction in progress" group and the value of a final static field named TRANSACT_IN_PROGRESS is 2, you could invoke putLine as follows:
int moduleId; moduleId = TraceLogger.getTraceLogger().getModuleId("com.netbeans.modules.servlet"); TraceLogger.getTraceLogger().putLine(TraceLogger.PERFORMANCE, moduleId, TRANSACT_IN_PROGRESS, 1, perfTextData);
The level number is determined by the application. Typically, you use levels to filter trace messages. The following netbeans.logger.settings example indicates that all level 1 trace data from group 2 (transactions in progress) of the module named com.module1 should be printed to standard output:
%stdout(dbg:com.module1:2:1)
The following code sample outputs one line:
TraceLogger log = TraceLogger.getTraceLogger();
// Printed when the filter sets the level >= 1 int moduleID = log.getModuleId("com.module1"); log.put(TraceLogger.DEBUG, moduleID, TRANSACT_IN_PROGRESS, 1, "Browsing account #"'); log.putLine(TraceLogger.DEBUG, moduleID, TRANSACT_IN_PROGRESS, 1,acc.Number);
// Not printed when the filter sets the level <= 1 log.put(TraceLogger.DEBUG, moduleID, TRANSACT_IN_PROGRESS, 2,acc.Owner); log.put(TraceLogger.DEBUG, moduleID, TRANSACT_IN_PROGRESS, 2,acc.LastChangeDate);
You can set the following configuration flags to affect how the TraceLogger features work: