0
# JUL to SLF4J Bridge
1

2
JUL to SLF4J Bridge provides a handler that routes all Java Util Logging (JUL) log records to the SLF4J API. This bridge enables legacy applications using JUL to integrate seamlessly with modern SLF4J-based logging frameworks by installing a single handler on the root logger.
3

4
## Package Information
5

6
- **Package Name**: jul-to-slf4j
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.slf4j
10
- **Artifact ID**: jul-to-slf4j
11
- **Module Name**: jul.to.slf4j (explicit module) / jul_to_slf4j (automatic module)
12
- **Installation**: 
13
  ```xml
14
  <dependency>
15
    <groupId>org.slf4j</groupId>
16
    <artifactId>jul-to-slf4j</artifactId>
17
    <version>2.0.17</version>
18
  </dependency>
19
  ```
20

21
For **Java 9+ modular applications** with explicit module-info.java:
22
```java
23
module your.app {
24
    requires jul.to.slf4j;
25
    // your other requirements
26
}
27
```
28

29
For **non-modular applications** on the module path, the Automatic Module Name is `jul_to_slf4j`:
30
```java
31
module your.app {
32
    requires jul_to_slf4j;  // Note: underscores, not dots
33
    // your other requirements
34
}
35
```
36

37
## Core Imports
38

39
```java
40
import org.slf4j.bridge.SLF4JBridgeHandler;
41
```
42

43
## Basic Usage
44

45
```java
46
import org.slf4j.bridge.SLF4JBridgeHandler;
47
import java.util.logging.Logger;
48

49
// Install the bridge to redirect all JUL logging to SLF4J
50
SLF4JBridgeHandler.removeHandlersForRootLogger();
51
SLF4JBridgeHandler.install();
52

53
// Now all JUL logging will be redirected to SLF4J
54
Logger julLogger = Logger.getLogger("com.example.MyClass");
55
julLogger.info("This message will be handled by SLF4J");
56

57
// Check if bridge is installed
58
if (SLF4JBridgeHandler.isInstalled()) {
59
    System.out.println("Bridge is active");
60
}
61

62
// Uninstall when needed
63
SLF4JBridgeHandler.uninstall();
64
```
65

66
## Architecture
67

68
The JUL to SLF4J bridge operates through a single handler class that:
69

70
- **Handler Installation**: Installs on JUL's root logger as the sole handler
71
- **Level Mapping**: Maps JUL levels to equivalent SLF4J levels (FINEST→TRACE, FINER→DEBUG, etc.)
72
- **Location Awareness**: Supports location-aware logging when available for better debugging
73
- **Resource Bundle Support**: Handles JUL message formatting with resource bundles
74
- **Thread Safety**: Safe for concurrent use in multi-threaded applications
75

76
## Capabilities
77

78
### Bridge Installation
79

80
Install the SLF4J bridge handler on the root logger to redirect all JUL logging.
81

82
```java { .api }
83
/**
84
 * Adds a SLF4JBridgeHandler instance to JUL's root logger
85
 */
86
public static void install();
87
```
88

89
### Bridge Removal
90

91
Remove previously installed SLF4J bridge handlers from the root logger.
92

93
```java { .api }
94
/**
95
 * Removes previously installed SLF4JBridgeHandler instances
96
 * @throws SecurityException if security manager exists and caller lacks LoggingPermission("control")
97
 */
98
public static void uninstall() throws SecurityException;
99
```
100

101
### Installation Status
102

103
Check whether the SLF4J bridge handler has been installed.
104

105
```java { .api }
106
/**
107
 * Returns true if SLF4JBridgeHandler has been previously installed
108
 * @return true if installed, false otherwise
109
 */
110
public static boolean isInstalled();
111
```
112

113
### Root Logger Cleanup
114

115
Remove all handlers from the root logger, typically called before installing the bridge.
116

117
```java { .api }
118
/**
119
 * Removes/unregisters all handlers currently attached to the root logger
120
 * @since 1.6.5
121
 */
122
public static void removeHandlersForRootLogger();
123
```
124

125
### Handler Instance Creation
126

127
Create a new SLF4JBridgeHandler instance for manual configuration.
128

129
```java { .api }
130
/**
131
 * Initialize this handler (no-op implementation)
132
 */
133
public SLF4JBridgeHandler();
134
```
135

136
### Log Record Processing
137

138
Process and redirect JUL log records to SLF4J loggers.
139

140
```java { .api }
141
/**
142
 * Publish a LogRecord by forwarding it to appropriate SLF4J logger
143
 * @param record Description of the log event (null records are silently ignored)
144
 */
145
public void publish(LogRecord record);
146
```
147

148
### Handler Management
149

150
Standard handler interface methods for lifecycle management.
151

152
```java { .api }
153
/**
154
 * No-op implementation (required by Handler interface)
155
 */
156
public void close();
157

158
/**
159
 * No-op implementation (required by Handler interface)
160
 */
161
public void flush();
162
```
163

164
### Logger Resolution
165

166
Internal method for resolving SLF4J loggers from JUL log records.
167

168
```java { .api }
169
/**
170
 * Return the Logger instance that will be used for logging
171
 * @param record a LogRecord
172
 * @return an SLF4J logger corresponding to the record parameter's logger name
173
 */
174
protected Logger getSLF4JLogger(LogRecord record);
175
```
176

177
### Location-Aware Logging
178

179
Internal method for handling location-aware logging when available.
180

181
```java { .api }
182
/**
183
 * Calls location-aware logger with proper level mapping
184
 * @param lal LocationAwareLogger instance
185
 * @param record LogRecord to process
186
 */
187
protected void callLocationAwareLogger(LocationAwareLogger lal, LogRecord record);
188

189
/**
190
 * Calls plain SLF4J logger with proper level mapping
191
 * @param slf4jLogger Logger instance
192
 * @param record LogRecord to process
193
 */
194
protected void callPlainSLF4JLogger(Logger slf4jLogger, LogRecord record);
195
```
196

197
## Level Mapping
198

199
The bridge maps JUL levels to SLF4J levels according to the following scheme:
200

201
| JUL Level | SLF4J Level |
202
|-----------|-------------|
203
| FINEST    | TRACE       |
204
| FINER     | DEBUG       |
205
| FINE      | DEBUG       |
206
| INFO      | INFO        |
207
| WARNING   | WARN        |
208
| SEVERE    | ERROR       |
209
210
## Types
211

212
```java { .api }
213
// Standard Java imports required
214
import java.util.logging.Handler;
215
import java.util.logging.LogRecord;
216
import java.util.logging.Level;
217
import org.slf4j.Logger;
218
import org.slf4j.spi.LocationAwareLogger;
219

220
/**
221
 * Bridge handler that extends java.util.logging.Handler
222
 * to redirect JUL log records to SLF4J
223
 */
224
public class SLF4JBridgeHandler extends Handler {
225
    // All methods listed above
226
}
227
```
228

229
## Usage Patterns
230

231
### Standard Installation Pattern
232

233
```java
234
// Remove existing handlers to avoid duplication
235
SLF4JBridgeHandler.removeHandlersForRootLogger();
236

237
// Install the bridge
238
SLF4JBridgeHandler.install();
239

240
// Verify installation
241
if (SLF4JBridgeHandler.isInstalled()) {
242
    // Bridge is active - all JUL logging now goes to SLF4J
243
}
244
```
245

246
### Configuration-Based Installation
247

248
```properties
249
# In logging.properties
250
handlers = org.slf4j.bridge.SLF4JBridgeHandler
251
```
252

253
### Programmatic Cleanup
254

255
```java
256
// Clean shutdown
257
if (SLF4JBridgeHandler.isInstalled()) {
258
    SLF4JBridgeHandler.uninstall();
259
}
260
```
261

262
## Error Handling
263

264
- **SecurityException**: May be thrown by `uninstall()` if security manager restricts logging permissions
265
- **Null Records**: `publish()` method silently ignores null LogRecord parameters
266
- **Missing Loggers**: Uses fallback logger name "unknown.jul.logger" for records without names
267

268
## Dependencies
269

270
This package requires:
271
- **slf4j-api**: Core SLF4J API for logger instances and interfaces
272
- **Java Util Logging**: Standard Java logging framework (java.util.logging)
273

274
The bridge is compatible with any SLF4J binding (logback, log4j2, etc.) and serves as the integration layer between JUL and SLF4J ecosystems.