Manages the reporting of status messages for a Java program, messages that you create for monitoring the program (either during development or when a runtime error has occurred).

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 manages a set of log streams that are defined at runtime as a result of one of the preceding techniques. Filters are set for each log stream.

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.

Writing log information with put, putLine, print, and println

You use the put, putLine, print, and println methods to send information to the log stream. 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.

netbeans.logger.settings Property

The netbeans.logger.settings property determines default logging settings. When a  TraceLogger object is created, its constructor looks for this property and uses its settings to create the specified log streams. If the constructor cannot find this property, it sets the netbeans.logger.settings string "%stdout(err:*)", causing a single log stream to be created that writes all error messages to the standard output.

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:*)
netbeans.logger.settings File Name Parameter
netbeans.logger.settings can specify one or more files to be used for logging certain messages. The file names %stdout and %stderr specify logging to standard output or standard error, respectively.

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.

netbeans.logger.settings File Filter Parameter
For each file name, you specify a file filter, which determines which logging messages are written to that log file. You can specify up to four types of filters for each file, separated by a space. You must always specify the first filter type (message type). The other three filter types are optional, and further qualify the information that is logged. The syntax for a file filter is

(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:

Message Type

The message_type parameter describes the general logging category of the message, and is specified by one of the following static fields:
 
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.
Message type indicators
The TraceLogger class maintains a set of static fields with the same names as those indicated under "netbeans.logger.settings Value" that indicate that one or more flags of a particular message type have been set for some log stream. You can use these fields to test whether any messages of a particular type have been set before performing the work needed to print a method. It can improve performance to test these boolean fields before constructing and printing a message.

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);

Module Name

The module_name parameter describes which module or part of the system is producing this message. The TraceLogger maintains a dynamic list of modules, along with an integer module identifier for each. Modules are added to this list when specified in a set of logger settings (either during startup or via TraceLogger.modifyFlags), or when TraceLogger.getModuleID is called with a module identifier. A module name in the logger settings is just a string uniquely identifying the module; this is usually the fully-qualified package name for the module, e.g. com.netbeans.modules.servlet. Inside a module's code, the same string used in the logger settings is used to obtain an integer module identifier from the logger (using TraceLogger.getModuleID). This module identifier is then passed to the log methods such as println and put.

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.

Group Number

Each module can arbitrarily divide the messages it produces into groups, identified by a number from 1 to 63. Typically these flags are assigned to diagnostic or performance messages, where it is useful to be able to select various message subsets.

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);

Level Number

The fourth optional filter is the level, an arbitrary integer ranging from 1 to 255 that indicates how detailed the message content is. For example, messages at level 1 are very high-level and superficial. Usually not very many of them are produced. Messages at higher level numbers give more detail.

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);

Configuration flags

You can set the following configuration flags to affect how the TraceLogger features work: