Documentation of 'org.clapper.util.io.RollingFileWriter' Java class
RollingFileWriter
Skip navigation links
org.clapper.util.io

Class 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:

    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.

    • 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

      All Methods Instance Methods Concrete Methods 
      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, close, format, format, print, print, print, print, print, print, print, print, print, printf, printf, write, write, write, write, write

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Skip navigation links

DMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.