0
# Core Implementation
1

2
The core implementation provides the fundamental logging provider, configuration management, data structures, and asynchronous processing capabilities that power the tinylog framework.
3

4
## Capabilities
5

6
### Logging Provider
7

8
The main service provider implementation that integrates with the tinylog-api to provide actual logging functionality.
9

10
```java { .api }
11
/**
12
 * Main logging provider implementation for tinylog
13
 */
14
class TinylogLoggingProvider implements LoggingProvider {
15
    /**
16
     * Default constructor using TinylogContextProvider
17
     */
18
    public TinylogLoggingProvider();
19
    
20
    /**
21
     * Constructor with custom context provider
22
     * @param contextProvider Custom context provider implementation
23
     */
24
    protected TinylogLoggingProvider(ContextProvider contextProvider);
25
    
26
    /**
27
     * Check if logging is enabled for the given parameters
28
     * @param depth Stack trace depth for caller identification
29
     * @param tag Log tag (null for untagged)
30
     * @param level Log level
31
     * @return true if logging is enabled
32
     */
33
    public boolean isEnabled(int depth, String tag, Level level);
34
    
35
    /**
36
     * Log a message with the specified parameters
37
     * @param depth Stack trace depth for caller identification
38
     * @param tag Log tag (null for untagged)
39
     * @param level Log level
40
     * @param exception Exception to log (null if none)
41
     * @param formatter Message formatter
42
     * @param obj First message object
43
     * @param arguments Additional format arguments
44
     */
45
    public void log(int depth, String tag, Level level, Throwable exception, 
46
                   MessageFormatter formatter, Object obj, Object... arguments);
47
    
48
    /**
49
     * Log a message with logger class name
50
     * @param loggerClassName Name of the logger class
51
     * @param tag Log tag
52
     * @param level Log level
53
     * @param exception Exception to log
54
     * @param formatter Message formatter
55
     * @param obj First message object
56
     * @param arguments Additional format arguments
57
     */
58
    public void log(String loggerClassName, String tag, Level level, Throwable exception, 
59
                   MessageFormatter formatter, Object obj, Object... arguments);
60
    
61
    /**
62
     * Get minimum log level for any tag
63
     * @return Minimum log level
64
     */
65
    public Level getMinimumLevel();
66
    
67
    /**
68
     * Get minimum log level for specific tag
69
     * @param tag Log tag
70
     * @return Minimum log level for the tag
71
     */
72
    public Level getMinimumLevel(String tag);
73
    
74
    /**
75
     * Get all writers for specific tag and level
76
     * @param tag Log tag
77
     * @param level Log level
78
     * @return Collection of writers
79
     */
80
    public Collection<Writer> getWriters(String tag, Level level);
81
    
82
    /**
83
     * Get all writers for specific tag
84
     * @param tag Log tag
85
     * @return Collection of writers
86
     */
87
    public Collection<Writer> getWriters(String tag);
88
    
89
    /**
90
     * Get all writers
91
     * @return Collection of all writers
92
     */
93
    public Collection<Writer> getWriters();
94
    
95
    /**
96
     * Get the context provider used by this logging provider
97
     * @return Context provider instance
98
     */
99
    public ContextProvider getContextProvider();
100
    
101
    /**
102
     * Shutdown the logging provider and release resources
103
     * @throws InterruptedException if shutdown is interrupted
104
     */
105
    public void shutdown() throws InterruptedException;
106
}
107
```
108

109
### Log Entry
110

111
Immutable data structure containing all information for a single log entry.
112

113
```java { .api }
114
/**
115
 * Immutable holder for all log entry data
116
 */
117
class LogEntry {
118
    /**
119
     * Create a complete log entry
120
     * @param timestamp Entry timestamp
121
     * @param thread Thread that created the entry
122
     * @param context Thread-local context map
123
     * @param className Class name where logging occurred
124
     * @param methodName Method name where logging occurred
125
     * @param fileName Source file name
126
     * @param lineNumber Source line number
127
     * @param tag Log tag (null if untagged)
128
     * @param level Log level
129
     * @param message Formatted log message
130
     * @param exception Exception (null if none)
131
     */
132
    public LogEntry(Timestamp timestamp, Thread thread, Map<String, String> context,
133
                   String className, String methodName, String fileName, int lineNumber,
134
                   String tag, Level level, String message, Throwable exception);
135
    
136
    // Getter methods
137
    public Timestamp getTimestamp();
138
    public Thread getThread();
139
    public Map<String, String> getContext();
140
    public String getClassName();
141
    public String getMethodName();
142
    public String getFileName();
143
    public int getLineNumber();
144
    public String getTag();
145
    public Level getLevel();
146
    public String getMessage();
147
    public Throwable getException();
148
}
149
```
150

151
### Log Entry Values
152

153
Enumeration of all possible log entry components that writers can request.
154

155
```java { .api }
156
/**
157
 * Enumeration of log entry value types
158
 */
159
enum LogEntryValue {
160
    /**
161
     * Timestamp when the log entry was created
162
     */
163
    DATE,
164
    
165
    /**
166
     * Thread that created the log entry
167
     */
168
    THREAD,
169
    
170
    /**
171
     * Thread-local context variables
172
     */
173
    CONTEXT,
174
    
175
    /**
176
     * Class name where logging occurred
177
     */
178
    CLASS,
179
    
180
    /**
181
     * Method name where logging occurred
182
     */
183
    METHOD,
184
    
185
    /**
186
     * Source file name
187
     */
188
    FILE,
189
    
190
    /**
191
     * Source line number
192
     */
193
    LINE,
194
    
195
    /**
196
     * Log tag for categorization
197
     */
198
    TAG,
199
    
200
    /**
201
     * Log level (ERROR, WARN, INFO, DEBUG, TRACE)
202
     */
203
    LEVEL,
204
    
205
    /**
206
     * Formatted log message
207
     */
208
    MESSAGE,
209
    
210
    /**
211
     * Exception/throwable information
212
     */
213
    EXCEPTION
214
}
215
```
216

217
### Context Provider
218

219
Thread-local context management for associating key-value pairs with log entries.
220

221
```java { .api }
222
/**
223
 * Context provider using InheritableThreadLocal for thread-safe context management
224
 */
225
class TinylogContextProvider implements ContextProvider {
226
    /**
227
     * Default constructor
228
     */
229
    public TinylogContextProvider();
230
    
231
    /**
232
     * Get all context mappings for the current thread
233
     * @return Map of context key-value pairs
234
     */
235
    public Map<String, String> getMapping();
236
    
237
    /**
238
     * Get a specific context value
239
     * @param key Context key
240
     * @return Context value or null if not found
241
     */
242
    public String get(String key);
243
    
244
    /**
245
     * Set a context value for the current thread
246
     * @param key Context key
247
     * @param value Context value (converted to string)
248
     */
249
    public void put(String key, Object value);
250
    
251
    /**
252
     * Remove a context key from the current thread
253
     * @param key Context key to remove
254
     */
255
    public void remove(String key);
256
    
257
    /**
258
     * Clear all context values from the current thread
259
     */
260
    public void clear();
261
}
262
```
263

264
### Configuration Management
265

266
Configuration parsing and management for properties-based setup.
267

268
```java { .api }
269
/**
270
 * Configuration support for the logging provider
271
 */
272
class TinylogLoggingConfiguration {
273
    /**
274
     * Default constructor
275
     */
276
    public TinylogLoggingConfiguration();
277
    
278
    /**
279
     * Create writer configurations from properties
280
     * @param tags List of configured tags
281
     * @param globalLevel Global log level
282
     * @param writingThread Whether to use background writing thread
283
     * @return 2D array of writers organized by tag and level
284
     */
285
    public Collection<Writer>[][] createWriters(List<String> tags, Level globalLevel, boolean writingThread);
286
    
287
    /**
288
     * Calculate minimum log level across all writers
289
     * @param globalLevel Global log level
290
     * @param customLevels Tag-specific log levels
291
     * @return Minimum effective log level
292
     */
293
    public Level calculateMinimumLevel(Level globalLevel, Map<String, Level> customLevels);
294
    
295
    /**
296
     * Calculate required log entry values across all writers
297
     * @param writers 2D array of writers
298
     * @return 2D array of required LogEntryValue sets
299
     */
300
    public Collection<LogEntryValue>[][] calculateRequiredLogEntryValues(Collection<Writer>[][] writers);
301
    
302
    /**
303
     * Calculate stack trace requirements for exception handling
304
     * @param requiredLogEntryValues Required log entry values by writer
305
     * @return BitSet indicating which levels require full stack traces
306
     */
307
    public BitSet calculateFullStackTraceRequirements(Collection<LogEntryValue>[][] requiredLogEntryValues);
308
    
309
    /**
310
     * Create asynchronous writing thread if enabled
311
     * @param writers Writer configurations
312
     * @return WritingThread instance or null if disabled
313
     */
314
    public WritingThread createWritingThread(Collection<Writer>[][] writers);
315
    
316
    /**
317
     * Get all writers from the 2D writer array
318
     * @param writers 2D writer array
319
     * @return Flattened collection of all writers
320
     */
321
    public static Collection<Writer> getAllWriters(Collection<Writer>[][] writers);
322
    
323
    /**
324
     * Create a complete log entry from parameters
325
     * @param stackTraceElement Stack trace element for source location
326
     * @param tag Log tag
327
     * @param level Log level
328
     * @param exception Exception to log
329
     * @param formatter Message formatter
330
     * @param obj First message object
331
     * @param arguments Additional format arguments
332
     * @param requiredLogEntryValues Required log entry values by level
333
     * @param contextProvider Context provider for thread-local values
334
     * @return Complete LogEntry instance
335
     */
336
    public static LogEntry createLogEntry(StackTraceElement stackTraceElement, String tag, 
337
                                        Level level, Throwable exception, MessageFormatter formatter, Object obj,
338
                                        Object[] arguments, Collection<LogEntryValue>[] requiredLogEntryValues, 
339
                                        ContextProvider contextProvider);
340
}
341
```
342

343
### Configuration Parser
344

345
Static utilities for parsing tinylog configuration properties.
346

347
```java { .api }
348
/**
349
 * Parser for properties-based configuration
350
 */
351
class ConfigurationParser {
352
    /**
353
     * Get the global log level from configuration
354
     * @return Configured global Level
355
     */
356
    public static Level getGlobalLevel();
357
    
358
    /**
359
     * Get tag-specific log levels from configuration
360
     * @return Map of tag names to Level objects
361
     */
362
    public static Map<String, Level> getCustomLevels();
363
    
364
    /**
365
     * Get list of configured tags
366
     * @return List of tag names
367
     */
368
    public static List<String> getTags();
369
    
370
    /**
371
     * Check if asynchronous writing thread is enabled
372
     * @return true if writing thread should be used
373
     */
374
    public static boolean isWritingThreadEnabled();
375
    
376
    /**
377
     * Check if automatic shutdown is enabled
378
     * @return true if automatic shutdown is enabled
379
     */
380
    public static boolean isAutoShutdownEnabled();
381
}
382
```
383

384
### Asynchronous Writing
385

386
Background thread for asynchronous log entry processing to improve performance.
387

388
```java { .api }
389
/**
390
 * Thread for asynchronous log entry writing
391
 */
392
class WritingThread extends Thread {
393
    /**
394
     * Add a log entry to the writing queue
395
     * @param writer Target writer for the entry
396
     * @param logEntry Log entry to write
397
     */
398
    public void add(Writer writer, LogEntry logEntry);
399
    
400
    /**
401
     * Shutdown the writing thread and flush all pending entries
402
     * @throws InterruptedException if shutdown is interrupted
403
     */
404
    public void shutdown() throws InterruptedException;
405
    
406
    /**
407
     * Check if the writing thread is still alive and processing
408
     * @return true if the thread is active
409
     */
410
    public boolean isAlive();
411
}
412
```
413

414
## Usage Examples
415

416
**Basic Provider Usage (typically automatic):**
417

418
```java
419
// The provider is automatically discovered via ServiceLoader
420
// Configuration is done through tinylog.properties
421
// Direct usage is rare - normally accessed through tinylog-api
422

423
import org.tinylog.core.TinylogLoggingProvider;
424
import org.tinylog.provider.LoggingProvider;
425

426
// Get the logging provider (automatic service discovery)
427
LoggingProvider provider = new TinylogLoggingProvider();
428

429
// Check if logging is enabled
430
boolean enabled = provider.isEnabled(1, null, Level.INFO);
431

432
// Log a message (normally done through Logger API)
433
provider.log(1, null, Level.INFO, null, "Application started");
434
```
435

436
**Context Usage:**
437

438
```java
439
import org.tinylog.core.TinylogContextProvider;
440

441
TinylogContextProvider context = new TinylogContextProvider();
442

443
// Set context values
444
context.put("userId", "12345");
445
context.put("sessionId", "abc-def-ghi");
446
context.put("operation", "login");
447

448
// These values will appear in log entries for the current thread
449
Logger.info("User login attempt"); // Will include context values
450

451
// Clear context when done
452
context.clear();
453
```
454

455
**Configuration Examples:**
456

457
```properties
458
# Basic configuration
459
level=INFO
460
writer=console
461

462
# Advanced configuration with custom levels and writing thread
463
level=DEBUG
464
level@tag1=WARN
465
level@tag2=TRACE
466

467
writingthread=true
468
autoshutdown=true
469

470
writer=console
471
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} [{level}] [{tag}] {class}.{method}(): {message}
472

473
writer2=file
474
writer2.file=application.log
475
writer2.level=INFO
476
writer2.format={date} {level}: {message}
477
```
478

479
**Manual Log Entry Creation:**
480

481
```java
482
import org.tinylog.core.LogEntry;
483
import org.tinylog.core.LogEntryValue;
484
import org.tinylog.Level;
485

486
// Create a complete log entry (rarely done manually)
487
LogEntry entry = new LogEntry(
488
    new Timestamp(System.currentTimeMillis()),
489
    Thread.currentThread(),
490
    Map.of("user", "admin", "action", "delete"),
491
    "com.example.UserService",
492
    "deleteUser",
493
    "UserService.java",
494
    42,
495
    "security",
496
    Level.WARN,
497
    "User deletion attempted",
498
    null
499
);
500

501
// Log entry contains all available information
502
String className = entry.getClassName();
503
Level level = entry.getLevel();
504
Map<String, String> context = entry.getContext();
505
```
506

507
**Asynchronous Writing Setup:**
508

509
```properties
510
# Enable asynchronous writing for better performance
511
writingthread=true
512

513
# Configure multiple writers that will benefit from async processing
514
writer=file
515
writer.file=app.log
516

517
writer2=rolling file
518
writer2.file=rolling.log
519
writer2.policies=size:100MB
520

521
writer3=jdbc
522
writer3.url=jdbc:h2:mem:logs
523
writer3.table=log_entries
524
```