org.apache.derby.impl.services.stream

Class RollingFileStream

java.lang.Object

java.io.OutputStream

org.apache.derby.impl.services.stream.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.

Constructor Summary

Constructors

Constructor and 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

Modifier and Type	Method and Description
void	close() Close all the files.
void	write(int b) Implements the write method of the OutputStream.

Methods inherited from class java.io.OutputStream

flush, write, write

Methods inherited from class java.lang.Object

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

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

close

public void close()
           throws java.lang.SecurityException

Close all the files.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

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").