0
# Raw Writers
1

2
Raw writers in tinylog-impl provide low-level byte array writing capabilities and decorators for advanced I/O operations. These components handle the actual file and network I/O operations underlying the higher-level writer implementations.
3

4
## Capabilities
5

6
### Byte Array Writer Interface
7

8
Core interface for writers that handle raw byte array operations.
9

10
```java { .api }
11
/**
12
 * Interface for writers that output raw byte arrays
13
 */
14
interface ByteArrayWriter {
15
    /**
16
     * Read trailing bytes from the output destination
17
     * @param buffer Buffer to read into
18
     * @param offset Offset in buffer to start reading
19
     * @param length Maximum number of bytes to read
20
     * @return Number of bytes actually read
21
     * @throws IOException if I/O operation fails
22
     */
23
    int readTail(byte[] data, int offset, int length) throws IOException;
24
    
25
    /**
26
     * Write byte array data
27
     * @param data Data to write
28
     * @param length Number of bytes to write from data
29
     * @throws IOException if I/O operation fails
30
     * @deprecated Use write(byte[], int, int) instead
31
     */
32
    @Deprecated
33
    void write(byte[] data, int length) throws IOException;
34
    
35
    /**
36
     * Write byte array data with offset and length
37
     * @param data Data to write
38
     * @param offset Offset in data to start writing
39
     * @param length Number of bytes to write
40
     * @throws IOException if I/O operation fails
41
     */
42
    void write(byte[] data, int offset, int length) throws IOException;
43
    
44
    /**
45
     * Truncate the output to specified size
46
     * @param size Size to truncate to
47
     * @throws IOException if I/O operation fails
48
     */
49
    void truncate(int size) throws IOException;
50
    
51
    /**
52
     * Flush any buffered data
53
     * @throws IOException if I/O operation fails
54
     */
55
    void flush() throws IOException;
56
    
57
    /**
58
     * Close the writer and release resources
59
     * @throws IOException if I/O operation fails
60
     */
61
    void close() throws IOException;
62
}
63
```
64

65
### Random Access File Writer
66

67
Provides random access file operations for log file management.
68

69
```java { .api }
70
/**
71
 * Writer for random access file operations
72
 */
73
class RandomAccessFileWriter implements ByteArrayWriter {
74
    /**
75
     * Create random access file writer
76
     * @param file Underlying random access file
77
     */
78
    public RandomAccessFileWriter(RandomAccessFile file);
79
}
80
```
81

82
### Locked Random Access File Writer
83

84
Thread-safe random access file writer with file locking support.
85

86
```java { .api }
87
/**
88
 * Thread-safe random access file writer with locking
89
 */
90
class LockedRandomAccessFileWriter implements ByteArrayWriter {
91
    /**
92
     * Create locked file writer
93
     * @param file Underlying random access file
94
     */
95
    public LockedRandomAccessFileWriter(RandomAccessFile file);
96
}
97
```
98

99
## Writer Decorators
100

101
Decorators provide additional functionality by wrapping other ByteArrayWriter implementations.
102

103
### Buffered Writer Decorator
104

105
Adds buffering capabilities to improve I/O performance.
106

107
```java { .api }
108
/**
109
 * Decorator that adds buffering to byte array writers
110
 */
111
class BufferedWriterDecorator implements ByteArrayWriter {
112
    /**
113
     * Create buffered writer with default buffer size
114
     * @param writer Underlying writer to decorate
115
     */
116
    public BufferedWriterDecorator(ByteArrayWriter writer);
117
    
118
    /**
119
     * Create buffered writer with custom buffer size
120
     * @param writer Underlying writer to decorate
121
     * @param bufferSize Size of internal buffer in bytes
122
     */
123
    public BufferedWriterDecorator(ByteArrayWriter writer, int bufferSize);
124
    
125
    /**
126
     * Check if auto-flush is enabled
127
     * @return true if auto-flush is enabled
128
     */
129
    public boolean isAutoFlush();
130
    
131
    /**
132
     * Set auto-flush behavior
133
     * @param autoFlush Whether to auto-flush after each write
134
     */
135
    public void setAutoFlush(boolean autoFlush);
136
}
137
```
138

139
### Charset Adjustment Writer Decorator
140

141
Handles character encoding adjustments for text data.
142

143
```java { .api }
144
/**
145
 * Decorator for character encoding adjustments
146
 */
147
class CharsetAdjustmentWriterDecorator implements ByteArrayWriter {
148
    /**
149
     * Create charset adjustment decorator with default encoding
150
     * @param writer Underlying writer to decorate
151
     */
152
    public CharsetAdjustmentWriterDecorator(ByteArrayWriter writer);
153
    
154
    /**
155
     * Create charset adjustment decorator with specific encoding
156
     * @param writer Underlying writer to decorate
157
     * @param charset Character encoding to use
158
     */
159
    public CharsetAdjustmentWriterDecorator(ByteArrayWriter writer, Charset charset);
160
    
161
    /**
162
     * Get the configured charset
163
     * @return Character encoding
164
     */
165
    public Charset getCharset();
166
}
167
```
168

169
### Synchronized Writer Decorator
170

171
Provides thread-safe access to underlying writers through synchronization.
172

173
```java { .api }
174
/**
175
 * Decorator that provides thread-safe access through synchronization
176
 */
177
class SynchronizedWriterDecorator implements ByteArrayWriter {
178
    /**
179
     * Create synchronized writer decorator
180
     * @param writer Underlying writer to decorate
181
     */
182
    public SynchronizedWriterDecorator(ByteArrayWriter writer);
183
    
184
    /**
185
     * Get the underlying writer (for testing/debugging)
186
     * @return Wrapped writer instance
187
     */
188
    public ByteArrayWriter getUnderlyingWriter();
189
}
190
```
191

192
## Network Writers
193

194
Abstract and concrete implementations for network-based log output.
195

196
### Abstract Socket Writer
197

198
Base class for network socket writers.
199

200
```java { .api }
201
/**
202
 * Abstract base class for socket-based writers
203
 */
204
abstract class AbstractSocketWriter extends AbstractFormatPatternWriter {
205
    /**
206
     * Create socket writer with configuration
207
     * @param properties Configuration properties
208
     * @throws IOException if network connection fails
209
     */
210
    protected AbstractSocketWriter(Map<String, String> properties) throws IOException;
211
    
212
    /**
213
     * Get the remote host address
214
     * @return Host address string
215
     */
216
    public String getHost();
217
    
218
    /**
219
     * Get the remote port number
220
     * @return Port number
221
     */
222
    public int getPort();
223
    
224
    /**
225
     * Check if connection is currently active
226
     * @return true if connected
227
     */
228
    public boolean isConnected();
229
    
230
    /**
231
     * Reconnect to the remote host
232
     * @throws IOException if reconnection fails
233
     */
234
    public void reconnect() throws IOException;
235
}
236
```
237

238
### TCP Socket Writer
239

240
TCP-based network writer for reliable log transmission.
241

242
```java { .api }
243
/**
244
 * Writer for TCP socket output
245
 */
246
class TcpSocketWriter extends AbstractSocketWriter {
247
    /**
248
     * Create TCP socket writer
249
     * @param properties Configuration properties (host, port, etc.)
250
     * @throws IOException if TCP connection fails
251
     */
252
    public TcpSocketWriter(Map<String, String> properties) throws IOException;
253
    
254
    /**
255
     * Get socket timeout value
256
     * @return Timeout in milliseconds
257
     */
258
    public int getSocketTimeout();
259
    
260
    /**
261
     * Set socket timeout
262
     * @param timeout Timeout in milliseconds
263
     */
264
    public void setSocketTimeout(int timeout);
265
    
266
    /**
267
     * Check if TCP keep-alive is enabled
268
     * @return true if keep-alive is enabled
269
     */
270
    public boolean isKeepAlive();
271
}
272
```
273

274
### UDP Socket Writer
275

276
UDP-based network writer for fast, connectionless log transmission.
277

278
```java { .api }
279
/**
280
 * Writer for UDP socket output
281
 */
282
class UdpSocketWriter extends AbstractSocketWriter {
283
    /**
284
     * Create UDP socket writer
285
     * @param properties Configuration properties (host, port, etc.)
286
     * @throws IOException if UDP socket creation fails
287
     */
288
    public UdpSocketWriter(Map<String, String> properties) throws IOException;
289
    
290
    /**
291
     * Get maximum packet size
292
     * @return Maximum UDP packet size in bytes
293
     */
294
    public int getMaxPacketSize();
295
    
296
    /**
297
     * Set maximum packet size
298
     * @param maxSize Maximum UDP packet size in bytes
299
     */
300
    public void setMaxPacketSize(int maxSize);
301
}
302
```
303

304
## Syslog Support
305

306
Enumerations and utilities for Syslog protocol support.
307

308
### Syslog Facility
309

310
Enumeration of standard Syslog facility codes.
311

312
```java { .api }
313
/**
314
 * Enumeration of Syslog facility codes
315
 */
316
enum SyslogFacility {
317
    /** Kernel messages */
318
    KERN(0),
319
    
320
    /** User-level messages */
321
    USER(1),
322
    
323
    /** Mail system messages */
324
    MAIL(2),
325
    
326
    /** System daemon messages */
327
    DAEMON(3),
328
    
329
    /** Security/authorization messages */
330
    AUTH(4),
331
    
332
    /** Internal syslogd messages */
333
    SYSLOG(5),
334
    
335
    /** Line printer subsystem */
336
    LPR(6),
337
    
338
    /** Network news subsystem */
339
    NEWS(7),
340
    
341
    /** UUCP subsystem */
342
    UUCP(8),
343
    
344
    /** Clock daemon */
345
    CRON(9),
346
    
347
    /** Security/authorization messages */
348
    AUTHPRIV(10),
349
    
350
    /** FTP daemon */
351
    FTP(11),
352
    
353
    /** NTP subsystem */
354
    NTP(12),
355
    
356
    /** Log audit */
357
    SECURITY(13),
358
    
359
    /** Log alert */
360
    CONSOLE(14),
361
    
362
    /** Clock daemon */
363
    CLOCK(15),
364
    
365
    /** Local use 0-7 */
366
    LOCAL0(16), LOCAL1(17), LOCAL2(18), LOCAL3(19),
367
    LOCAL4(20), LOCAL5(21), LOCAL6(22), LOCAL7(23);
368
    
369
    /**
370
     * Get facility code value
371
     * @return Numeric facility code
372
     */
373
    public int getCode();
374
}
375
```
376

377
### Syslog Severity
378

379
Enumeration of standard Syslog severity levels.
380

381
```java { .api }
382
/**
383
 * Enumeration of Syslog severity levels
384
 */
385
enum SyslogSeverity {
386
    /** System is unusable */
387
    EMERGENCY(0),
388
    
389
    /** Action must be taken immediately */
390
    ALERT(1),
391
    
392
    /** Critical conditions */
393
    CRITICAL(2),
394
    
395
    /** Error conditions */
396
    ERROR(3),
397
    
398
    /** Warning conditions */
399
    WARNING(4),
400
    
401
    /** Normal but significant condition */
402
    NOTICE(5),
403
    
404
    /** Informational messages */
405
    INFORMATIONAL(6),
406
    
407
    /** Debug-level messages */
408
    DEBUG(7);
409
    
410
    /**
411
     * Get severity code value
412
     * @return Numeric severity code
413
     */
414
    public int getCode();
415
}
416
```
417

418
## Usage Examples
419

420
**File-Based Raw Writers:**
421

422
```java
423
import org.tinylog.writers.raw.*;
424

425
// Basic random access file writing
426
RandomAccessFileWriter fileWriter = new RandomAccessFileWriter("output.log", true);
427
byte[] data = "Log entry\n".getBytes(StandardCharsets.UTF_8);
428
fileWriter.write(data, 0, data.length);
429
fileWriter.flush();
430
fileWriter.close();
431

432
// Locked file writing for shared access
433
LockedRandomAccessFileWriter lockedWriter = new LockedRandomAccessFileWriter("shared.log", true);
434
lockedWriter.write(data, 0, data.length);
435
lockedWriter.close();
436
```
437

438
**Decorated Writers:**
439

440
```java
441
// Buffered writing for performance
442
ByteArrayWriter baseWriter = new RandomAccessFileWriter("buffered.log");
443
BufferedWriterDecorator bufferedWriter = new BufferedWriterDecorator(baseWriter, 8192);
444
bufferedWriter.setAutoFlush(false);
445

446
// Thread-safe writing
447
SynchronizedWriterDecorator syncWriter = new SynchronizedWriterDecorator(bufferedWriter);
448

449
// Charset-aware writing
450
CharsetAdjustmentWriterDecorator charsetWriter = 
451
    new CharsetAdjustmentWriterDecorator(syncWriter, StandardCharsets.UTF_8);
452
```
453

454
**Network Writers Configuration:**
455

456
```properties
457
# TCP socket writer
458
writer=syslog
459
writer.host=log-server.example.com
460
writer.port=514
461
writer.protocol=tcp
462
writer.facility=daemon
463

464
# UDP socket writer with custom settings
465
writer=syslog
466
writer.host=192.168.1.100
467
writer.port=514
468
writer.protocol=udp
469
writer.facility=local0
470
writer.format={level}: {message}
471
```
472

473
**Complex Writer Stack:**
474

475
```java
476
// Create a complex writer stack: File -> Buffered -> Charset -> Synchronized
477
ByteArrayWriter writer = new RandomAccessFileWriter("complex.log", true);
478
writer = new BufferedWriterDecorator(writer, 16384);
479
writer = new CharsetAdjustmentWriterDecorator(writer, StandardCharsets.UTF_8);
480
writer = new SynchronizedWriterDecorator(writer);
481

482
// Use the decorated writer
483
String logMessage = "Complex log entry";
484
byte[] messageBytes = logMessage.getBytes(StandardCharsets.UTF_8);
485
writer.write(messageBytes, 0, messageBytes.length);
486
writer.flush();
487
```
488

489
**Syslog Integration:**
490

491
```java
492
import org.tinylog.writers.raw.SyslogFacility;
493
import org.tinylog.writers.raw.SyslogSeverity;
494

495
// Map log levels to syslog severities
496
SyslogSeverity severity = SyslogSeverity.fromLevel(Level.ERROR);
497
SyslogFacility facility = SyslogFacility.DAEMON;
498

499
// Calculate syslog priority value (facility * 8 + severity)
500
int priority = facility.getCode() * 8 + severity.getCode();
501
```
502

503
**Performance Considerations:**
504

505
```properties
506
# High-performance file writing
507
writer.buffered=true
508
writer.writingthread=true
509

510
# Use appropriate buffer sizes
511
writer.buffer.size=32768
512

513
# Network settings for reliability
514
writer.tcp.keepalive=true
515
writer.tcp.timeout=30000
516
```