0
# Configuration Builders
1

2
Configuration builders provide programmatic configuration capabilities that integrate with Log4j 2.x configuration system while maintaining Log4j 1.x compatibility. These builders enable type-safe, fluent configuration APIs.
3

4
## Base Builder Interfaces
5

6
### Builder Interface
7

8
```java { .api }
9
public interface Builder<T> {
10
    // Build the configured object
11
    T build();
12
}
13
```
14

15
**Returns:**
16
- `T` the built configuration object
17

18
### Parser Interface
19

20
```java { .api }
21
public interface Parser<T extends Builder<? extends Object>> {
22
    // Parse configuration and return builder
23
    T parse(Element element);
24
}
25
```
26

27
**Parameters:**
28
- `element` - DOM Element containing configuration
29

30
**Returns:**
31
- `T` builder configured from the element
32

33
## Appender Builders
34

35
### AppenderBuilder Interface
36

37
```java { .api }
38
public interface AppenderBuilder<T extends Appender> extends Builder<T> {
39
    // Common appender configuration
40
    AppenderBuilder<T> setName(String name);
41
    AppenderBuilder<T> setLayout(Layout layout);
42
    AppenderBuilder<T> setFilter(Filter filter);
43
    AppenderBuilder<T> setErrorHandler(ErrorHandler errorHandler);
44
    
45
    // Build the appender
46
    @Override
47
    T build();
48
}
49
```
50

51
**Parameters:**
52
- `name` - String name for the appender
53
- `layout` - Layout for message formatting
54
- `filter` - Filter for message filtering
55
- `errorHandler` - ErrorHandler for error management
56

57
**Returns:**
58
- `AppenderBuilder<T>` for method chaining
59
- `T` the built appender
60

61
### ConsoleAppenderBuilder
62

63
```java { .api }
64
public class ConsoleAppenderBuilder implements AppenderBuilder<ConsoleAppender>, Parser<ConsoleAppenderBuilder> {
65
    // Builder methods
66
    public ConsoleAppenderBuilder setName(String name);
67
    public ConsoleAppenderBuilder setLayout(Layout layout);
68
    public ConsoleAppenderBuilder setFilter(Filter filter);
69
    public ConsoleAppenderBuilder setErrorHandler(ErrorHandler errorHandler);
70
    
71
    // Console-specific configuration
72
    public ConsoleAppenderBuilder setTarget(String target);
73
    public ConsoleAppenderBuilder setFollow(boolean follow);
74
    
75
    // Build and parse
76
    @Override
77
    public ConsoleAppender build();
78
    
79
    @Override
80
    public ConsoleAppenderBuilder parse(Element element);
81
}
82
```
83

84
**Parameters:**
85
- `name` - String appender name
86
- `layout` - Layout for formatting
87
- `filter` - Filter for message filtering
88
- `errorHandler` - ErrorHandler for errors
89
- `target` - String target (SYSTEM_OUT or SYSTEM_ERR)
90
- `follow` - Boolean follow setting
91
- `element` - DOM Element for parsing
92

93
**Returns:**
94
- `ConsoleAppenderBuilder` for chaining
95
- `ConsoleAppender` built instance
96

97
### FileAppenderBuilder
98

99
```java { .api }
100
public class FileAppenderBuilder implements AppenderBuilder<FileAppender>, Parser<FileAppenderBuilder> {
101
    // Builder methods
102
    public FileAppenderBuilder setName(String name);
103
    public FileAppenderBuilder setLayout(Layout layout);
104
    public FileAppenderBuilder setFilter(Filter filter);
105
    public FileAppenderBuilder setErrorHandler(ErrorHandler errorHandler);
106
    
107
    // File-specific configuration
108
    public FileAppenderBuilder setFileName(String fileName);
109
    public FileAppenderBuilder setAppend(boolean append);
110
    public FileAppenderBuilder setBufferedIO(boolean bufferedIO);
111
    public FileAppenderBuilder setBufferSize(int bufferSize);
112
    
113
    // Build and parse
114
    @Override
115
    public FileAppender build();
116
    
117
    @Override
118
    public FileAppenderBuilder parse(Element element);
119
}
120
```
121

122
**Parameters:**
123
- `name` - String appender name
124
- `layout` - Layout for formatting
125
- `filter` - Filter for filtering
126
- `errorHandler` - ErrorHandler for errors
127
- `fileName` - String path to log file
128
- `append` - Boolean append flag
129
- `bufferedIO` - Boolean buffering flag
130
- `bufferSize` - Integer buffer size
131

132
**Returns:**
133
- `FileAppenderBuilder` for chaining
134
- `FileAppender` built instance
135

136
### RollingFileAppenderBuilder
137

138
```java { .api }
139
public class RollingFileAppenderBuilder implements AppenderBuilder<RollingFileAppender>, Parser<RollingFileAppenderBuilder> {
140
    // Inherited builder methods
141
    public RollingFileAppenderBuilder setName(String name);
142
    public RollingFileAppenderBuilder setLayout(Layout layout);
143
    public RollingFileAppenderBuilder setFilter(Filter filter);
144
    public RollingFileAppenderBuilder setErrorHandler(ErrorHandler errorHandler);
145
    public RollingFileAppenderBuilder setFileName(String fileName);
146
    public RollingFileAppenderBuilder setAppend(boolean append);
147
    
148
    // Rolling-specific configuration
149
    public RollingFileAppenderBuilder setMaxFileSize(String maxFileSize);
150
    public RollingFileAppenderBuilder setMaxBackupIndex(int maxBackupIndex);
151
    
152
    // Build and parse
153
    @Override
154
    public RollingFileAppender build();
155
    
156
    @Override
157
    public RollingFileAppenderBuilder parse(Element element);
158
}
159
```
160

161
**Parameters:**
162
- `maxFileSize` - String maximum file size (e.g., "10MB")
163
- `maxBackupIndex` - Integer maximum backup files
164

165
**Returns:**
166
- `RollingFileAppenderBuilder` for chaining
167
- `RollingFileAppender` built instance
168

169
## Layout Builders
170

171
### LayoutBuilder Interface
172

173
```java { .api }
174
public interface LayoutBuilder<T extends Layout> extends Builder<T> {
175
    // Build the layout
176
    @Override
177
    T build();
178
}
179
```
180

181
**Returns:**
182
- `T` the built layout
183

184
### PatternLayoutBuilder
185

186
```java { .api }
187
public class PatternLayoutBuilder implements LayoutBuilder<PatternLayout>, Parser<PatternLayoutBuilder> {
188
    // Configuration
189
    public PatternLayoutBuilder setConversionPattern(String pattern);
190
    
191
    // Build and parse
192
    @Override
193
    public PatternLayout build();
194
    
195
    @Override
196
    public PatternLayoutBuilder parse(Element element);
197
}
198
```
199

200
**Parameters:**
201
- `pattern` - String conversion pattern
202
- `element` - DOM Element for parsing
203

204
**Returns:**
205
- `PatternLayoutBuilder` for chaining
206
- `PatternLayout` built instance
207

208
### SimpleLayoutBuilder
209

210
```java { .api }
211
public class SimpleLayoutBuilder implements LayoutBuilder<SimpleLayout>, Parser<SimpleLayoutBuilder> {
212
    // Build and parse
213
    @Override
214
    public SimpleLayout build();
215
    
216
    @Override
217
    public SimpleLayoutBuilder parse(Element element);
218
}
219
```
220

221
**Parameters:**
222
- `element` - DOM Element for parsing
223

224
**Returns:**
225
- `SimpleLayoutBuilder` for chaining
226
- `SimpleLayout` built instance
227

228
## Filter Builders
229

230
### FilterBuilder Interface
231

232
```java { .api }
233
public interface FilterBuilder extends Builder<Filter>, Parser<FilterBuilder> {
234
    // Build the filter
235
    @Override
236
    Filter build();
237
    
238
    // Parse configuration
239
    @Override
240
    FilterBuilder parse(Element element);
241
}
242
```
243

244
**Parameters:**
245
- `element` - DOM Element for parsing
246

247
**Returns:**
248
- `Filter` built instance
249
- `FilterBuilder` configured from element
250

251
### LevelRangeFilterBuilder
252

253
```java { .api }
254
public class LevelRangeFilterBuilder implements FilterBuilder {
255
    // Configuration
256
    public LevelRangeFilterBuilder setLevelMin(Level levelMin);
257
    public LevelRangeFilterBuilder setLevelMax(Level levelMax);
258
    public LevelRangeFilterBuilder setAcceptOnMatch(boolean acceptOnMatch);
259
    
260
    // Build and parse
261
    @Override
262
    public Filter build();
263
    
264
    @Override
265
    public LevelRangeFilterBuilder parse(Element element);
266
}
267
```
268

269
**Parameters:**
270
- `levelMin` - Level minimum level for range
271
- `levelMax` - Level maximum level for range
272
- `acceptOnMatch` - Boolean accept or deny on match
273
- `element` - DOM Element for parsing
274

275
**Returns:**
276
- `LevelRangeFilterBuilder` for chaining
277
- `Filter` built instance
278

279
### LevelMatchFilterBuilder
280

281
```java { .api }
282
public class LevelMatchFilterBuilder implements FilterBuilder {
283
    // Configuration
284
    public LevelMatchFilterBuilder setLevel(Level level);
285
    public LevelMatchFilterBuilder setAcceptOnMatch(boolean acceptOnMatch);
286
    
287
    // Build and parse
288
    @Override
289
    public Filter build();
290
    
291
    @Override
292
    public LevelMatchFilterBuilder parse(Element element);
293
}
294
```
295

296
**Parameters:**
297
- `level` - Level to match against
298
- `acceptOnMatch` - Boolean accept or deny on match
299
- `element` - DOM Element for parsing
300

301
**Returns:**
302
- `LevelMatchFilterBuilder` for chaining
303
- `Filter` built instance
304

305
## Configuration Builder
306

307
### ConfigurationBuilder
308

309
```java { .api }
310
public class ConfigurationBuilder implements Builder<LoggerRepository> {
311
    // Logger configuration
312
    public ConfigurationBuilder addLogger(String name, Level level, boolean additivity);
313
    public ConfigurationBuilder addLogger(String name, Level level, boolean additivity, Appender... appenders);
314
    public ConfigurationBuilder setRootLogger(Level level, Appender... appenders);
315
    
316
    // Appender management
317
    public ConfigurationBuilder addAppender(Appender appender);
318
    public ConfigurationBuilder removeAppender(String name);
319
    
320
    // Repository configuration
321
    public ConfigurationBuilder setThreshold(Level threshold);
322
    
323
    // Build configuration
324
    @Override
325
    public LoggerRepository build();
326
    
327
    // Apply configuration
328
    public void configure();
329
}
330
```
331

332
**Parameters:**
333
- `name` - String logger name
334
- `level` - Level logging level
335
- `additivity` - Boolean additivity flag
336
- `appenders` - Appender array of appenders
337
- `appender` - Appender to add or remove
338
- `threshold` - Level global threshold
339

340
**Returns:**
341
- `ConfigurationBuilder` for chaining
342
- `LoggerRepository` built repository
343

344
## Usage Examples
345

346
### Console Appender Builder
347
```java
348
import org.apache.log4j.builders.appender.ConsoleAppenderBuilder;
349
import org.apache.log4j.builders.layout.PatternLayoutBuilder;
350
import org.apache.log4j.*;
351

352
public class ConsoleAppenderBuilderExample {
353
    public void createConsoleAppender() {
354
        // Build pattern layout
355
        PatternLayout layout = new PatternLayoutBuilder()
356
            .setConversionPattern("%d{HH:mm:ss} %-5p %c{1} - %m%n")
357
            .build();
358
        
359
        // Build console appender
360
        ConsoleAppender appender = new ConsoleAppenderBuilder()
361
            .setName("console")
362
            .setLayout(layout)
363
            .setTarget(ConsoleAppender.SYSTEM_OUT)
364
            .setFollow(true)
365
            .build();
366
        
367
        // Add to logger
368
        Logger logger = Logger.getLogger("builder-example");
369
        logger.addAppender(appender);
370
        logger.setLevel(Level.INFO);
371
        
372
        logger.info("Console appender created with builder");
373
    }
374
}
375
```
376

377
### File Appender Builder
378
```java
379
import org.apache.log4j.builders.appender.FileAppenderBuilder;
380
import org.apache.log4j.builders.layout.PatternLayoutBuilder;
381
import org.apache.log4j.*;
382

383
public class FileAppenderBuilderExample {
384
    public void createFileAppender() {
385
        // Build layout
386
        PatternLayout layout = new PatternLayoutBuilder()
387
            .setConversionPattern("%d{ISO8601} [%t] %-5p %c - %m%n")
388
            .build();
389
        
390
        // Build file appender
391
        FileAppender appender = new FileAppenderBuilder()
392
            .setName("file")
393
            .setLayout(layout)
394
            .setFileName("application.log")
395
            .setAppend(true)
396
            .setBufferedIO(true)
397
            .setBufferSize(8192)
398
            .build();
399
        
400
        // Configure logger
401
        Logger logger = Logger.getLogger("file-example");
402
        logger.addAppender(appender);
403
        logger.setLevel(Level.DEBUG);
404
        
405
        logger.debug("File appender created with builder");
406
    }
407
}
408
```
409

410
### Rolling File Appender Builder
411
```java
412
import org.apache.log4j.builders.appender.RollingFileAppenderBuilder;
413
import org.apache.log4j.builders.layout.PatternLayoutBuilder;
414
import org.apache.log4j.*;
415

416
public class RollingFileBuilderExample {
417
    public void createRollingFileAppender() {
418
        // Build layout
419
        PatternLayout layout = new PatternLayoutBuilder()
420
            .setConversionPattern("%d %p %c - %m%n")
421
            .build();
422
        
423
        // Build rolling file appender
424
        RollingFileAppender appender = new RollingFileAppenderBuilder()
425
            .setName("rolling")
426
            .setLayout(layout)
427
            .setFileName("app.log")
428
            .setAppend(true)
429
            .setMaxFileSize("10MB")
430
            .setMaxBackupIndex(5)
431
            .build();
432
        
433
        // Configure logger
434
        Logger logger = Logger.getLogger("rolling-example");
435
        logger.addAppender(appender);
436
        logger.setLevel(Level.INFO);
437
        
438
        logger.info("Rolling file appender created");
439
    }
440
}
441
```
442

443
### Filter Builder Usage
444
```java
445
import org.apache.log4j.builders.filter.*;
446
import org.apache.log4j.builders.appender.ConsoleAppenderBuilder;
447
import org.apache.log4j.builders.layout.PatternLayoutBuilder;
448
import org.apache.log4j.*;
449

450
public class FilterBuilderExample {
451
    public void createFilteredAppender() {
452
        // Build level range filter (INFO to ERROR)
453
        Filter levelRangeFilter = new LevelRangeFilterBuilder()
454
            .setLevelMin(Level.INFO)
455
            .setLevelMax(Level.ERROR)
456
            .setAcceptOnMatch(true)
457
            .build();
458
        
459
        // Build level match filter (only WARN)
460
        Filter levelMatchFilter = new LevelMatchFilterBuilder()
461
            .setLevel(Level.WARN)
462
            .setAcceptOnMatch(true)
463
            .build();
464
        
465
        // Build layout
466
        PatternLayout layout = new PatternLayoutBuilder()
467
            .setConversionPattern("%-5p %c - %m%n")
468
            .build();
469
        
470
        // Build appender with filter
471
        ConsoleAppender appender = new ConsoleAppenderBuilder()
472
            .setName("filtered-console")
473
            .setLayout(layout)
474
            .setFilter(levelRangeFilter)
475
            .build();
476
        
477
        // Configure logger
478
        Logger logger = Logger.getLogger("filtered-example");
479
        logger.addAppender(appender);
480
        logger.setLevel(Level.DEBUG);
481
        
482
        // Test filtering
483
        logger.debug("Debug message - should be filtered out");
484
        logger.info("Info message - should appear");
485
        logger.warn("Warn message - should appear");
486
        logger.error("Error message - should appear");
487
    }
488
}
489
```
490

491
### Complete Configuration Builder
492
```java
493
import org.apache.log4j.builders.*;
494
import org.apache.log4j.builders.appender.*;
495
import org.apache.log4j.builders.layout.*;
496
import org.apache.log4j.*;
497

498
public class ConfigurationBuilderExample {
499
    public void buildCompleteConfiguration() {
500
        // Build console layout
501
        PatternLayout consoleLayout = new PatternLayoutBuilder()
502
            .setConversionPattern("%-5p %c{1} - %m%n")
503
            .build();
504
        
505
        // Build file layout
506
        PatternLayout fileLayout = new PatternLayoutBuilder()
507
            .setConversionPattern("%d{ISO8601} [%t] %-5p %c - %m%n")
508
            .build();
509
        
510
        // Build console appender
511
        ConsoleAppender consoleAppender = new ConsoleAppenderBuilder()
512
            .setName("console")
513
            .setLayout(consoleLayout)
514
            .setTarget(ConsoleAppender.SYSTEM_OUT)
515
            .build();
516
        
517
        // Build rolling file appender
518
        RollingFileAppender fileAppender = new RollingFileAppenderBuilder()
519
            .setName("file")
520
            .setLayout(fileLayout)
521
            .setFileName("app.log")
522
            .setMaxFileSize("10MB")
523
            .setMaxBackupIndex(3)
524
            .build();
525
        
526
        // Build complete configuration
527
        LoggerRepository repository = new ConfigurationBuilder()
528
            .addAppender(consoleAppender)
529
            .addAppender(fileAppender)
530
            .setRootLogger(Level.INFO, consoleAppender, fileAppender)
531
            .addLogger("com.myapp.dao", Level.DEBUG, false, fileAppender)
532
            .addLogger("org.springframework", Level.WARN, true)
533
            .setThreshold(Level.DEBUG)
534
            .build();
535
        
536
        // Apply configuration
537
        new ConfigurationBuilder()
538
            .addAppender(consoleAppender)
539
            .addAppender(fileAppender)
540
            .setRootLogger(Level.INFO, consoleAppender, fileAppender)
541
            .configure();
542
    }
543
}
544
```
545

546
### XML Configuration Parsing
547
```java
548
import org.apache.log4j.builders.appender.ConsoleAppenderBuilder;
549
import org.apache.log4j.builders.layout.PatternLayoutBuilder;
550
import org.w3c.dom.Element;
551
import javax.xml.parsers.DocumentBuilder;
552
import javax.xml.parsers.DocumentBuilderFactory;
553

554
public class XMLParsingExample {
555
    public void parseXMLConfiguration() throws Exception {
556
        // Example XML element parsing
557
        String xmlConfig = 
558
            "<appender name='console' class='org.apache.log4j.ConsoleAppender'>" +
559
            "  <param name='Target' value='System.out'/>" +
560
            "  <layout class='org.apache.log4j.PatternLayout'>" +
561
            "    <param name='ConversionPattern' value='%-5p %c - %m%n'/>" +
562
            "  </layout>" +
563
            "</appender>";
564
        
565
        // Parse XML (simplified example)
566
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
567
        DocumentBuilder builder = factory.newDocumentBuilder();
568
        
569
        // In real implementation, you would parse the actual XML
570
        // Element appenderElement = ...;
571
        
572
        // Parse with builders
573
        ConsoleAppenderBuilder appenderBuilder = new ConsoleAppenderBuilder();
574
        // ConsoleAppender appender = appenderBuilder.parse(appenderElement).build();
575
        
576
        // For demonstration, build manually
577
        PatternLayout layout = new PatternLayoutBuilder()
578
            .setConversionPattern("%-5p %c - %m%n")
579
            .build();
580
        
581
        ConsoleAppender appender = new ConsoleAppenderBuilder()
582
            .setName("console")
583
            .setTarget("System.out")
584
            .setLayout(layout)
585
            .build();
586
        
587
        Logger.getRootLogger().addAppender(appender);
588
    }
589
}
590
```
591

592
### Fluent Configuration API
593
```java
594
import org.apache.log4j.builders.*;
595
import org.apache.log4j.*;
596

597
public class FluentConfigurationExample {
598
    public void createFluentConfiguration() {
599
        // Fluent API for complex configuration
600
        new ConfigurationBuilder()
601
            // Root logger with console output
602
            .setRootLogger(Level.INFO, 
603
                new ConsoleAppenderBuilder()
604
                    .setName("root-console")
605
                    .setLayout(new PatternLayoutBuilder()
606
                        .setConversionPattern("%-5p %c{1} - %m%n")
607
                        .build())
608
                    .build())
609
            
610
            // Application logger with file output  
611
            .addLogger("com.myapp", Level.DEBUG, false,
612
                new RollingFileAppenderBuilder()
613
                    .setName("app-file")
614
                    .setFileName("myapp.log")
615
                    .setMaxFileSize("50MB")
616
                    .setMaxBackupIndex(10)
617
                    .setLayout(new PatternLayoutBuilder()
618
                        .setConversionPattern("%d{ISO8601} [%t] %-5p %c - %m%n")
619
                        .build())
620
                    .build())
621
            
622
            // Third-party library logger with warn level
623
            .addLogger("org.apache", Level.WARN, true)
624
            .addLogger("org.springframework", Level.WARN, true)
625
            
626
            // Apply the configuration
627
            .configure();
628
    }
629
}
630
```