0
# Log4j 1.x Compatibility API
1

2
## Overview
3

4
The Apache Log4j 1.x Compatibility API provides a seamless bridge between legacy Log4j 1.x applications and the modern Log4j 2.x infrastructure. This compatibility layer allows existing applications using Log4j 1.x syntax to work without code changes while benefiting from Log4j 2.x's improved performance, security, and features.
5

6
## Package Information
7

8
- **Package**: `org.apache.logging.log4j:log4j-1.2-api`
9
- **Version**: `2.25.1`
10
- **Type**: Library
11
- **Language**: Java
12
- **License**: Apache-2.0
13

14
## Installation
15

16
### Maven
17
```xml
18
<dependency>
19
    <groupId>org.apache.logging.log4j</groupId>
20
    <artifactId>log4j-1.2-api</artifactId>
21
    <version>2.25.1</version>
22
</dependency>
23
```
24

25
### Gradle
26
```gradle
27
implementation 'org.apache.logging.log4j:log4j-1.2-api:2.25.1'
28
```
29

30
## Core Imports
31

32
```java { .api }
33
// Primary logging classes
34
import org.apache.log4j.Logger;
35
import org.apache.log4j.LogManager;
36
import org.apache.log4j.Level;
37

38
// Configuration
39
import org.apache.log4j.PropertyConfigurator;
40
import org.apache.log4j.xml.DOMConfigurator;
41

42
// Appenders and layouts
43
import org.apache.log4j.ConsoleAppender;
44
import org.apache.log4j.FileAppender;
45
import org.apache.log4j.PatternLayout;
46

47
// Thread context
48
import org.apache.log4j.MDC;
49
import org.apache.log4j.NDC;
50
```
51

52
## Basic Usage
53

54
### Simple Logging
55
```java
56
import org.apache.log4j.Logger;
57

58
public class MyClass {
59
    private static final Logger logger = Logger.getLogger(MyClass.class);
60
    
61
    public void doSomething() {
62
        logger.info("Starting operation");
63
        try {
64
            // Your code here
65
            logger.debug("Operation completed successfully");
66
        } catch (Exception e) {
67
            logger.error("Operation failed", e);
68
        }
69
    }
70
}
71
```
72

73
### Configuration
74
```java
75
import org.apache.log4j.PropertyConfigurator;
76
import org.apache.log4j.xml.DOMConfigurator;
77

78
// Configure from properties file
79
PropertyConfigurator.configure("log4j.properties");
80

81
// Configure from XML file
82
DOMConfigurator.configure("log4j.xml");
83
```
84

85
### Thread Context
86
```java
87
import org.apache.log4j.MDC;
88
import org.apache.log4j.NDC;
89

90
// Mapped Diagnostic Context
91
MDC.put("userId", "john123");
92
MDC.put("sessionId", "session456");
93

94
// Nested Diagnostic Context
95
NDC.push("WebService");
96
NDC.push("UserOperation");
97
```
98

99
## Architecture
100

101
The Log4j 1.x Compatibility API consists of several key architectural components:
102

103
- **Logging Core**: Primary logging classes that maintain Log4j 1.x interface while delegating to Log4j 2.x
104
- **Configuration**: Multiple configuration approaches supporting both properties and XML formats
105
- **Appenders**: Output destinations with full Log4j 1.x compatibility
106
- **Layouts**: Message formatting with pattern-based and simple layouts
107
- **Thread Context**: Thread-local diagnostic information storage
108
- **SPI Extension Points**: Interfaces for custom extensions and plugins
109

110
## Capabilities
111

112
### [Core Logging](./logging.md)
113
Primary logging interfaces including Logger, LogManager, and Level classes. Provides the main entry points for application logging with full Log4j 1.x compatibility.
114

115
```java { .api }
116
Logger logger = Logger.getLogger(MyClass.class);
117
logger.info("Application started");
118
logger.error("Error occurred", exception);
119
```
120

121
### [Configuration Management](./configuration.md) 
122
Configuration loading and management through PropertyConfigurator, DOMConfigurator, and programmatic configuration. Supports both traditional Log4j 1.x configuration formats.
123

124
```java { .api }
125
PropertyConfigurator.configure("log4j.properties");
126
DOMConfigurator.configure("log4j.xml");
127
BasicConfigurator.configure();
128
```
129

130
### [Appenders and Output](./appenders.md)
131
Output destinations including ConsoleAppender, FileAppender, RollingFileAppender, and custom appenders. Manages where log messages are written with full configurability.
132

133
```java { .api }
134
ConsoleAppender appender = new ConsoleAppender(new PatternLayout("%d %p %c - %m%n"));
135
logger.addAppender(appender);
136
```
137

138
### [Layouts and Formatting](./layouts.md)
139
Message formatting through PatternLayout, SimpleLayout, and custom layouts. Controls how log messages are formatted for output.
140

141
```java { .api }
142
PatternLayout layout = new PatternLayout("%d{ISO8601} [%t] %-5p %c{1} - %m%n");
143
SimpleLayout simpleLayout = new SimpleLayout();
144
```
145

146
### [Thread Context](./context.md)  
147
Thread-local diagnostic context through MDC (Mapped Diagnostic Context) and NDC (Nested Diagnostic Context). Enables context-aware logging across application threads.
148

149
```java { .api }
150
MDC.put("userId", "user123");
151
MDC.put("requestId", "req456");
152
NDC.push("operation");
153
```
154

155
### [Configuration Builders](./builders.md)
156
Programmatic configuration builders that integrate with Log4j 2.x configuration system while maintaining Log4j 1.x compatibility.
157

158
```java { .api }
159
AppenderBuilder<?> builder = new ConsoleAppenderBuilder<>();
160
Filter filter = new LevelRangeFilterBuilder().build();
161
```
162

163
### [SPI and Extension Points](./spi.md)
164
Service Provider Interface classes including LoggerRepository, ErrorHandler, Filter, and other extension points for custom functionality.
165

166
```java { .api }
167
public interface ErrorHandler {
168
    void error(String message, Exception ex, int errorCode);
169
    void setAppender(Appender appender);
170
}
171
```