Class RollingFileStream

java.lang.Object
java.io.OutputStream
org.apache.derby.impl.services.stream.RollingFileStream
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable

public class RollingFileStream extends 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 Details

    • meter

      The underlying stream being written to that keeps track of how much has been written
    • 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 String pattern
      The filename pattern.
    • lockFileName

      private String lockFileName
      The lockfile name
    • lockStream

      private FileOutputStream lockStream
      The output stream that is used as a lock
    • files

      private File[] files
      The array of File instance representing the rolling files
    • MAX_LOCKS

      private static final int MAX_LOCKS
      See Also:
    • locks

      private static HashMap<String,String> locks
  • Constructor Details

    • RollingFileStream

      public RollingFileStream() throws IOException, 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:
      IOException - if there are IO problems opening the files.
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control")).
      NullPointerException - if pattern property is an empty String.
    • RollingFileStream

      public RollingFileStream(String pattern, int limit, int count, boolean append) throws IOException, 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:
      IOException - if there are IO problems opening the files.
      SecurityException - if a security manager exists and if the caller does not have LoggingPermission("control").
      IllegalArgumentException - if limit < 0, or count < 1.
      IllegalArgumentException - if pattern is an empty string
  • Method Details

    • write

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

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

      private File generate(String pattern, int generation, int unique) throws 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:
      IOException
    • rotate

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

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

      private String getSystemProperty(String property)
      Gets a system property in a privileged block
      Parameters:
      property - The propety to get
      Returns:
      The property value
    • openFile

      private FileOutputStream openFile(String filename, boolean append) throws 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:
      IOException
    • fileExists

      private boolean fileExists(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(File file)
      Delete a file in a privilege block
      Parameters:
      file - The file to delete
    • fileRename

      private boolean fileRename(File file1, 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(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(File fname, boolean append) throws 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:
      IOException
    • checkMeter

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