Package org.lsst.ccs.utilities.logging

This package provides proxies to the standard java.util.logging package.

See: Description

Class Summary

Class	Description
ConsoleHandlerN	A Console handler that detects duplicate logs.
FileHandlerN
IsLoggableDelegate	A utility to plug into Handlers that want to detect duplicate logs.
JULAppender	simple bridge from Log4J to JUL.
Logger	Just a wrapper class around java.util.Logger to add specific logging methods.
LogManagement	Ths static initialization of this class should be fired early in an application by doing
SocketHandlerN	A SocketHandler that detects duplicate publications.Y
StreamHandlerN	: A StreamHandler that detects duplicate publications.

Package org.lsst.ccs.utilities.logging Description

This package provides proxies to the standard java.util.logging package.
Its Logger class is only for codes that log messages or data (not for codes that deal with Level, Formatters or Handlers). It provides methods that can simply replace logging invocations meant to be handled by Log4J or simple standard java logging invocations: you can then in your codes just change the import directives and keep you code "as is".

So you have for instance :

     Logger logger = Logger.getLogger("org.lsst.ccs.mypackage") ;
     //....
     logger.info("doing the right thing!") ;
     //...
     if( logger.isInfoEnabled() ) {
         logger.log(Level.INFO, "still better", methodCall()) ;
     }
     //...
     try {
         //...
     } catch(Exception exc) {
         logger.error("Oops!", exc) ;
     }
 

But the Logger class is not only to get syntactic sugar: it provides access to "multi-dimensional logging".

What's that?

The idea is that can log the same call to different loggers in a single invocation. So, for instance, you have the usual logger linked to a package but you want also to address different "concerns" that are common to different classes or package. Then you can write:

     logger.log(Level.INFO, "Object being initialized", theObject, "INIT");
 

this means that the created LogRecord will be submitted to the current Logger and also to another one named "INIT".
Thus you can create many "transversal" loggers named "INIT", "CONFIG", "MOVE" (or whatever you want) and then you will be able to handle log informations reporting specifically about one of this "concerns".

     logger.log(Level.INFO, "Object being moved at initialisation", theObject, "INIT", "MOVE");
 

Then you can set the level for the corresponding package to SEVERE and set the level of the "INIT" concern to INFO .
All the logging methods of the Logger class takes an optional String... variable argument list where you can name concerns.

Then you can handle real java.util.logging.Loggers that bear a name of package or a name of concern. Then you can use setLevel or addHandler methods to this actual loggers (of type java.util.logging.Logger). But you should note there are changes to the way Handlers should be defined and to the configuration file (if you want to pilot logging through a configuration file).

Handler design

Since the same LogRecord might be provided to different Loggers then a Handler may receive many publish requests for the same LogRecord! It means that the Handlers should memorize which records are published and not report twice the same record.
Special handlers are provided to check for duplicates: ConsoleHandlerN, StreamHandlerN, SocketHandlerN, ... all rely on the service of a IsLoggableDelegate that checks the records for multiple publishing.

Configuration file

There is a logging.properties file to define the behaviour of loggers ans handlers: though this file is in the standard format of java.util.logging it is positioned in a different way:

• it is considered a better policy to put the file at a global level of the CLASSPATH. ("/logging.propertie" in resource handling syntax).
• to obtain this behaviour call Class.forName("org.lsst.ccs.utilities.logging.LogManagement early in your main (this will call static initialization code)

Example of a logging.properties file:

 # Properties file which configures the operation of the CCS
 # logging facility.

 # The system will look for this config file, first using
 # a System property specified at startup:
 #
 # java -Dorg.lsst.ccs.resources.directory=myLoggingConfigFilePath
 #
 # If this property is not specified, then the config file is
 # retrieved from its default location at:
 #
 # GENERAL_RESOURCES_DIRECTORY/logging.properties

 # Global logging properties.
 # ------------------------------------------
 # The set of handlers to be loaded upon startup.
 # Comma-separated list of class names.
 # (? LogManager docs say no comma here, but JDK example has comma.)
 # handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler
 handlers=org.lsst.ccs.utilities.logging.ConsoleHandlerN
 ## BEWARE: you CAN'T set  org.lsst.ccs.bus.utils.LogBusHandler HERE!
 ## because it is initialized later (when the buses are activated)

 # Default global logging level.
 # Loggers and Handlers may override this level
 .level=WARNING

 # Loggers
 # ------------------------------------------
 # Loggers are usually attached to packages.
 # Here, the level for each package is specified.
 # The global level is used by default, so levels
 # specified here simply act as an override.
 #myapp.ui.level=ALL
 #myapp.business.level=CONFIG
 #myapp.data.level=SEVERE
 org.lsst=WARNING

 # Handlers
 # -----------------------------------------

 # --- ConsoleHandler ---
 # Override of global logging level
 #java.util.logging.ConsoleHandler.level=SEVERE

 org.lsst.ccs.utilities.logging.ConsoleHandlerN.level=WARNING
 ## BEWARE: you CAN'T set the Level of org.lsst.ccs.bus.utils.LogBusHandler HERE!
 ## because it is initialized later (when the buses are activated)
 ## to set this handler's level without invoking a command use property "org.lsst.ccs.logbuslevel"