SLF4J: Bridge vs Migrator JARs

Question

SLF4J (1.7.5, but really any modern version) ships with several "over" (migrator) JARs:

• jcl-over-slf4j-1.7.5.jar
• log4j-over-slf4j-1.7.5.jar

...as well as a "to" (bridge) JAR:

• jul-to-slf4j-1.7.5.jar

According to their docs, a migrator:

...ease[s] migration to SLF4J from [JCL/log4j]. This jar file is intended as a drop-in replacement for [JCL/log4j]. It implements the[ir] public API but using SLF4J underneath, hence the name "over" SLF4J.

Whereas, the JUL bridge:

routes all incoming jul records to the SLF4j API.

1. Do I use jcl-over-slf4j-1.7.5.jar when I have code that logs using JCL, but I want it to use SLF4J? Or something else?
2. When would I use jul-to-slf4j-1.7.5.jar? How is the word "to" here used differently than "over"?
3. Why is there no "over" JAR for JUL? Why are there no "to" JARs for JCL and log4j?

Answer 1

First of all, these jars are intended for situations where your project has dependencies out of your control, and these dependencies make use of JUL (java.util.logging), JCL (Jakarta Commons Logging) or log4j and you would like to route all logging operations through the slf4j-api. Think of it as dynamically replacing all calls to those legacy logging apis with slf4j-api equivalents.

Each one of these 3 jars does the same thing for its respective legacy logging framework. The difference in naming (over vs to) stems from the way this translation is accomplished.

With the above in mind here are the answers to your questions:

1. If the code is under your control, you might as well replace all JCL calls with proper slf4j-api calls (same goes for any other legacy framework). If the source code is out of your control or you can't be bothered to replace them, you can include jcl-over-slf4j-1.7.5.jar in your classpath and exclude commons-logging.jar. That's because jcl-over-slf4j-1.7.5.jar contains the same classes (or a subset thereof) of commons-logging.jar rewritten to send all logging activity to slf4j-api. Hence the over name.

2. jul-to-slf4j-1.7.5.jar works its magic in a slightly different way - hence the to name. JUL makes use of handlers. A handler is any class that extends java.util.logging.Handler and is meant to handle (guess what) logging messages (or records in JUL terminology). So in this case, in order to route all JUL logging to slf4j-api we just need to make sure we register only one such handler - the SLF4JBridgeHandler (which happens to be the only class contained in jul-to-slf4j-1.7.5.jar). The configuration options to do that can be found here.

3. The difference between over and to should now be evident. The over jars work by replacing the very same classes of the original jars with ones that route all logging to slf4j-api. The JUL to jar doesn't need to do the same kind of class rewriting due to the way JUL operates with handlers (and you only need configure one handler that will route all logging to slf4j-api).

For more legacy notes check the excellent slf4j legacy documentation, and also be sure to check the big picture (also linked to from the main legacy article).

Hope this helps.

Answer 2

Do I use jcl-over-slf4j-1.7.5.jar when I have code that logs using JCL, but I want it to use SLF4J? Or something else?

You should use the jcl-over-slf4j.jar if you want to migrate your application from using JCL to SLF4J. Both JCL and SLF4J serves as a simple facade or abstraction for various logging frameworks, for example Log4J. SLF4J is considered a better solution than JCL as it solves various classloading issues related to the the JCL discovery mechanism. Note that the 1.1 release of JCL includes several changes that are intended to resolve those classloading issues.
There are several use cases where you would like to replace JCL with SLF4J:

• Solve class loader issues related to commons logging
• You realized that SLF4J is a better logging facade than JCL
• You would like to use logback which natively implements the SLF4J API

While you can completely replace the use of JCL with SLF4J by replacing the JCL API calls with SLF4J API calls, the JCL over SLF4J implementation will allow you to migrate to SLF4J gradually, especially if some of the libraries your software depends on continue to use JCL (for example the Spring Framework).

When would I use jul-to-slf4j-1.7.5.jar? How is the word "to" here used differently than "over"?

You should use the jul-to-slf4j-1.7.5.jar if your application is using java.util.logging (JUL) as its logging framework and you would like to replace it with SLF4J as a logging facade and have the freedom of choosing between other logging implementations . JUL provides the classes and interfaces of the JavaTM 2 platform's core logging facilities. Contrary to jcl-over-slf4j, which reimplement JCL, the jul-to-slf4j module does not reimplement the java.util.logging because packages under the java.* namespace cannot be replaced. Instead, jul-to-slf4j includes a java.util.logging (jul) handler, namely SLF4JBridgeHandler, which routes all incoming jul records to the SLF4j API. Notice the note SLF4J has about the performance of this solution.

Why is there no "over" JAR for JUL? Why are there no "to" JARs for JCL and log4j?

As described in previous section, packages under the java.* namespace cannot be replaced and therefore there is no possibility to create a "from" bridging module but rather use a solution which routes JUL API calls to SLF4J. For other bridging modules this overhead is simply not necessary.