In a java.util.logging logging.properties file, what's the difference between "handlers" and ".handlers"?

Question

In the documentation of LogManager, the following is set of the Handlers property:

A property "handlers". This defines a whitespace or comma separated list of class names for handler classes to load and register as handlers on the root Logger (the Logger named "").

A property ".handlers". This defines a whitespace or comma separated list of class names for handlers classes to load and register as handlers to the specified logger. Each class name must be for a Handler class which has a default constructor. Note that these Handlers may be created lazily, when they are first used.

Since the name of the root logger is the empty string (""), it seems to me like both of the clauses below should be equivalent:

handlers = myHandler
.handlers = myHandler

Here's an example from the JDK's lib/logging.properties file:

handlers= java.util.logging.ConsoleHandler
.level= INFO

I've noticed that weird things are happening when I attempt to enumerate the handlers on the root logger. I suspect that this has to do with the implementation of LogManager referring to one of those properties. However, I'd like to try and understand whether I am correct in my assumption of equivalency.

To clarify: My goal with this question is to understand whether the behaviour should be identical.

Florrie

Answer 1

The reason there are two different ways is due to New Features in J2SE 5.0. In J2SE 1.4, you could only add handlers to the root logger using the handlers property.

Per the Java 1.4 LogManager JavaDocs:

A property "handlers". This defines a whitespace separated list of class names for handler classes to load and register as handlers on the root Logger (the Logger named ""). Each class name must be for a Handler class which has a default constructor. Note that these Handlers may be created lazily, when they are first used.

As you can see from the JavaDocs you posted the documentation was revised removing the part about created lazily.

In Java 5, JDK-4635817 : Attaching handlers to loggers using logging config file was fixed by allowing the use of .handlers Due to backward compatibility, the LogManager had to support both the old and the new ways of installing handlers.

For the most part handlers and .handlers are equivalent except:

1. Using handlers will only load your handler when a LogRecord is published to the root logger handlers. If you never log anything the handler is never loaded.
2. Using .handlers will attach your handler during creation of the root logger.
3. If you use both together then the union of both properties are applied to the root logger using rules #1 and #2.

Subclasses of LogManager like org.apache.juli.ClassLoaderLogManager used in Tomcat apply different rules from what is listed above.

JDK 9 has a regression that will be fixed where .handlers doesn't work correctly. This is filed under: JDK-8191033 Regression in logging.properties: specifying .handlers= for root logger (instead of handlers=) no longer works.

Pylos

Thank you so much! So I was able to determine this behaviour from the source code of LogManager, but could not pin down the reason. The links are very helpful. I wish this had been better clarified in the documentation. – Florrie

Answer 2

Looking through the source code of LogManager, it looks like the 2 properties ".handlers" and "handlers" are treated slightly different.

The property "handlers" if present causes root logger's handlers to be initialized before any other logger's handlers. If ".handlers" is used instead this initialization will happen, but later than the log manager expects it to.

The "weird things" that you are seeing might be related to this delayed initialization handlers.

Sharpedged

That's what I've seen when debugging my local version (from OpenJDK). However, I'm trying to understand whether LogManager should have been handling both as equivalent. – Florrie