0
# Rollover Policies
1

2
Rollover policies in tinylog-impl determine when the RollingFileWriter should create a new log file and optionally archive the current one. Policies can be combined to create sophisticated rollover strategies based on file size, time, or application startup.
3

4
## Capabilities
5

6
### Base Policy Interface
7

8
All rollover policies implement the Policy interface, which defines the contract for rollover decisions.
9

10
```java { .api }
11
/**
12
 * Interface for rollover policies that determine when to create new log files
13
 */
14
interface Policy {
15
    /**
16
     * Check if an existing log file should be continued
17
     * @param path Path to the existing log file
18
     * @return true if the file should be continued, false to trigger rollover
19
     */
20
    boolean continueExistingFile(String path);
21
    
22
    /**
23
     * Check if the current log file should be continued after writing an entry
24
     * @param entry The log entry bytes that were just written
25
     * @return true if the current file should continue, false to trigger rollover
26
     */
27
    boolean continueCurrentFile(byte[] entry);
28
    
29
    /**
30
     * Reset the policy state (called after rollover)
31
     */
32
    void reset();
33
}
34
```
35

36
### Size Policy
37

38
Triggers rollover when the log file reaches a specified size limit.
39

40
```java { .api }
41
/**
42
 * Policy that triggers rollover based on file size
43
 */
44
class SizePolicy implements Policy {
45
    /**
46
     * Default constructor for size-based rollover policy
47
     */
48
    public SizePolicy();
49
    
50
    /**
51
     * Constructor for size-based rollover policy with size specification
52
     * @param argument Size specification (supports units: B, KB, MB, GB)
53
     */
54
    public SizePolicy(String argument);
55
}
56
```
57

58
**Configuration Examples:**
59

60
```properties
61
# Rollover when file reaches 10 MB
62
writer=rolling file
63
writer.file=application.log
64
writer.policies=size:10MB
65

66
# Rollover at 500 KB
67
writer=rolling file
68
writer.file=debug.log
69
writer.policies=size:500KB
70

71
# Rollover at 2 GB
72
writer=rolling file
73
writer.file=archive.log
74
writer.policies=size:2GB
75
```
76

77
**Supported Size Units:**
78
- `B` - Bytes
79
- `KB` - Kilobytes (1,024 bytes)
80
- `MB` - Megabytes (1,024 KB)
81
- `GB` - Gigabytes (1,024 MB)
82

83
### Daily Policy
84

85
Triggers rollover daily at midnight, creating date-stamped log files.
86

87
```java { .api }
88
/**
89
 * Policy that triggers rollover daily at midnight
90
 */
91
class DailyPolicy extends AbstractDatePolicy {
92
    /**
93
     * Default constructor for daily rollover at midnight
94
     */
95
    public DailyPolicy();
96
    
97
    /**
98
     * Constructor with configuration argument
99
     * @param argument Configuration argument for policy
100
     */
101
    public DailyPolicy(String argument);
102
}
103
```
104

105
**Configuration Examples:**
106

107
```properties
108
# Daily rollover at midnight (system timezone)
109
writer=rolling file
110
writer.file=daily.log
111
writer.policies=daily
112

113
# Daily rollover in specific timezone
114
writer=rolling file
115
writer.file=utc-daily.log
116
writer.policies=daily:UTC
117

118
# Daily rollover in New York timezone
119
writer=rolling file
120
writer.file=ny-daily.log
121
writer.policies=daily:America/New_York
122
```
123

124
### Monthly Policy
125

126
Triggers rollover monthly on the first day of each month at midnight.
127

128
```java { .api }
129
/**
130
 * Policy that triggers rollover monthly at midnight on the first day
131
 */
132
class MonthlyPolicy extends AbstractDatePolicy {
133
    /**
134
     * Default constructor for monthly rollover at midnight
135
     */
136
    public MonthlyPolicy();
137
    
138
    /**
139
     * Constructor with configuration argument
140
     * @param argument Configuration argument for policy
141
     */
142
    public MonthlyPolicy(String argument);
143
}
144
```
145

146
**Configuration Examples:**
147

148
```properties
149
# Monthly rollover at midnight on the 1st
150
writer=rolling file
151
writer.file=monthly.log
152
writer.policies=monthly
153

154
# Monthly rollover in UTC timezone
155
writer=rolling file
156
writer.file=monthly-utc.log
157
writer.policies=monthly:UTC
158
```
159

160
### Startup Policy
161

162
Triggers rollover when the application starts, ensuring each application run gets its own log file.
163

164
```java { .api }
165
/**
166
 * Policy that triggers rollover on application startup
167
 */
168
class StartupPolicy implements Policy {
169
    /**
170
     * Default constructor for startup-based rollover
171
     */
172
    public StartupPolicy();
173
}
174
```
175

176
**Configuration Examples:**
177

178
```properties
179
# New log file for each application startup
180
writer=rolling file
181
writer.file=startup.log
182
writer.policies=startup
183

184
# Combine with size policy for startup + size-based rollover
185
writer=rolling file
186
writer.file=app.log
187
writer.policies=startup,size:50MB
188
```
189

190
### Dynamic Policy
191

192
Advanced policy that allows custom rollover logic based on system properties, environment variables, or other dynamic conditions.
193

194
```java { .api }
195
/**
196
 * Policy with dynamic rollover conditions
197
 */
198
class DynamicPolicy implements Policy {
199
    /**
200
     * Constructor with dynamic condition expression
201
     * @param condition Dynamic condition for rollover evaluation
202
     */
203
    public DynamicPolicy(String condition);
204
}
205
```
206

207
**Configuration Examples:**
208

209
```properties
210
# Rollover based on system property
211
writer=rolling file
212
writer.file=dynamic.log
213
writer.policies=dynamic:${sys:rollover.trigger}
214

215
# Rollover based on environment variable
216
writer=rolling file
217
writer.file=env-dynamic.log
218
writer.policies=dynamic:${env:LOG_ROLLOVER}
219
```
220

221
### Abstract Date Policy
222

223
Base class for time-based policies providing common date/time functionality.
224

225
```java { .api }
226
/**
227
 * Abstract base class for date/time-based rollover policies
228
 */
229
abstract class AbstractDatePolicy implements Policy {
230
    /**
231
     * Constructor with timezone support
232
     * @param timezone Timezone for date calculations
233
     */
234
    protected AbstractDatePolicy(String timezone);
235
    
236
    /**
237
     * Get the configured timezone
238
     * @return TimeZone instance
239
     */
240
    protected TimeZone getTimeZone();
241
    
242
    /**
243
     * Calculate the next rollover time
244
     * @param currentTime Current timestamp
245
     * @return Next rollover timestamp
246
     */
247
    protected abstract long calculateNextRolloverTime(long currentTime);
248
}
249
```
250

251
## Policy Combinations
252

253
Multiple policies can be combined to create sophisticated rollover strategies. When multiple policies are specified, rollover occurs when ANY policy condition is met.
254

255
### Common Combinations
256

257
**Size + Daily Rollover:**
258
```properties
259
# Rollover daily OR when file reaches 100MB
260
writer=rolling file
261
writer.file=combined.log
262
writer.policies=daily,size:100MB
263
```
264

265
**Startup + Size Rollover:**
266
```properties
267
# New file at startup, then rollover every 50MB
268
writer=rolling file
269
writer.file=app.log
270
writer.policies=startup,size:50MB
271
```
272

273
**Multiple Time-based Policies:**
274
```properties
275
# Rollover daily in business hours, monthly otherwise
276
writer=rolling file
277
writer.file=business.log
278
writer.policies=daily:America/New_York,monthly:UTC
279
```
280

281
## Usage Examples
282

283
**Basic Size-based Rollover:**
284

285
```properties
286
writer=rolling file
287
writer.file=application.log
288
writer.policies=size:25MB
289
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} [{level}] {class}: {message}
290
```
291

292
**Time-based Rollover with Compression:**
293

294
```properties
295
writer=rolling file
296
writer.file=daily-app.log
297
writer.policies=daily
298
writer.converter=gzip
299
writer.format={date: HH:mm:ss} {level}: {message}
300
```
301

302
**Complex Multi-Policy Setup:**
303

304
```properties
305
writer=rolling file
306
writer.file=/var/log/myapp/application.log
307
writer.policies=startup,daily:UTC,size:500MB
308
writer.converter=gzip
309
writer.format={date: yyyy-MM-dd HH:mm:ss.SSS} {level} [{thread}] {class}.{method}(): {message}
310
writer.charset=UTF-8
311
writer.buffered=true
312
```
313

314
**Development vs Production Policies:**
315

316
```properties
317
# Development - new file each startup for debugging
318
writer=rolling file
319
writer.file=dev-app.log
320
writer.policies=startup,size:10MB
321

322
# Production - daily rollover with large size limit
323
writer=rolling file  
324
writer.file=/var/log/prod-app.log
325
writer.policies=daily,size:1GB
326
writer.converter=gzip
327
```
328

329
## File Naming Patterns
330

331
When rollover occurs, archived files follow specific naming patterns:
332

333
- **Size/Startup policies**: `filename.log.1`, `filename.log.2`, etc.
334
- **Daily policy**: `filename.2023-12-25.log`
335
- **Monthly policy**: `filename.2023-12.log`
336
- **With compression**: `filename.2023-12-25.log.gz`
337

338
**Custom Naming:**
339
```properties
340
writer=rolling file
341
writer.file=app-{date:yyyy-MM-dd}.log
342
writer.policies=daily
343
# Creates: app-2023-12-25.log, app-2023-12-26.log, etc.
344
```