Package org.apache.derby.impl.services.stream

Class RollingFileStream

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
    public class RollingFileStream
extends java.io.OutputStream
    This class provides rolling file OutputStream. The file pattern, file size, and number of files can be customized.

    This class borrows extensively from the java.util.logger.FileHandler class for its file handling ability and instead of handling logger messages it extends java.io.OutputStream.

    A pattern consists of a string that includes the following special components that will be replaced at runtime:

    • "/" the local pathname separator
    • "%t" the system temporary directory
    • "%h" the value of the "user.home" system property
    • "%d" the value of the "derby.system.home" system property
    • "%g" the generation number to distinguish rotated logs
    • "%u" a unique number to resolve conflicts
    • "%%" translates to a single percent sign "%"
    If no "%g" field has been specified and the file count is greater than one, then the generation number will be added to the end of the generated filename, after a dot.

    Thus for example a pattern of "%t/java%g.log" with a count of 2 would typically cause files to be written on Solaris to /var/tmp/java0.log and /var/tmp/java1.log whereas on Windows 95 they would be typically written to C:\TEMP\java0.log and C:\TEMP\java1.log

    Generation numbers follow the sequence 0, 1, 2, etc.

    Normally the "%u" unique field is set to 0. However, if the FileHandler tries to open the filename and finds the file is currently in use by another process it will increment the unique number field and try again. This will be repeated until FileHandler finds a file name that is not currently in use. If there is a conflict and no "%u" field has been specified, it will be added at the end of the filename after a dot. (This will be after any automatically added generation number.)

    Thus if three processes were all trying to output to fred%u.%g.txt then they might end up using fred0.0.txt, fred1.0.txt, fred2.0.txt as the first file in their rotating sequences.

    Note that the use of unique ids to avoid conflicts is only guaranteed to work reliably when using a local disk file system.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean append
      The append flag which indicates at creation time to append to an existing file or to always create a new one
      private int count
      The rolling file count.
      private java.io.File[] files
      The array of File instance representing the rolling files
      private int limit  
      private java.lang.String lockFileName
      The lockfile name
      private static java.util.HashMap<java.lang.String,​java.lang.String> locks  
      private java.io.FileOutputStream lockStream
      The output stream that is used as a lock
      private static int MAX_LOCKS  
      private RollingFileStream.MeteredStream meter
      The underlying stream being written to that keeps track of how much has been written
      private java.lang.String pattern
      The filename pattern.

    • Constructor Summary

      Constructors 
      Constructor Description
      RollingFileStream()
      Construct a default RollingFileStream.
      RollingFileStream​(java.lang.String pattern, int limit, int count, boolean append)
      Initialize a RollingFileStream to write to a set of files with optional append.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void checkMeter()
      Invoked by the metered OutputStream
      void close()
      Close all the files.
      private void fileDelete​(java.io.File file)
      Delete a file in a privilege block
      private boolean fileExists​(java.io.File file)
      Check to see if a file exists in a privilege block
      private long fileLength​(java.io.File file)
      Get the length of a file in a privilege block
      private boolean fileRename​(java.io.File file1, java.io.File file2)
      Rename a file in a privilege block
      private java.io.File generate​(java.lang.String pattern, int generation, int unique)
      Generates and returns File from a pattern
      private java.lang.String getSystemProperty​(java.lang.String property)
      Gets a system property in a privileged block
      private void open​(java.io.File fname, boolean append)
      Opens a new file that and delegates it to a MeteredStream
      private java.io.FileOutputStream openFile​(java.lang.String filename, boolean append)
      Opens a file in the privileged block
      private void openFiles()
      Opens the output files files based on the configured pattern, limit, count, and append mode.
      private void rotate()
      Rotates the log files.
      void write​(int b)
      Implements the write method of the OutputStream.

      • Methods inherited from class java.io.OutputStream

        flush, nullOutputStream, write, write

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • append

        private boolean append
        The append flag which indicates at creation time to append to an existing file or to always create a new one

      • limit

        private int limit

      • count

        private int count
        The rolling file count. This many files will be created before the oldest is removed and the files rolled.

      • pattern

        private java.lang.String pattern
        The filename pattern.

      • lockFileName

        private java.lang.String lockFileName
        The lockfile name

      • lockStream

        private java.io.FileOutputStream lockStream
        The output stream that is used as a lock

      • files

        private java.io.File[] files
        The array of File instance representing the rolling files

      • locks

        private static java.util.HashMap<java.lang.String,​java.lang.String> locks

    • Constructor Detail

      • RollingFileStream

        public RollingFileStream()
                  throws java.io.IOException,
                         java.lang.SecurityException
        Construct a default RollingFileStream. This will be configured entirely with default values:
        • pattern - %d/derby-%g.log (DERBY_HOME/derby-0.log)
        • limit - 0 (unlimited)
        • count - 1 (one file)
        • append - false (overwrite and not append)
        Throws:
        java.io.IOException - if there are IO problems opening the files.
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control")).
        java.lang.NullPointerException - if pattern property is an empty String.

      • RollingFileStream

        public RollingFileStream​(java.lang.String pattern,
                         int limit,
                         int count,
                         boolean append)
                  throws java.io.IOException,
                         java.lang.SecurityException
        Initialize a RollingFileStream to write to a set of files with optional append. When (approximately) the given limit has been written to one file, another file will be opened. The output will cycle through a set of count files.
        Parameters:
        pattern - the pattern for naming the output file
        limit - the maximum number of bytes to write to any one file
        count - the number of files to use
        append - specifies append mode
        Throws:
        java.io.IOException - if there are IO problems opening the files.
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
        java.lang.IllegalArgumentException - if limit < 0, or count < 1.
        java.lang.IllegalArgumentException - if pattern is an empty string

    • Method Detail

      • write

        public void write​(int b)
           throws java.io.IOException
        Implements the write method of the OutputStream. This writes the value to the metered stream.
        Specified by:
        write in class java.io.OutputStream
        Parameters:
        b - The value to write
        Throws:
        java.io.IOException

      • openFiles

        private void openFiles()
                throws java.io.IOException
        Opens the output files files based on the configured pattern, limit, count, and append mode.
        Throws:
        java.io.IOException

      • generate

        private java.io.File generate​(java.lang.String pattern,
                              int generation,
                              int unique)
                       throws java.io.IOException
        Generates and returns File from a pattern
        Parameters:
        pattern - The filename pattern
        generation - The generation number used if there is a conflict
        unique - The unique number to append to the filename
        Returns:
        The File
        Throws:
        java.io.IOException

      • rotate

        private void rotate()
             throws java.io.IOException
        Rotates the log files. The metered OutputStream is closed,the log files are rotated and then a new metered OutputStream is created.
        Throws:
        java.io.IOException

      • close

        public void close()
           throws java.lang.SecurityException
        Close all the files.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        java.lang.SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").

      • getSystemProperty

        private java.lang.String getSystemProperty​(java.lang.String property)
        Gets a system property in a privileged block
        Parameters:
        property - The propety to get
        Returns:
        The property value

      • openFile

        private java.io.FileOutputStream openFile​(java.lang.String filename,
                                          boolean append)
                                   throws java.io.IOException
        Opens a file in the privileged block
        Parameters:
        filename - The name of the file to open
        append - if true open the file in append mode
        Returns:
        The FileOutputStream for the file
        Throws:
        java.io.IOException

      • fileExists

        private boolean fileExists​(java.io.File file)
        Check to see if a file exists in a privilege block
        Parameters:
        file - The file to check
        Returns:
        true if the file exists or false otherwise

      • fileDelete

        private void fileDelete​(java.io.File file)
        Delete a file in a privilege block
        Parameters:
        file - The file to delete

      • fileRename

        private boolean fileRename​(java.io.File file1,
                           java.io.File file2)
        Rename a file in a privilege block
        Parameters:
        file1 - The file to rename
        file2 - The file to rename it to
        Returns:
        true if the file was renamed or false otherwise

      • fileLength

        private long fileLength​(java.io.File file)
        Get the length of a file in a privilege block
        Parameters:
        file - The file to get the length of
        Returns:
        The length of the file

      • open

        private void open​(java.io.File fname,
                  boolean append)
           throws java.io.IOException
        Opens a new file that and delegates it to a MeteredStream
        Parameters:
        fname - The name of the file
        append - If true append to the existing file
        Throws:
        java.io.IOException

      • checkMeter

        private void checkMeter()
                 throws java.io.IOException
        Invoked by the metered OutputStream
        Throws:
        java.io.IOException