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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private class	RollingFileStream.MeteredStream

Field Summary

Modifier and Type	Field and 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 File[]	files The array of File instance representing the rolling files
private int	limit
private String	lockFileName The lockfile name
private static HashMap<String, String>	locks
private FileOutputStream	lockStream The output stream that is used as a lock
private static final int	MAX_LOCKS
private RollingFileStream.MeteredStream	meter The underlying stream being written to that keeps track of how much has been written
private String	pattern The filename pattern.

Constructor Summary

Access	Constructor and Description
public	RollingFileStream() Construct a default `RollingFileStream`.
public	RollingFileStream(String the pattern for naming the output file pattern, int the maximum number of bytes to write to any one file limit, int the number of files to use count, boolean specifies append mode append) Initialize a `RollingFileStream` to write to a set of files with optional append.

Method Summary

Modifier and Type	Method and Description
private void	checkMeter() Invoked by the metered OutputStream
public synchronized void	close() Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Close all the files.
private void	fileDelete(final File The file to delete file) Delete a file.
private boolean	Returns: `true` if the file exists or `false` otherwise fileExists(final File The file to check file) Check to see if a file exists.
private long	Returns: The length of the file fileLength(final File The file to get the length of file) Get the length of a file.
private boolean	Returns: `true` if the file was renamed or false otherwise fileRename(final File The file to rename file1, final File The file to rename it to file2) Rename a file.
private File	Returns: The File generate(String The filename pattern pattern, int The generation number used if there is a conflict generation, int The unique number to append to the filename unique) Generates and returns File from a pattern
private String	Returns: The property value getSystemProperty(final String The propety to get property) Gets a system property.
private void	open(File The name of the file fname, boolean If `true` append to the existing file append) Opens a new file that and delegates it to a MeteredStream
private FileOutputStream	Returns: The FileOutputStream for the file openFile(final String The name of the file to open filename, final boolean if `true` open the file in append mode append) Opens a file.
private void	openFiles() Opens the output files files based on the configured pattern, limit, count, and append mode.
private synchronized void	rotate() Rotates the log files.
public void	write(int The value to write b) Implements abstract java.io.OutputStream.write. Implements the write method of the OutputStream.

Inherited from java.io.OutputStream:: flush nullOutputStream write write

Field Detail

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

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

files	back to summary
private File[] files The array of File instance representing the rolling files

limit	back to summary
private int limit

lockFileName	back to summary
private String lockFileName The lockfile name

locks	back to summary
private static HashMap<String, String> locks

lockStream	back to summary
private FileOutputStream lockStream The output stream that is used as a lock

MAX_LOCKS	back to summary
private static final int MAX_LOCKS

meter	back to summary
private RollingFileStream.MeteredStream meter The underlying stream being written to that keeps track of how much has been written

pattern	back to summary
private String pattern The filename pattern.

Constructor Detail

RollingFileStream back to summary

RollingFileStream	back to summary
public RollingFileStream() throws IOException 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) Exceptions IOException: if there are IO problems opening the files. `LoggingPermission("control"))`. NullPointerException: if pattern property is an empty String.

public RollingFileStream() throws IOException

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)

Exceptions

IOException:: if there are IO problems opening the files. LoggingPermission("control")).
NullPointerException:: if pattern property is an empty String.

RollingFileStream back to summary

RollingFileStream	back to summary
public RollingFileStream(String pattern, int limit, int count, boolean append) throws IOException 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:String the pattern for naming the output file limit:int the maximum number of bytes to write to any one file count:int the number of files to use append:boolean specifies append mode Exceptions IOException: if there are IO problems opening the files. IllegalArgumentException: if limit < 0, or count < 1. if pattern is an empty string

public RollingFileStream(String pattern, int limit, int count, boolean append) throws IOException

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:String: the pattern for naming the output file
limit:int: the maximum number of bytes to write to any one file
count:int: the number of files to use
append:boolean: specifies append mode

Exceptions

IOException:

if there are IO problems opening the files.

IllegalArgumentException:

if limit < 0, or count < 1.
if pattern is an empty string

Method Detail

checkMeter	back to summary
private void checkMeter() throws IOException Invoked by the metered OutputStream

close	back to summary
public synchronized void close() Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Close all the files.

back to summary

public synchronized void close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Close all the files.

fileDelete	back to summary
private void fileDelete(final File file) Delete a file. Parameters file:File The file to delete

fileDelete

back to summary

private void fileDelete(final File file)

Delete a file.

Parameters

file:File: The file to delete

fileExists back to summary

fileExists	back to summary
private boolean fileExists(final File file) Check to see if a file exists. Parameters file:File The file to check Returns:boolean `true` if the file exists or `false` otherwise

private boolean fileExists(final File file)

Check to see if a file exists.

Parameters

file:File: The file to check

Returns:boolean

true if the file exists or false otherwise

fileLength	back to summary
private long fileLength(final File file) Get the length of a file. Parameters file:File The file to get the length of Returns:long The length of the file

fileLength

back to summary

private long fileLength(final File file)

Get the length of a file.

Parameters

file:File: The file to get the length of

Returns:long

The length of the file

fileRename back to summary

fileRename	back to summary
private boolean fileRename(final File file1, final File file2) Rename a file. Parameters file1:File The file to rename file2:File The file to rename it to Returns:boolean `true` if the file was renamed or false otherwise

private boolean fileRename(final File file1, final File file2)

Rename a file.

Parameters

file1:File: The file to rename
file2:File: The file to rename it to

Returns:boolean

true if the file was renamed or false otherwise

generate	back to summary
private File generate(String pattern, int generation, int unique) throws IOException Generates and returns File from a pattern Parameters pattern:String The filename pattern generation:int The generation number used if there is a conflict unique:int The unique number to append to the filename Returns:File The File

generate

back to summary

private File generate(String pattern, int generation, int unique) throws IOException

Generates and returns File from a pattern

Parameters

pattern:String: The filename pattern
generation:int: The generation number used if there is a conflict
unique:int: The unique number to append to the filename

Returns:File

The File

getSystemProperty	back to summary
private String getSystemProperty(final String property) Gets a system property. Parameters property:String The propety to get Returns:String The property value

getSystemProperty

back to summary

private String getSystemProperty(final String property)

Gets a system property.

Parameters

property:String: The propety to get

Returns:String

The property value

open back to summary

open	back to summary
private void open(File fname, boolean append) throws IOException Opens a new file that and delegates it to a MeteredStream Parameters fname:File The name of the file append:boolean If `true` append to the existing file

private void open(File fname, boolean append) throws IOException

Opens a new file that and delegates it to a MeteredStream

Parameters

fname:File: The name of the file
append:boolean: If true append to the existing file

openFile back to summary

openFile	back to summary
private FileOutputStream openFile(final String filename, final boolean append) throws IOException Opens a file. Parameters filename:String The name of the file to open append:boolean if `true` open the file in append mode Returns:FileOutputStream The FileOutputStream for the file

private FileOutputStream openFile(final String filename, final boolean append) throws IOException

Opens a file.

Parameters

filename:String: The name of the file to open
append:boolean: if true open the file in append mode

Returns:FileOutputStream

The FileOutputStream for the file

openFiles	back to summary
private void openFiles() throws IOException Opens the output files files based on the configured pattern, limit, count, and append mode.

rotate	back to summary
private synchronized 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.

write back to summary

write	back to summary
public void write(int b) throws IOException Implements abstract java.io.OutputStream.write. Implements the write method of the OutputStream. This writes the value to the metered stream. Parameters b:int The value to write Exceptions IOException: Doc from java.io.OutputStream.write. if an I/O error occurs. In particular, an `IOException` may be thrown if the output stream has been closed.

public void write(int b) throws IOException

Implements abstract java.io.OutputStream.write.

Implements the write method of the OutputStream. This writes the value to the metered stream.

Parameters

b:int: The value to write

Exceptions

IOException:

Doc from java.io.OutputStream.write.

if an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.

org.apache.derby.impl.services.stream back to summary

private Class RollingFileStream.MeteredStream

Class Inheritance

extends OutputStream

java.lang.Object
java.io.OutputStream
org.apache.derby.impl.services.stream.RollingFileStream.MeteredStream

Field Summary

Modifier and Type	Field and Description
pack-priv OutputStream	out The real OutputStream to delegate to
pack-priv int	written The number of bytes written so far to the OutputStream

Constructor Summary

Access	Constructor and Description
pack-priv	MeteredStream(OutputStream The OutputStream to delegate to out, int The number of bytes currently written to the OuptutStream written) Creates a new instance of MeteredStream

Method Summary

Modifier and Type	Method and Description
public void	close() Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Closes this output stream and releases any system resources associated with this stream.
public int	getWritten()
public void	write(int the `byte`. b) Implements abstract java.io.OutputStream.write. Writes the specified byte to this output stream.

Inherited from java.io.OutputStream:: flush nullOutputStream write write

Field Detail

out	back to summary
pack-priv OutputStream out The real OutputStream to delegate to

written	back to summary
pack-priv int written The number of bytes written so far to the OutputStream

Constructor Detail

MeteredStream	back to summary
pack-priv MeteredStream(OutputStream out, int written) Creates a new instance of MeteredStream Parameters out:OutputStream The OutputStream to delegate to written:int The number of bytes currently written to the OuptutStream

MeteredStream

back to summary

pack-priv MeteredStream(OutputStream out, int written)

Creates a new instance of MeteredStream

Parameters

out:OutputStream: The OutputStream to delegate to
written:int: The number of bytes currently written to the OuptutStream

Method Detail

close back to summary

close	back to summary
public void close() throws IOException Overrides java.io.OutputStream.close. Implements java.io.Closeable.close. Doc from java.io.OutputStream.close. Closes this output stream and releases any system resources associated with this stream. The general contract of `close` is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void close() throws IOException

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Doc from java.io.OutputStream.close.

Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

getWritten	back to summary
public int getWritten()

write back to summary

write	back to summary
public void write(int b) throws IOException Implements abstract java.io.OutputStream.write. Doc from java.io.OutputStream.write. Writes the specified byte to this output stream. The general contract for `write` is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument `b`. The 24 high-order bits of `b` are ignored. Parameters b:int the `byte`. Exceptions IOException: if an I/O error occurs. In particular, an `IOException` may be thrown if the output stream has been closed.

public void write(int b) throws IOException

Implements abstract java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Parameters

b:int: the byte.

Exceptions

IOException:: if an I/O error occurs. In particular, an IOException may be thrown if the output stream has been closed.

public Class RollingFileStream

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class RollingFileStream.MeteredStream

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail