0
# tinylog-impl
1
2
tinylog-impl is the native implementation of the tinylog logging framework for Java, providing high-performance, lightweight logging with zero dependencies. It serves as an OSGi fragment that provides concrete implementations for all tinylog-api interfaces, including writers for various output destinations, rollover policies, throwable filters, and file converters.
3
4
## Package Information
5
6
- **Package Name**: org.tinylog:tinylog-impl
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>org.tinylog</groupId>
13
<artifactId>tinylog-impl</artifactId>
14
<version>2.7.0</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
The tinylog-impl library provides service implementations that are automatically discovered through Java's ServiceLoader mechanism. Most classes are not directly imported but configured through properties:
21
22
```java
23
// Core logging provider (automatically discovered)
24
import org.tinylog.core.TinylogLoggingProvider;
25
26
// Writers (configured via properties, but can be used directly)
27
import org.tinylog.writers.ConsoleWriter;
28
import org.tinylog.writers.FileWriter;
29
import org.tinylog.writers.RollingFileWriter;
30
31
// Policies for rolling files
32
import org.tinylog.policies.SizePolicy;
33
import org.tinylog.policies.DailyPolicy;
34
35
// Core data structures
36
import org.tinylog.core.LogEntry;
37
import org.tinylog.core.LogEntryValue;
38
```
39
40
## Basic Usage
41
42
tinylog-impl provides the underlying implementation and is typically configured through properties rather than direct API calls:
43
44
```java
45
// Configuration via tinylog.properties
46
// writer=console
47
// writer.format={date: HH:mm:ss.SSS} {level}: {message}
48
49
// The implementation provides the actual logging functionality
50
// when using tinylog-api for logging calls
51
import org.tinylog.Logger;
52
53
Logger.info("This message is handled by tinylog-impl");
54
Logger.error("Error message with exception", exception);
55
```
56
57
## Architecture
58
59
tinylog-impl is built around several key components:
60
61
- **Logging Provider**: `TinylogLoggingProvider` serves as the main service provider implementation
62
- **Writers**: Output destinations including console, files, databases, network sockets, and structured formats
63
- **Policies**: Rollover triggers for file-based writers (size, time, startup-based)
64
- **Converters**: File transformation utilities (compression, format conversion)
65
- **Filters**: Exception/throwable transformation and filtering
66
- **Configuration**: Properties-based configuration parsing and management
67
- **Threading**: Asynchronous writing capabilities with background thread management
68
69
## Capabilities
70
71
### Writers
72
73
Complete set of output destinations for log entries, from simple console output to complex database and network logging.
74
75
```java { .api }
76
// Base writer interface
77
interface Writer {
78
Collection<LogEntryValue> getRequiredLogEntryValues();
79
void write(LogEntry logEntry) throws Exception;
80
void flush() throws Exception;
81
void close() throws Exception;
82
}
83
84
// Console writer
85
class ConsoleWriter extends AbstractFormatPatternWriter {
86
// Configured via properties: writer=console
87
}
88
89
// File writer
90
class FileWriter extends AbstractFormatPatternWriter {
91
// Configured via properties: writer=file, writer.file=application.log
92
}
93
94
// Rolling file writer
95
class RollingFileWriter extends AbstractFormatPatternWriter {
96
// Supports policies and converters for advanced file management
97
}
98
```
99
100
[Writers](./writers.md)
101
102
### Rollover Policies
103
104
Policies for triggering file rollover events in RollingFileWriter, supporting time-based, size-based, and custom rollover conditions.
105
106
```java { .api }
107
interface Policy {
108
boolean continueExistingFile(String path);
109
boolean continueCurrentFile(byte[] entry);
110
void reset();
111
}
112
113
// Size-based rollover
114
class SizePolicy implements Policy {
115
// Configured via: writer.policies=size:10MB
116
}
117
118
// Time-based rollover
119
class DailyPolicy extends AbstractDatePolicy {
120
// Configured via: writer.policies=daily
121
}
122
```
123
124
[Policies](./policies.md)
125
126
### Core Implementation
127
128
Core logging provider implementation and fundamental data structures for log processing.
129
130
```java { .api }
131
// Main logging provider
132
class TinylogLoggingProvider implements LoggingProvider {
133
// Automatically discovered service provider
134
public boolean isEnabled(int depth, String tag, Level level);
135
public void log(int depth, String tag, Level level, Throwable exception,
136
MessageFormatter formatter, Object... arguments);
137
}
138
139
// Log entry data structure
140
class LogEntry {
141
public LogEntry(Timestamp timestamp, Thread thread, Map<String, String> context,
142
String className, String methodName, String fileName, int lineNumber,
143
String tag, Level level, String message, Throwable exception);
144
// Getters for all components
145
}
146
147
// Required log entry values enumeration
148
enum LogEntryValue {
149
DATE, THREAD, CONTEXT, CLASS, METHOD, FILE, LINE, TAG, LEVEL, MESSAGE, EXCEPTION
150
}
151
```
152
153
[Core Implementation](./core.md)
154
155
### Exception Handling
156
157
Throwable filters for transforming exceptions and stack traces, providing flexible error handling and logging customization.
158
159
```java { .api }
160
interface ThrowableFilter {
161
ThrowableData filter(ThrowableData origin);
162
}
163
164
// Keep full throwable information
165
class KeepThrowableFilter extends AbstractStackTraceElementsFilter {
166
// Configured via: writer.exception=keep
167
}
168
169
// Strip stack trace elements
170
class StripThrowableFilter extends AbstractStackTraceElementsFilter {
171
// Configured via: writer.exception=strip
172
}
173
```
174
175
[Exception Handling](./exception-handling.md)
176
177
### File Converters
178
179
File converters for transforming completed log files, supporting compression and custom file processing.
180
181
```java { .api }
182
interface FileConverter {
183
String getBackupSuffix();
184
void open(String fileName);
185
byte[] write(byte[] data);
186
void close();
187
void shutdown() throws InterruptedException;
188
}
189
190
// GZIP compression converter
191
class GzipFileConverter implements FileConverter {
192
// Configured via: writer.converter=gzip
193
}
194
```
195
196
[File Converters](./converters.md)
197
198
### Format Patterns
199
200
Pattern system for customizable log entry formatting using tokens to represent different log components.
201
202
```java { .api }
203
interface Token {
204
Collection<LogEntryValue> getRequiredLogEntryValues();
205
void render(LogEntry logEntry, StringBuilder builder);
206
void apply(LogEntry logEntry, PreparedStatement statement, int index) throws SQLException;
207
}
208
209
// Format pattern parser
210
class FormatPatternParser {
211
public FormatPatternParser(String filters);
212
public Collection<Token> parse(String pattern);
213
}
214
215
// Token implementations for date, message, exception, class, method, etc.
216
class DateToken implements Token { /* Date/time formatting */ }
217
class MessageToken implements Token { /* Log message rendering */ }
218
class ExceptionToken implements Token { /* Exception formatting */ }
219
```
220
221
[Format Patterns](./pattern.md)
222
223
### Raw Writers
224
225
Low-level byte array writers and decorators for advanced I/O operations and network communication.
226
227
```java { .api }
228
interface ByteArrayWriter {
229
int readTail(byte[] buffer, int offset, int length) throws IOException;
230
void write(byte[] data, int offset, int length) throws IOException;
231
void truncate(int size) throws IOException;
232
void flush() throws IOException;
233
void close() throws IOException;
234
}
235
236
// File-based raw writers
237
class RandomAccessFileWriter implements ByteArrayWriter { /* Random access file I/O */ }
238
class LockedRandomAccessFileWriter implements ByteArrayWriter { /* Thread-safe file I/O */ }
239
240
// Network writers
241
class TcpSocketWriter extends AbstractSocketWriter { /* TCP network output */ }
242
class UdpSocketWriter extends AbstractSocketWriter { /* UDP network output */ }
243
244
// Writer decorators
245
class BufferedWriterDecorator implements ByteArrayWriter { /* Buffering capability */ }
246
class SynchronizedWriterDecorator implements ByteArrayWriter { /* Thread synchronization */ }
247
```
248
249
[Raw Writers](./raw-writers.md)
250
251
## Types
252
253
```java { .api }
254
// Core log entry data
255
class LogEntry {
256
public Timestamp getTimestamp();
257
public Thread getThread();
258
public Map<String, String> getContext();
259
public String getClassName();
260
public String getMethodName();
261
public String getFileName();
262
public int getLineNumber();
263
public String getTag();
264
public Level getLevel();
265
public String getMessage();
266
public Throwable getException();
267
}
268
269
// Throwable data interface
270
interface ThrowableData {
271
String getClassName();
272
String getMessage();
273
List<StackTraceElement> getStackTrace();
274
ThrowableData getCause();
275
}
276
277
// Configuration support
278
class TinylogLoggingConfiguration {
279
public Collection<Writer>[][] createWriters(List<String> tags, Level globalLevel, boolean writingThread);
280
public Level calculateMinimumLevel(Level globalLevel, Map<String, Level> customLevels);
281
public WritingThread createWritingThread(Collection<Writer>[][] writers);
282
}
283
```