org.clapper.util.io

Class RollingFileWriter

java.lang.Object

java.io.Writer

java.io.PrintWriter

org.clapper.util.io.RollingFileWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class RollingFileWriter
extends java.io.PrintWriter

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:

Patterns

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.

Caveats

1. When automatic rollover is enabled, be careful not to choose a the maximum file size value that's too small.
2. If you instantiate a RollingFileWriter handler for a given file and you specify a different maximum number of rolled-over files than the previous time you opened the file, the RollingFileWriter object may ignore previously rolled over files. For instance, if you instantiate a RollingFileWriter object to write to error.log{$n}, and you elect to retain 10 files, you'll eventually end up with error.log, error.log.0, ..., error.log.9. If, in a later invocation of your application, you instantiate a RollingFileWriter object to write to error.log, but you elect to retain 100 files, the second RollingFileWriter object will never notice the rolled-over files created by the first application run, because it'll be using a 2-digit numeric extension (and, therefore, looking for files error.log.00, error.log.01, ..., error.log.99).
3. This class doesn't check for roll-over until one of the println() methods is called.
4. A rolled-over file can be a little larger than the actual maximum size, depending on the length of the line that triggered the roll-over.

See Also:

File, PrintWriter

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RollingFileWriter.Compression An enumeration of constants defining whether or not to compress backup files.
static interface	RollingFileWriter.RolloverCallback Defines the interface to a callback object containing methods that a RollingFileWriter can invoke during processing.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	INDEX_PATTERN The pattern to substitute.

Fields inherited from class java.io.PrintWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor and Description
RollingFileWriter(java.lang.String fileNamePattern) Constructs a RollingFileWriter that does not do automatic file roll-over.
RollingFileWriter(java.lang.String fileNamePattern, long maxRolledFileSize, int maxRolledFiles, RollingFileWriter.Compression compressionType) Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size.
RollingFileWriter(java.lang.String fileNamePattern, RollingFileWriter.Compression compressionType) Constructs a RollingFileWriter that does not do automatic file roll-over.
RollingFileWriter(java.lang.String fileNamePattern, java.lang.String charsetName, long maxRolledFileSize, int maxRolledFiles) Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size.
RollingFileWriter(java.lang.String fileNamePattern, java.lang.String charsetName, long maxRolledFileSize, int maxRolledOverFiles, RollingFileWriter.Compression compressionType, RollingFileWriter.RolloverCallback callback) Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size.
RollingFileWriter(java.lang.String fileNamePattern, java.lang.String charsetName, RollingFileWriter.Compression compressionType) Constructs a RollingFileWriter that does not do automatic file roll-over.

Method Summary

Modifier and Type	Method and Description
void	flush() Flush the stream.
java.lang.String	getPathName() Get the path name of the file being written to.
void	println() Finish the current line, rolling the file if necessary.
void	println(boolean b) Print a boolean and finish the line, rolling the file if necessary.
void	println(char c) Print a character and finish the line, rolling the file if necessary.
void	println(char[] s) Print an array of characters and finish the line, rolling the file if necessary.
void	println(double d) Print a double and finish the line, rolling the file if necessary.
void	println(float f) Print a float and finish the line, rolling the file if necessary.
void	println(int i) Print an integer and finish the line, rolling the file if necessary.
void	println(long l) Print a long and finish the line, rolling the file if necessary.
void	println(java.lang.Object o) Print an Object and finish the line, rolling the file if necessary.
void	println(short s) Print a short and finish the line, rolling the file if necessary.
void	println(java.lang.String s) Print a String and finish the line, rolling the file if necessary.

Methods inherited from class java.io.PrintWriter

append, append, append, checkError, clearError, close, format, format, print, print, print, print, print, print, print, print, print, printf, printf, setError, write, write, write, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INDEX_PATTERN

public static final java.lang.String INDEX_PATTERN

The pattern to substitute. Useful for classes that have to insert this pattern into a string.

See Also:

Constant Field Values

Constructor Detail

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern)
                  throws IOExceptionExt

Constructs a RollingFileWriter that does not do automatic file roll-over. Roll-over of any existing files does occur at the instant the file is opened (i.e., by this constructor), but does not occur on the fly while the file is being written. Backups are not compressed.

Parameters:

fileNamePattern - The name pattern for the file to open

Throws:

IOExceptionExt - Failed to open file

See Also:

RollingFileWriter(String,Compression), RollingFileWriter(String,String,Compression), RollingFileWriter(String,long,int,Compression), RollingFileWriter(String,String,long,int,Compression,RolloverCallback)

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern,
                         RollingFileWriter.Compression compressionType)
                  throws IOExceptionExt

Constructs a RollingFileWriter that does not do automatic file roll-over. Roll-over of any existing files does occur at the instant the file is opened (i.e., by this constructor), but does not occur on the fly while the file is being written.

Parameters:

fileNamePattern - The name pattern for the file to open

compressionType - RollingFileWriter.Compression.COMPRESS_BACKUPS to compress backups, RollingFileWriter.Compression.DONT_COMPRESS_BACKUPS to leave backups uncompressed

Throws:

IOExceptionExt - Failed to open file

See Also:

RollingFileWriter(String), RollingFileWriter(String,String,Compression), RollingFileWriter(String,long,int,Compression), RollingFileWriter(String,String,long,int,Compression,RolloverCallback)

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern,
                         java.lang.String charsetName,
                         RollingFileWriter.Compression compressionType)
                  throws IOExceptionExt

Constructs a RollingFileWriter that does not do automatic file roll-over. Roll-over of any existing files does occur at the instant the file is opened (i.e., by this constructor), but does not occur on the fly while the file is being written.

Parameters:

fileNamePattern - The name pattern for the file to open

charsetName - The name of the character encoding to use for the output, or null for the default

compressionType - RollingFileWriter.Compression.COMPRESS_BACKUPS to compress backups, RollingFileWriter.Compression.DONT_COMPRESS_BACKUPS to leave backups uncompressed

Throws:

IOExceptionExt - Failed to open file

See Also:

RollingFileWriter(String), RollingFileWriter(String,Compression), RollingFileWriter(String,long,int,Compression), RollingFileWriter(String,String,long,int,Compression,RolloverCallback)

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern,
                         java.lang.String charsetName,
                         long maxRolledFileSize,
                         int maxRolledFiles)
                  throws IOExceptionExt

Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size. No RollingFileWriter.RolloverCallback object will be registered, and rolled files will not be compressed.

Parameters:

fileNamePattern - The name pattern for the file to open

charsetName - The name of the character encoding to use for the output, or null for the default

maxRolledFileSize - The maximum size, in bytes, that the file can be before it is rolled over, or 0 for no maximum.

maxRolledFiles - The maximum number of rolled-over log files to retain, or 0 for no maximum.

Throws:

IOExceptionExt - Failed to open file.

See Also:

RollingFileWriter(String), RollingFileWriter(String,Compression), RollingFileWriter(String,String,Compression), RollingFileWriter(String,String,long,int,Compression,RolloverCallback)

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern,
                         long maxRolledFileSize,
                         int maxRolledFiles,
                         RollingFileWriter.Compression compressionType)
                  throws IOExceptionExt

Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size. No RollingFileWriter.RolloverCallback object will be registered.

Parameters:

fileNamePattern - The name pattern for the file to open

maxRolledFileSize - The maximum size, in bytes, that the file can be before it is rolled over, or 0 for no maximum.

maxRolledFiles - The maximum number of rolled-over log files to retain, or 0 for no maximum.

compressionType - RollingFileWriter.Compression.COMPRESS_BACKUPS to compress backups, RollingFileWriter.Compression.DONT_COMPRESS_BACKUPS to leave backups uncompressed

Throws:

IOExceptionExt - Failed to open file.

See Also:

RollingFileWriter(String), RollingFileWriter(String,Compression), RollingFileWriter(String,String,Compression), RollingFileWriter(String,String,long,int,Compression,RolloverCallback)

RollingFileWriter

public RollingFileWriter(java.lang.String fileNamePattern,
                         java.lang.String charsetName,
                         long maxRolledFileSize,
                         int maxRolledOverFiles,
                         RollingFileWriter.Compression compressionType,
                         RollingFileWriter.RolloverCallback callback)
                  throws IOExceptionExt

Create a new RollingFileWriter that will write to the specified file, optionally automatically rolling the file over when it exceeds a specified maximum size.

Parameters:

fileNamePattern - The name pattern for the file to open

charsetName - The name of the character encoding to use for the output, or null for the default

maxRolledFileSize - The maximum size, in bytes, that the file can be before it is rolled over, or 0 for no maximum.

maxRolledOverFiles - The maximum number of rolled-over log files to retain, or 0 for no maximum.

compressionType - RollingFileWriter.Compression.COMPRESS_BACKUPS to compress backups, RollingFileWriter.Compression.DONT_COMPRESS_BACKUPS to leave backups uncompressed

callback - The callback object to invoke on roll-over, or null for none

Throws:

IOExceptionExt - Failed to open file.

See Also:

RollingFileWriter(String), RollingFileWriter(String,Compression), RollingFileWriter(String,String,Compression), RollingFileWriter(String,long,int,Compression)

Method Detail

getPathName

public java.lang.String getPathName()

Get the path name of the file being written to.

Returns:

The file's name

flush

public void flush()

Flush the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams. This method does not check for roll-over, because it's possible to flush the object in the middle of a line, and roll-over should only occur at the end of a line.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.PrintWriter

println

public void println()

Finish the current line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

println

public void println(boolean b)

Print a boolean and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

b - The boolean to print

println

public void println(char c)

Print a character and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

c - The character to print

println

public void println(char[] s)

Print an array of characters and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

s - The array of characters to print

println

public void println(double d)

Print a double and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

d - The double floating point number to print

println

public void println(float f)

Print a float and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

f - The floating point number to print

println

public void println(int i)

Print an integer and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

i - The integer to print

println

public void println(long l)

Print a long and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

l - The long to print

println

public void println(short s)

Print a short and finish the line, rolling the file if necessary.

Parameters:

s - The short to print

println

public void println(java.lang.String s)

Print a String and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

s - The String to print.

println

public void println(java.lang.Object o)

Print an Object and finish the line, rolling the file if necessary.

Overrides:

println in class java.io.PrintWriter

Parameters:

o - The object to print.