0
# Apache Log4j JUL Adapter
1

2
The Apache Log4j JUL Adapter (log4j-jul) provides a bridge between Java Util Logging (JUL) and the Log4j logging framework. It allows applications and libraries using java.util.logging.Logger to seamlessly log through the Log4j API instead of the default Java logging implementation, offering better performance, more flexible configuration options, and advanced logging features.
3

4
## Package Information
5

6
- **Package Name**: log4j-jul
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `org.apache.logging.log4j:log4j-jul:2.25.1`
10
- **Installation**: Add dependency to your `pom.xml` or `build.gradle`
11

12
## Core Imports
13

14
```java
15
import org.apache.logging.log4j.jul.LogManager;
16
import org.apache.logging.log4j.jul.Log4jBridgeHandler;
17
import org.apache.logging.log4j.jul.LevelTranslator;
18
```
19

20
## Basic Usage
21

22
### LogManager Replacement (Recommended)
23

24
For optimal performance, replace JUL's LogManager with Log4j's implementation:
25

26
```java
27
// Set system property (typically in JVM args or system properties)
28
System.setProperty("java.util.logging.manager", "org.apache.logging.log4j.jul.LogManager");
29

30
// Use standard JUL API - it will be redirected to Log4j
31
java.util.logging.Logger logger = java.util.logging.Logger.getLogger("com.example");
32
logger.info("This message goes to Log4j");
33
```
34

35
### Bridge Handler Alternative
36

37
For environments where LogManager replacement isn't feasible:
38

39
```java
40
// Programmatic installation
41
import org.apache.logging.log4j.jul.Log4jBridgeHandler;
42

43
Log4jBridgeHandler.install(
44
    true,        // removeHandlersForRootLogger
45
    "_JUL",      // suffixToAppend (optional)
46
    true         // propagateLevels
47
);
48

49
// Or configure in logging.properties:
50
// handlers = org.apache.logging.log4j.jul.Log4jBridgeHandler
51
// org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels = true
52
```
53

54
## Architecture
55

56
The log4j-jul adapter provides two main integration approaches:
57

58
1. **LogManager Replacement**: Complete JUL-to-Log4j redirection for optimal performance
59
2. **Bridge Handler**: Handler-based approach for constrained environments
60

61
The adapter automatically selects the appropriate logger implementation based on available Log4j components (API-only vs. Core).
62

63
## Capabilities
64

65
### LogManager Integration
66

67
Complete replacement of JUL's LogManager with Log4j-backed implementation providing transparent redirection of all JUL logging calls.
68

69
```java { .api }
70
public class LogManager extends java.util.logging.LogManager {
71
    public LogManager();
72
    public Logger getLogger(String name);
73
    public Enumeration<String> getLoggerNames();
74
    public boolean addLogger(Logger logger);
75
}
76
```
77

78
[LogManager Integration](./logmanager-integration.md)
79

80
### Bridge Handler
81

82
JUL Handler that bridges log events to Log4j without requiring LogManager replacement, suitable for webapps and constrained environments.
83

84
```java { .api }
85
public class Log4jBridgeHandler extends java.util.logging.Handler {
86
    public Log4jBridgeHandler();
87
    public Log4jBridgeHandler(boolean debugOutput, String suffixToAppend, boolean propagateLevels);
88
    public static void install(boolean removeHandlersForRootLogger, String suffixToAppend, boolean propagateLevels);
89
    public void publish(LogRecord record);
90
}
91
```
92

93
[Bridge Handler](./bridge-handler.md)
94

95
### Level Translation
96

97
Bidirectional conversion between JUL and Log4j logging levels with support for custom levels and closest-match mapping.
98

99
```java { .api }
100
public final class LevelTranslator {
101
    public static final Level FINEST;
102
    public static final Level CONFIG;
103
    public static Level toLevel(java.util.logging.Level level);
104
    public static java.util.logging.Level toJavaLevel(Level level);
105
}
106
```
107

108
[Level Translation](./level-translation.md)
109

110
### Logger Adapters
111

112
Pluggable adapter system for different Log4j implementations (API-only vs. Core) with automatic selection and custom override capabilities.
113

114
```java { .api }
115
public abstract class AbstractLoggerAdapter extends org.apache.logging.log4j.spi.AbstractLoggerAdapter<Logger> {
116
    protected LoggerContext getContext();
117
}
118
```
119

120
[Logger Adapters](./logger-adapters.md)
121

122
## Configuration
123

124
### System Properties
125

126
- `java.util.logging.manager` - Set to `org.apache.logging.log4j.jul.LogManager` for LogManager approach
127
- `log4j.jul.LoggerAdapter` - Override default logger adapter selection
128
- `log4j.jul.levelConverter` - Use custom level converter implementation
129

130
### JUL Configuration Properties
131

132
For Bridge Handler approach in `logging.properties`:
133

134
- `org.apache.logging.log4j.jul.Log4jBridgeHandler.suffixToAppend` - Suffix for JUL logger names
135
- `org.apache.logging.log4j.jul.Log4jBridgeHandler.propagateLevels` - Auto-propagate Log4j levels to JUL
136
- `org.apache.logging.log4j.jul.Log4jBridgeHandler.sysoutDebug` - Enable debug output
137

138
## Dependencies
139

140
- **Required**: log4j-api
141
- **Optional**: log4j-core (enables enhanced functionality and CoreLogger features)
142
- **Compatible**: All Java versions supported by Log4j 2.x
143

144
## Types
145

146
```java { .api }
147
public interface LevelConverter {
148
    Level toLevel(java.util.logging.Level javaLevel);
149
    java.util.logging.Level toJavaLevel(Level level);
150
}
151

152
public final class Constants {
153
    public static final String LOGGER_ADAPTOR_PROPERTY = "log4j.jul.LoggerAdapter";
154
    public static final String LEVEL_CONVERTER_PROPERTY = "log4j.jul.levelConverter";
155
}
156
```