Sending Logging Messages

The simplest way to send a message to the logging system is with the jsx3.log() method. The jsx3.log() method is simply a shortcut for sending a logging message of level INFO to the global logger (jsx3.util.Logger.GLOBAL.info()).

In General Interface Builder, inserting this method in your JavaScript code:

jsx3.log("a logging message");

prints the following line to the System Log palette if the default logging file is used:

15:26:35.138 global (INFO) - a logging message

When a message is sent to the logging system, it is sent through a logger instance, which has a unique name and can also have a specified log level. A logging message also has a level associated with it. If the message's log level matches or exceeds the logger log level, the logger forwards it to the registered handler. For more information, see Log Levels.

For more precise control of the logger and level of a logging message, the Logger class can be used. The static Logger.getLogger() method returns a logger instance of the given name. Note that loggers are instantiated dynamically and the getLogger() method always returns a logger instance, even if it's not specified in the logging system configuration file.

For example,

var log = jsx3.util.Logger.getLogger("com.tibco");

The Logger class defines an instance method named for each level:

log.error("a terrible error occurred");
log.debug("x was equal to " + x);

There are several other methods of the Logger class that are useful for logging. For more information, see General Interface API Reference.

It is best programming practice to design logging messages as a permanent part of the source code. It's useful to partition the logging messages that an application or library creates by category. Each category corresponds to a unique logger instance. One practice is to define a logger for each class in a system with a name equal to the fully qualified class name. Another common practice is to divide the system into a set of subsystems, each with its own logger.

Logging messages can be stripped from code before the code is deployed. This is necessary under logging systems that use standard out, (in JavaScript) window.alert(), or some other mechanism that is highly visible to both the developer and the user of an application.

In General Interface applications, there's no need to remove the logging messages from the source code, because the logging system is configured through a declarative XML file. The advantage to leaving logging messages in your code is that you can diagnose errors after deployment. Simply modify the logging system configuration file, run the deployed application, and determine what the errors are by viewing the logging messages.

The logging system is designed to impact the performance of General Interface applications as little as possible. The following code is a good example of how to send a logging message efficiently when constructing the message is expensive. The code simply checks the logger to see whether the logging message passes the logger's level before creating and sending the message.

var Logger = jsx3.util.Logger;
var log = Logger.getLogger("com.tibco");
if (log.isLoggable(Logger.INFO))
    log.info(xmlDoc.toString()); // serializing XML may be
                                 // expensive