A RollingFileWriter is similar to the JDK-supplied FileOutputStream class: It provides an output stream for writing data to a File. It differs from a normal FileOutputStream in that it provides support for rolling, or versioned, output files.
A RollingFileWriter object can be constructed so that it will automatically roll a file over when it exceeds a certain size. If automatic rollover is not selected, then rollover occurs only at the time the file is first opened. Automatic rollover is controlled by two parameters: the maximum size for any one file and the maximum number of rolled-over files. If automatic rollover is enabled, whenever a file exceeds the configured maximum size, the RollingFileWriter closes the file, renames it so that it has a numeric suffix and reopens the (now nonexistent) original file. It also shifts previously-rolled files out of the way. The numeric suffix always starts at 0, but the number of digits varies, depending on the maximum number of files. Because automatic rollover normally occurs when the maximum number of bytes has been exceeded, it's possible for the file to roll in the middle of a line of output.
Backup files can optionally be compressed, via the gzip algorithm, at the time of roll-over.
When a RollingFileWriter is instantiated with an appropriate file pattern (see below), it first looks for an existing instance of the named file. If it finds one, it rotates the existing file and any other existing backups out of the way, by renaming them. The new name is based on the primary name, with a version number (e.g., 0, 1, 2, etc.), or index, inserted into it. The file pattern controls where the index is inserted in the file names.
The filename or pathname passed to the constructor must be a pattern that contains a special marker, the string "${n}", indicating where the file version number is to be placed. If the filename does not contain such a marker, it is invalid. When a version number must be inserted, the marker is replaced with a period (".") and an index number. The number is zero-filled, if necessary, depending on the maximum number of backup files. For instance, if the maximum number of backup files is 7, then the backup algorithm will use ".0", ".1", ..., ".6". If the maximum number of backup files is 20, the backup algorithm will use ".00", ".01", etc.) The current (or most recent file) has no extension at all; this file is called the primary file. Backup files are ordered by reverse timestamp. The newest backup file has the lowest-numbered index, and the oldest backup file has the highest-numbered index.
Examples of valid file name patterns follow:| Pattern | Maximum number of backup files | Primary file | Backup files |
|---|---|---|---|
| /tmp/foo${n}.txt | 3 | /tmp/foo.txt | /tmp/foo.0.txt /tmp/foo.1.txt /tmp/foo.2.txt |
| C:\temp\mumble${n}.log | 11 | C:\temp\mumble.log | C:\temp\mumble.00.log C:\temp\mumble.01.log C:\temp\mumble.02.log C:\temp\mumble.03.log C:\temp\mumble.04.log C:\temp\mumble.05.log C:\temp\mumble.06.log C:\temp\mumble.07.log C:\temp\mumble.08.log C:\temp\mumble.09.log |
| /tmp/mumble.log${n} | 5 | /tmp/mumble.log | /tmp/mumble.log.0 /tmp/mumble.log.1 /tmp/mumble.log.2 /tmp/mumble.log.3 /tmp/mumble.log.4 |
When a caller opens a RollingFileWriter object, it can also register a callback object that will be invoked at the moment of roll-over, to retrieve a roll-over message. This message is then written to the end of the just rolled-over file and the beginning of the new file, and can help users to determine whether a file is one of a chain of files. These special callback objects can be instances of any class that implements the RollingFileWriter.RolloverCallback interface.
| |