0
# Writers
1

2
Writers in tinylog-impl provide output destinations for log entries, supporting various formats and destinations including console, files, databases, network sockets, and structured data formats.
3

4
## Capabilities
5

6
### Base Writer Interface
7

8
All writers implement the base Writer interface, which defines the contract for processing log entries.
9

10
```java { .api }
11
/**
12
 * Interface for writers that output log entries
13
 */
14
interface Writer {
15
    /**
16
     * Get the required log entry values for this writer
17
     * @return Collection of required LogEntryValue enums
18
     */
19
    Collection<LogEntryValue> getRequiredLogEntryValues();
20
    
21
    /**
22
     * Write a log entry
23
     * @param logEntry The log entry to write
24
     * @throws Exception if writing fails
25
     */
26
    void write(LogEntry logEntry) throws Exception;
27
    
28
    /**
29
     * Flush any buffered data
30
     * @throws Exception if flushing fails
31
     */
32
    void flush() throws Exception;
33
    
34
    /**
35
     * Close the writer and release resources
36
     * @throws Exception if closing fails
37
     */
38
    void close() throws Exception;
39
}
40
```
41

42
### Console Writer
43

44
Outputs log entries to the console (stdout/stderr) with configurable formatting.
45

46
```java { .api }
47
/**
48
 * Writer for console output with format pattern support
49
 */
50
class ConsoleWriter extends AbstractFormatPatternWriter {
51
    // Automatically configured via service provider
52
    // Configuration: writer=console
53
    // Optional: writer.format={date: HH:mm:ss.SSS} {level}: {message}
54
    //          writer.stream=out|err (default: out for INFO and below, err for WARN and above)
55
}
56
```
57

58
**Configuration Examples:**
59

60
```properties
61
# Basic console output
62
writer=console
63

64
# Console with custom format
65
writer=console
66
writer.format={date: yyyy-MM-dd HH:mm:ss} [{level}] {class}.{method}(): {message}
67

68
# Console to stderr
69
writer=console
70
writer.stream=err
71
```
72

73
### File Writer
74

75
Outputs log entries to a specified file with configurable formatting and charset support.
76

77
```java { .api }
78
/**
79
 * Writer for file output with format pattern support
80
 */
81
class FileWriter extends AbstractFormatPatternWriter {
82
    // Configuration: writer=file
83
    // Required: writer.file=path/to/logfile.log
84
    // Optional: writer.format=format_pattern
85
    //          writer.charset=UTF-8
86
    //          writer.buffered=true|false
87
    //          writer.writingthread=true|false
88
}
89
```
90

91
**Configuration Examples:**
92

93
```properties
94
# Basic file output
95
writer=file
96
writer.file=application.log
97

98
# File with custom formatting and charset
99
writer=file
100
writer.file=/var/log/myapp.log
101
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} {level} {class}: {message}
102
writer.charset=UTF-8
103
writer.buffered=true
104
```
105

106
### Rolling File Writer
107

108
Advanced file writer that supports automatic file rollover based on size, time, or custom policies.
109

110
```java { .api }
111
/**
112
 * Writer for rolling file output with policy-based rollover
113
 */
114
class RollingFileWriter extends AbstractFormatPatternWriter {
115
    // Configuration: writer=rolling file
116
    // Required: writer.file=path/to/logfile.log
117
    // Required: writer.policies=policy_specification
118
    // Optional: writer.converter=converter_type
119
    //          writer.format=format_pattern
120
    //          writer.charset=UTF-8
121
    //          writer.buffered=true|false
122
}
123
```
124

125
**Configuration Examples:**
126

127
```properties
128
# Rolling file with size policy
129
writer=rolling file
130
writer.file=application.log
131
writer.policies=size:10MB
132

133
# Rolling file with daily policy and compression
134
writer=rolling file
135
writer.file=/var/log/myapp.log
136
writer.policies=daily
137
writer.converter=gzip
138

139
# Rolling file with multiple policies
140
writer=rolling file
141
writer.file=application.log
142
writer.policies=size:50MB,daily
143
writer.format={date: yyyy-MM-dd HH:mm:ss} [{level}] {message}
144
```
145

146
### Shared File Writer
147

148
File writer that supports shared access across multiple processes using file locking.
149

150
```java { .api }
151
/**
152
 * Writer for shared file output with cross-process locking
153
 */
154
class SharedFileWriter extends AbstractFormatPatternWriter {
155
    // Configuration: writer=shared file
156
    // Required: writer.file=path/to/shared.log
157
    // Optional: writer.format=format_pattern
158
    //          writer.charset=UTF-8
159
}
160
```
161

162
### JDBC Writer
163

164
Outputs log entries to a database using JDBC connections with customizable SQL statements.
165

166
```java { .api }
167
/**
168
 * Writer for database output via JDBC
169
 */
170
class JdbcWriter extends AbstractWriter {
171
    // Configuration: writer=jdbc
172
    // Required: writer.url=jdbc_connection_url
173
    // Required: writer.table=table_name
174
    // Optional: writer.username=db_user
175
    //          writer.password=db_password
176
    //          writer.columns=column_mapping
177
    //          writer.batch=batch_size
178
}
179
```
180

181
**Configuration Examples:**
182

183
```properties
184
# Basic JDBC writer
185
writer=jdbc
186
writer.url=jdbc:h2:mem:testdb
187
writer.table=logs
188

189
# JDBC with custom columns
190
writer=jdbc
191
writer.url=jdbc:postgresql://localhost:5432/myapp
192
writer.username=logger
193
writer.password=secret
194
writer.table=application_logs
195
writer.columns.1=timestamp:timestamp
196
writer.columns.2=level:level
197
writer.columns.3=message:message
198
writer.columns.4=exception:exception
199
```
200

201
### JSON Writer
202

203
Outputs log entries in structured JSON format to files.
204

205
```java { .api }
206
/**
207
 * Writer for JSON format output to files
208
 */
209
class JsonWriter extends AbstractFileBasedWriter {
210
    // Configuration: writer=json
211
    // Required: writer.file=path/to/logs.json
212
    // Optional: writer.charset=UTF-8
213
    //          writer.buffered=true|false
214
    //          writer.field.level=level_field_name
215
    //          writer.field.message=message_field_name
216
}
217
```
218

219
**Configuration Examples:**
220

221
```properties
222
# Basic JSON output
223
writer=json
224
writer.file=application.json
225

226
# JSON with custom field names
227
writer=json
228
writer.file=logs.jsonl
229
writer.field.timestamp=ts
230
writer.field.level=severity
231
writer.field.message=msg
232
writer.field.exception=error
233
```
234

235
### Logcat Writer
236

237
Outputs log entries to Android's Logcat system for mobile applications.
238

239
```java { .api }
240
/**
241
 * Writer for Android Logcat output
242
 */
243
class LogcatWriter extends AbstractWriter {
244
    // Configuration: writer=logcat
245
    // Optional: writer.tag=application_tag
246
}
247
```
248

249
### Syslog Writer
250

251
Outputs log entries to Syslog servers using UDP or TCP protocols with RFC 3164/5424 support.
252

253
```java { .api }
254
/**
255
 * Writer for Syslog protocol output
256
 */
257
class SyslogWriter extends AbstractFormatPatternWriter {
258
    // Configuration: writer=syslog
259
    // Required: writer.host=syslog_server_host
260
    // Optional: writer.port=514
261
    //          writer.facility=user|mail|daemon|auth|etc (default: user)
262
    //          writer.protocol=udp|tcp (default: udp)
263
    //          writer.format=format_pattern
264
}
265
```
266

267
**Configuration Examples:**
268

269
```properties
270
# Basic syslog output
271
writer=syslog
272
writer.host=syslog.example.com
273

274
# Syslog with custom facility and TCP
275
writer=syslog
276
writer.host=log-server.internal
277
writer.port=514
278
writer.facility=daemon
279
writer.protocol=tcp
280
writer.format={level}: {class} - {message}
281
```
282

283
## Abstract Base Classes
284

285
### AbstractWriter
286

287
Base implementation providing common functionality for all writers.
288

289
```java { .api }
290
/**
291
 * Abstract base class for all writers
292
 */
293
abstract class AbstractWriter implements Writer {
294
    /**
295
     * Create writer from configuration properties
296
     * @param properties Configuration properties
297
     */
298
    protected AbstractWriter(Map<String, String> properties);
299
    
300
    /**
301
     * Parse required log entry values from configuration
302
     * @param properties Configuration properties
303
     * @return Set of required LogEntryValue enums
304
     */
305
    protected Set<LogEntryValue> getRequiredLogEntryValuesFromConfiguration(Map<String, String> properties);
306
}
307
```
308

309
### AbstractFileBasedWriter
310

311
Base class for file-based writers providing common file handling functionality.
312

313
```java { .api }
314
/**
315
 * Abstract base class for file-based writers
316
 */
317
abstract class AbstractFileBasedWriter extends AbstractWriter {
318
    /**
319
     * Get the configured file path
320
     * @return File path string
321
     */
322
    protected String getFileName();
323
    
324
    /**
325
     * Get the configured charset
326
     * @return Charset for file encoding
327
     */
328
    protected Charset getCharset();
329
    
330
    /**
331
     * Check if buffered writing is enabled
332
     * @return true if buffered
333
     */
334
    protected boolean isBuffered();
335
}
336
```
337

338
### AbstractFormatPatternWriter
339

340
Base class for writers that support format patterns for log entry formatting.
341

342
```java { .api }
343
/**
344
 * Abstract base class for writers with format pattern support
345
 */
346
abstract class AbstractFormatPatternWriter extends AbstractFileBasedWriter {
347
    /**
348
     * Render log entry using the configured format pattern
349
     * @param logEntry The log entry to render
350
     * @return Rendered string
351
     */
352
    protected String render(LogEntry logEntry);
353
    
354
    /**
355
     * Get the configured format pattern
356
     * @return Format pattern string
357
     */
358
    protected String getFormatPattern();
359
}
360
```
361

362
## Usage Examples
363

364
**Multiple Writers Configuration:**
365

366
```properties
367
# Configure multiple writers
368
writer=console,file,rolling file
369

370
# Console writer settings
371
writer1=console
372
writer1.format={date: HH:mm:ss} {level}: {message}
373

374
# File writer settings  
375
writer2=file
376
writer2.file=debug.log
377
writer2.level=DEBUG
378

379
# Rolling file writer settings
380
writer3=rolling file
381
writer3.file=application.log
382
writer3.policies=size:10MB,daily
383
writer3.converter=gzip
384
writer3.level=INFO
385
```
386

387
**Tag-Specific Writers:**
388

389
```properties
390
# Different writers for different tags
391
writer=console
392
writer.tag=performance
393
writer.format=PERF: {message}
394

395
writer2=file
396
writer2.tag=security
397
writer2.file=security.log
398
writer2.format={date}: {level} - {message}
399
```