0
# SLF4J Reload4j Provider
1

2
A SLF4J logging provider that integrates the Simple Logging Facade for Java (SLF4J) with the reload4j logging framework. This provider enables applications using SLF4J to output logs through reload4j, providing a bridge from the legacy log4j 1.2 dependency to the actively maintained reload4j fork.
3

4
## Package Information
5

6
- **Package Name**: slf4j-log4j12 (relocated to slf4j-reload4j)
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>org.slf4j</groupId><artifactId>slf4j-log4j12</artifactId><version>2.0.17</version></dependency>`
10
- **Relocated to**: `<dependency><groupId>org.slf4j</groupId><artifactId>slf4j-reload4j</artifactId><version>2.0.17</version></dependency>`
11

12
## Core Imports
13

14
```java
15
// Standard SLF4J imports - no direct imports of slf4j-reload4j classes needed
16
import org.slf4j.Logger;
17
import org.slf4j.LoggerFactory;
18
import org.slf4j.MDC;
19
```
20

21
## Basic Usage
22

23
```java
24
import org.slf4j.Logger;
25
import org.slf4j.LoggerFactory;
26
import org.slf4j.MDC;
27

28
public class ExampleApp {
29
    private static final Logger logger = LoggerFactory.getLogger(ExampleApp.class);
30
    
31
    public void processUser(String userId, String action) {
32
        // Add context information to MDC
33
        MDC.put("userId", userId);
34
        MDC.put("action", action);
35
        
36
        try {
37
            logger.info("Processing user action");
38
            
39
            // Business logic here
40
            if (action.equals("login")) {
41
                logger.debug("User login successful");
42
            } else if (action.equals("logout")) {
43
                logger.info("User logged out");
44
            }
45
            
46
        } catch (Exception e) {
47
            logger.error("Error processing user action", e);
48
        } finally {
49
            // Clean up MDC context
50
            MDC.clear();
51
        }
52
    }
53
}
54
```
55

56
## Architecture
57

58
The SLF4J Reload4j Provider follows the SLF4J service provider pattern:
59

60
- **Service Provider**: `Reload4jServiceProvider` implements `SLF4JServiceProvider` and is auto-discovered via Java ServiceLoader
61
- **Logger Factory**: `Reload4jLoggerFactory` creates and caches logger instances, delegating to reload4j's LogManager
62
- **Logger Adapter**: `Reload4jLoggerAdapter` wraps reload4j Logger instances and implements SLF4J Logger interface
63
- **MDC Adapter**: `Reload4jMDCAdapter` bridges SLF4J MDC operations to reload4j's MDC implementation
64

65
The provider automatically initializes when SLF4J is used, requiring no manual configuration beyond adding the dependency.
66

67
## Capabilities
68

69
### Service Provider Implementation
70

71
Core SLF4J service provider that enables automatic discovery and initialization of the reload4j logging backend.
72

73
```java { .api }
74
/**
75
 * Main SLF4J service provider for reload4j integration
76
 */
77
public class Reload4jServiceProvider implements SLF4JServiceProvider {
78
    /** SLF4J API version compatibility marker */
79
    public static String REQUESTED_API_VERSION = "2.0.99";
80
    
81
    /** Default constructor that initializes marker factory and MDC adapter */
82
    public Reload4jServiceProvider();
83
    
84
    /** Initialize the logger factory */
85
    public void initialize();
86
    
87
    /** Get the logger factory instance */
88
    public ILoggerFactory getLoggerFactory();
89
    
90
    /** Get the marker factory instance */
91
    public IMarkerFactory getMarkerFactory();
92
    
93
    /** Get the MDC adapter instance */
94
    public MDCAdapter getMDCAdapter();
95
    
96
    /** Get the requested API version */
97
    public String getRequestedApiVersion();
98
}
99
```
100

101
### Logger Factory
102

103
Factory implementation that creates and manages logger instances, delegating to reload4j's LogManager.
104

105
```java { .api }
106
/**
107
 * Logger factory that creates Reload4jLoggerAdapter instances
108
 */
109
public class Reload4jLoggerFactory implements ILoggerFactory {
110
    /** Default constructor that initializes logger cache and reload4j */
111
    public Reload4jLoggerFactory();
112
    
113
    /**
114
     * Get or create a logger for the specified name
115
     * @param name Logger name (class name or custom identifier)
116
     * @return Logger instance for the given name
117
     */
118
    public Logger getLogger(String name);
119
}
120
```
121

122
### Logger Adapter
123

124
SLF4J Logger implementation that wraps reload4j Logger instances and provides full SLF4J API compatibility.
125

126
```java { .api }
127
/**
128
 * SLF4J Logger implementation that delegates to reload4j Logger
129
 */
130
public final class Reload4jLoggerAdapter extends LegacyAbstractLogger 
131
    implements LocationAwareLogger, LoggingEventAware, Serializable {
132
    
133
    /** Check if TRACE level is enabled */
134
    public boolean isTraceEnabled();
135
    
136
    /** Check if DEBUG level is enabled */
137
    public boolean isDebugEnabled();
138
    
139
    /** Check if INFO level is enabled */
140
    public boolean isInfoEnabled();
141
    
142
    /** Check if WARN level is enabled */
143
    public boolean isWarnEnabled();
144
    
145
    /** Check if ERROR level is enabled */
146
    public boolean isErrorEnabled();
147
    
148
    /**
149
     * Location-aware logging method
150
     * @param marker Optional marker for categorization
151
     * @param callerFQCN Fully qualified class name of the caller
152
     * @param level Logging level as integer
153
     * @param msg Message to log
154
     * @param arguments Message formatting arguments
155
     * @param t Optional throwable for exception logging
156
     */
157
    public void log(Marker marker, String callerFQCN, int level, 
158
                   String msg, Object[] arguments, Throwable t);
159
    
160
    /**
161
     * Fluent API logging method for LoggingEvent
162
     * @param event LoggingEvent containing all log information
163
     */
164
    public void log(LoggingEvent event);
165
}
166
```
167

168
### MDC Adapter
169

170
MDC (Mapped Diagnostic Context) adapter that bridges SLF4J MDC operations to reload4j's MDC implementation.
171

172
```java { .api }
173
/**
174
 * MDC adapter that delegates to reload4j MDC implementation
175
 */
176
public class Reload4jMDCAdapter implements MDCAdapter {
177
    /** Clear all MDC values for current thread */
178
    public void clear();
179
    
180
    /**
181
     * Get MDC value for specified key
182
     * @param key The key to retrieve
183
     * @return String value or null if not found
184
     */
185
    public String get(String key);
186
    
187
    /**
188
     * Put key-value pair in MDC for current thread
189
     * @param key The key (cannot be null)
190
     * @param val The value (cannot be null for log4j compatibility)
191
     * @throws IllegalArgumentException if key or val is null
192
     */
193
    public void put(String key, String val);
194
    
195
    /**
196
     * Remove key from MDC for current thread
197
     * @param key The key to remove
198
     */
199
    public void remove(String key);
200
    
201
    /**
202
     * Get copy of current MDC context map
203
     * @return Map copy of current context, or null if no context
204
     */
205
    public Map getCopyOfContextMap();
206
    
207
    /**
208
     * Set MDC context map for current thread
209
     * @param contextMap Context map to set (null clears context)
210
     */
211
    public void setContextMap(Map<String, String> contextMap);
212
    
213
    /**
214
     * Push value to deque by key (SLF4J 2.0 feature)
215
     * @param key The key for the deque
216
     * @param value The value to push
217
     */
218
    public void pushByKey(String key, String value);
219
    
220
    /**
221
     * Pop value from deque by key (SLF4J 2.0 feature)  
222
     * @param key The key for the deque
223
     * @return The popped value or null if deque is empty
224
     */
225
    public String popByKey(String key);
226
    
227
    /**
228
     * Get copy of deque by key (SLF4J 2.0 feature)
229
     * @param key The key for the deque
230
     * @return Copy of the deque or null if not found
231
     */
232
    public Deque<String> getCopyOfDequeByKey(String key);
233
    
234
    /**
235
     * Clear deque by key (SLF4J 2.0 feature)
236
     * @param key The key for the deque to clear
237
     */
238
    public void clearDequeByKey(String key);
239
}
240
```
241

242
## Service Provider Configuration
243

244
The provider is automatically discovered by SLF4J through the Java ServiceLoader mechanism:
245

246
**Configuration File**: `META-INF/services/org.slf4j.spi.SLF4JServiceProvider`  
247
**Content**: `org.slf4j.reload4j.Reload4jServiceProvider`
248

249
No manual configuration is required - simply adding the dependency enables reload4j logging.
250

251
## Dependencies
252

253
- **SLF4J API**: Provides the core SLF4J interfaces (`Logger`, `LoggerFactory`, `MDC`, etc.)
254
- **Reload4j**: The actual logging implementation framework (actively maintained log4j 1.2 fork)
255

256
## Key Features
257

258
- **Automatic Discovery**: Uses Java ServiceLoader for zero-configuration setup
259
- **Full SLF4J 2.0 Compatibility**: Supports all SLF4J features including fluent API and advanced MDC operations
260
- **Thread Safety**: All operations are thread-safe with proper synchronization
261
- **Performance Optimized**: Efficient logger caching and delegation
262
- **MDC Support**: Complete MDC implementation with both traditional and deque-based operations
263
- **Marker Support**: Full marker support via SLF4J's BasicMarkerFactory
264
- **Location Awareness**: Provides accurate source location information for debugging
265
- **Error Prevention**: Built-in delegation loop detection prevents StackOverflowError
266

267
## Error Handling
268

269
- **Version Compatibility Check**: Validates reload4j version 1.2.12+ at initialization
270
- **Delegation Loop Prevention**: Static checks prevent conflicts with log4j-over-slf4j
271
- **IllegalStateException**: Thrown when delegation loops are detected
272
- **IllegalArgumentException**: Thrown for invalid MDC operations (null keys/values)
273
- **NoSuchFieldError**: Handled gracefully with informative error messages for version mismatches
274

275
## Maven Relocation
276

277
As of version 2.0.17, the `slf4j-log4j12` artifact has been relocated to `slf4j-reload4j`. When you depend on `org.slf4j:slf4j-log4j12:2.0.17`, Maven automatically resolves it to `org.slf4j:slf4j-reload4j:2.0.17`. This provides backward compatibility while transitioning to the actively maintained reload4j library.
278

279
To use the provider directly without relocation, depend on:
280

281
```xml
282
<dependency>
283
    <groupId>org.slf4j</groupId>
284
    <artifactId>slf4j-reload4j</artifactId>
285
    <version>2.0.17</version>
286
</dependency>
287
```