Presents your 
JAVA E-NEWSLETTER for May 1, 2003

<------------------------------------------->

TAKE A TOUR OF THE LOGGING.PROPERTIES FILE

One of the ways that the Java 1.4 logging package supports configuration
is through a properties file. The format of a properties file is
straightforward, but the sections could benefit from a little explanation. This
tip will explore, section by section, the default logging.properties 
file found in the JRE_PATH/lib directory.

The default logging.properties file starts off with an explanation of
how to set an alternate logging.properties file, complete with a sample
command line:

########################################################
#       Default Logging Configuration File
#
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.
# For example java -Djava.util.logging.config.file=myfile
############################################# ##########

To override the default properties file, you have to set a system
property specifying the name of the properties file you want to use.

The next section specifies global logging properties:

########################################################
#       Global properties
########################################################

# "handlers" specifies a comma separated list of log Handler
# classes. These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers= java.util.logging.ConsoleHandler

# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler,
java.util.logging.ConsoleHandler

The handlers property is where you define all of the handlers you want
to participate in the logging for your application. To specify handlers,
you provide a comma-separated list of class names that extend the
java.util.logging.Handler class. You can specify as many handlers as you like.
Classes listed as handlers must be loadable from the system classpath.

The next section sets the default level for all loggers to INFO:

# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overridden by a facility specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level= INFO

The level property sets the default logging level for all handlers. 
This logging level can be overridden by more specific settings later in the
file or by the implementation of the handler itself.

The next section sets properties specific to handlers:

########################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
########################################################

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = 
java.util.logging.XMLFormatter

# Limit the messages that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter =
java.util.logging.SimpleFormatter

The properties available for manipulation here are specific to the
handler. If you have custom or third-party handlers, this is the section where
you would set them. The properties are set by prepending the class name
of the handler and a dot to the name of the property you are setting.

The next section allows you to set logging levels for a specific logger.
These properties are set on the logger being used by the class, not the
handler:

########################################################
# Facility specific properties.
# Provides extra control for each logger.
########################################################

# For example, set the com.xyz.foo logger to only log SEVERE
# messages:
com.xyz.foo.level = SEVERE

The effect of these settings can be confusing, since they act on the
logger and not the handler. If the level setting is more restrictive than
the handler's setting, the logger's setting will override the handler's
setting. If the setting is less restrictive than the handler's setting, 
the handler's setting will override the logger's setting.

This happens because the logger sees a log record before making it to
the handler; so if the log level of the logger suppresses the record, 
the handler will never see the record.

----------------------------------------