Simple file logging Handler.

The FileHandler can either write to a specified file, or it can write to a rotating set of files.

For a rotating set of files, as each file reaches a given size limit, it is closed, rotated out, and a new file opened. Successively older files are named by adding "0", "1", "2", etc. into the base filename.

By default buffering is enabled in the IO libraries but each log record is flushed out when it is complete.

By default the XMLFormatter class is used for formatting.

Configuration: By default each FileHandler is initialized using the following LogManager configuration properties where <handler-name> refers to the fully-qualified class name of the handler. If properties are not defined (or have invalid values) then the specified default values are used.

<handler-name>.level specifies the default level for the Handler (defaults to Level.ALL).
<handler-name>.filter specifies the name of a Filter class to use (defaults to no Filter).
<handler-name>.formatter specifies the name of a Formatter class to use (defaults to java.util.logging.XMLFormatter)
<handler-name>.encoding the name of the character set encoding to use (defaults to the default platform encoding).
<handler-name>.limit specifies an approximate maximum amount to write (in bytes) to any one file. If this is zero, then there is no limit. (Defaults to no limit).
<handler-name>.count specifies how many output files to cycle through (defaults to 1).
<handler-name>.pattern specifies a pattern for generating the output file name. See below for details. (Defaults to "%h/java%u.log").
<handler-name>.append specifies whether the FileHandler should append onto any existing files (defaults to false).
<handler-name>.maxLocks specifies the maximum number of concurrent locks held by FileHandler (defaults to 100).

For example, the properties for FileHandler would be:

java.util.logging.FileHandler.level=INFO
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

For a custom handler, e.g. com.foo.MyHandler, the properties would be:

com.foo.MyHandler.level=INFO
com.foo.MyHandler.formatter=java.util.logging.SimpleFormatter

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
"%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 log 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 log 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 static class	FileHandler.InitializationErrorManager
private static class	FileHandler.MeteredStream A metered stream is a subclass of OutputStream that (a) forwards all its output to a target stream (b) keeps track of how many bytes have been written

Field Summary

Modifier and Type	Field and Description
private boolean	append
private int	count
private File[]	files
private long	limit
private FileChannel	lockFileChannel
private String	lockFileName
private static final Set<String>	locks
private static final int	MAX_LOCKS
private int	maxLocks
private FileHandler.MeteredStream	meter
private String	pattern

Constructor Summary

Access	Constructor and Description
public	FileHandler() Construct a default `FileHandler`.
public	FileHandler(String the name of the output file pattern) Initialize a `FileHandler` to write to the given filename.
public	FileHandler(String the name of the output file pattern, boolean specifies append mode append) Initialize a `FileHandler` to write to the given filename, with optional append.
public	FileHandler(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) Initialize a `FileHandler` to write to a set of files.
public	FileHandler(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 `FileHandler` to write to a set of files with optional append.
public	FileHandler(String the pattern for naming the output file pattern, long 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 `FileHandler` to write to a set of files with optional append.

Method Summary

Modifier and Type	Method and Description
public synchronized void	close() Overrides java.util.logging.StreamHandler.close. Close all the files.
private void	configure() Configure a FileHandler from LogManager properties and/or default values as specified in the class javadoc.
private File	Returns: the generated File generate(String the pattern for naming the output file pattern, int the generation number to distinguish rotated logs generation, int a unique number to resolve conflicts unique) Generate a file based on a user-supplied pattern, generation number, and an integer uniqueness suffix
pack-priv static File	generate(String pat, int count, int generation, int unique)
private boolean	isParentWritable(Path path)
private void	open(File fname, boolean append)
private void	openFiles() Open the set of output files, based on the configured instance variables.
public void	publish(LogRecord description of the log event. A null record is silently ignored and is not published record) Overrides java.util.logging.StreamHandler.publish. Format and publish a `LogRecord`.
private synchronized void	rotate() Rotate the set of output files
pack-priv void	synchronousPostWriteHook() Overrides java.util.logging.StreamHandler.synchronousPostWriteHook. Overridden by other handlers in this package to facilitate synchronous post-write behaviour.

Inherited from java.util.logging.StreamHandler:: flush isLoggable setEncoding setOutputStream

Field Detail

append	back to summary
private boolean append

count	back to summary
private int count

files	back to summary
private File[] files

limit	back to summary
private long limit

lockFileChannel	back to summary
private FileChannel lockFileChannel

lockFileName	back to summary
private String lockFileName

locks	back to summary
private static final Set<String> locks

MAX_LOCKS	back to summary
private static final int MAX_LOCKS

maxLocks	back to summary
private int maxLocks

meter	back to summary
private FileHandler.MeteredStream meter

pattern	back to summary
private String pattern

Constructor Detail

FileHandler back to summary

FileHandler	back to summary
public FileHandler() throws IOException Construct a default `FileHandler`. This will be configured entirely from `LogManager` properties (or their default values). Exceptions IOException: if there are IO problems opening the files. NullPointerException: if pattern property is an empty String.

public FileHandler() throws IOException

Construct a default FileHandler. This will be configured entirely from LogManager properties (or their default values).

Exceptions

IOException:: if there are IO problems opening the files.
NullPointerException:: if pattern property is an empty String.

FileHandler back to summary

FileHandler	back to summary
public FileHandler(String pattern) throws IOException Initialize a `FileHandler` to write to the given filename. The `FileHandler` is configured based on `LogManager` properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to no limit, and the file count is set to one. There is no limit on the amount of data that may be written, so use this with care. Parameters pattern:String the name of the output file Exceptions IOException: if there are IO problems opening the files. IllegalArgumentException: if pattern is an empty string

public FileHandler(String pattern) throws IOException

Initialize a FileHandler to write to the given filename.

The FileHandler is configured based on LogManager properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to no limit, and the file count is set to one.

There is no limit on the amount of data that may be written, so use this with care.

Parameters

pattern:String: the name of the output file

Exceptions

IOException:: if there are IO problems opening the files.
IllegalArgumentException:: if pattern is an empty string

FileHandler back to summary

FileHandler	back to summary
public FileHandler(String pattern, boolean append) throws IOException Initialize a `FileHandler` to write to the given filename, with optional append. The `FileHandler` is configured based on `LogManager` properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to no limit, the file count is set to one, and the append mode is set to the given `append` argument. There is no limit on the amount of data that may be written, so use this with care. Parameters pattern:String the name of the output file append:boolean specifies append mode Exceptions IOException: if there are IO problems opening the files. IllegalArgumentException: if pattern is an empty string

public FileHandler(String pattern, boolean append) throws IOException

Initialize a FileHandler to write to the given filename, with optional append.

There is no limit on the amount of data that may be written, so use this with care.

Parameters

pattern:String: the name of the output file
append:boolean: specifies append mode

Exceptions

IOException:: if there are IO problems opening the files.
IllegalArgumentException:: if pattern is an empty string

FileHandler back to summary

FileHandler	back to summary
public FileHandler(String pattern, int limit, int count) throws IOException Initialize a `FileHandler` to write to a set of files. 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. The `FileHandler` is configured based on `LogManager` properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to the limit argument, and the file count is set to the given count argument. The count must be at least 1. 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 Exceptions IOException: if there are IO problems opening the files. IllegalArgumentException: if `limit < 0`, or `count < 1`. if pattern is an empty string

public FileHandler(String pattern, int limit, int count) throws IOException

Initialize a FileHandler to write to a set of files. 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.

The count must be at least 1.

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

Exceptions

IOException:

if there are IO problems opening the files.

IllegalArgumentException:

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

FileHandler back to summary

FileHandler	back to summary
public FileHandler(String pattern, int limit, int count, boolean append) throws IOException Initialize a `FileHandler` 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. The `FileHandler` is configured based on `LogManager` properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to the limit argument, and the file count is set to the given count argument, and the append mode is set to the given `append` argument. The count must be at least 1. 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 FileHandler(String pattern, int limit, int count, boolean append) throws IOException

Initialize a FileHandler 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.

The count must be at least 1.

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

FileHandler back to summary

FileHandler	back to summary
public FileHandler(String pattern, long limit, int count, boolean append) throws IOException Initialize a `FileHandler` 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. The `FileHandler` is configured based on `LogManager` properties (or their default values) except that the given pattern argument is used as the filename pattern, the file limit is set to the limit argument, and the file count is set to the given count argument, and the append mode is set to the given `append` argument. The count must be at least 1. Parameters pattern:String the pattern for naming the output file limit:long 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 Since 9

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

The count must be at least 1.

Parameters

pattern:String: the pattern for naming the output file
limit:long: 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

Since

Method Detail

close	back to summary
public synchronized void close() Overrides java.util.logging.StreamHandler.close. Close all the files. Annotations @Override

back to summary

public synchronized void close()

Overrides java.util.logging.StreamHandler.close.

Close all the files.

Annotations

@Override

configure	back to summary
private void configure() Configure a FileHandler from LogManager properties and/or default values as specified in the class javadoc.

generate	back to summary
private File generate(String pattern, int generation, int unique) throws IOException Generate a file based on a user-supplied pattern, generation number, and an integer uniqueness suffix Parameters pattern:String the pattern for naming the output file generation:int the generation number to distinguish rotated logs unique:int a unique number to resolve conflicts Returns:File the generated File Exceptions IOException: if an I/O error occurs

generate

back to summary

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

Generate a file based on a user-supplied pattern, generation number, and an integer uniqueness suffix

Parameters

pattern:String: the pattern for naming the output file
generation:int: the generation number to distinguish rotated logs
unique:int: a unique number to resolve conflicts

Returns:File

the generated File

Exceptions

IOException:: if an I/O error occurs

generate	back to summary
pack-priv static File generate(String pat, int count, int generation, int unique) throws IOException

isParentWritable	back to summary
private boolean isParentWritable(Path path)

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

openFiles	back to summary
private void openFiles() throws IOException Open the set of output files, based on the configured instance variables.

publish back to summary

publish	back to summary
public void publish(LogRecord record) Overrides java.util.logging.StreamHandler.publish. Format and publish a `LogRecord`. Parameters record:LogRecord description of the log event. A null record is silently ignored and is not published Annotations @Override

public void publish(LogRecord record)

Overrides java.util.logging.StreamHandler.publish.

Format and publish a LogRecord.

Parameters

record:LogRecord: description of the log event. A null record is silently ignored and is not published

Annotations

@Override

rotate	back to summary
private synchronized void rotate() Rotate the set of output files

synchronousPostWriteHook	back to summary
pack-priv void synchronousPostWriteHook() Overrides java.util.logging.StreamHandler.synchronousPostWriteHook. Doc from java.util.logging.StreamHandler.synchronousPostWriteHook. Overridden by other handlers in this package to facilitate synchronous post-write behaviour. If other handlers need similar functionality, it might be feasible to make this method protected (see JDK-8349206), but please find a better name if you do ;). Annotations @Override

synchronousPostWriteHook

back to summary

pack-priv void synchronousPostWriteHook()

Overrides java.util.logging.StreamHandler.synchronousPostWriteHook.

Doc from java.util.logging.StreamHandler.synchronousPostWriteHook.

Overridden by other handlers in this package to facilitate synchronous post-write behaviour. If other handlers need similar functionality, it might be feasible to make this method protected (see JDK-8349206), but please find a better name if you do ;).

Annotations

@Override

java.util.logging back to summary

private Class FileHandler.InitializationErrorManager

Class Inheritance

extends ErrorManager

java.lang.Object
java.util.logging.ErrorManager
java.util.logging.FileHandler.InitializationErrorManager

Field Summary

Modifier and Type	Field and Description
pack-priv Exception	lastException

Inherited from java.util.logging.ErrorManager:: CLOSE_FAILURE FLUSH_FAILURE FORMAT_FAILURE GENERIC_FAILURE OPEN_FAILURE WRITE_FAILURE

Constructor Summary

Access	Constructor and Description
private	InitializationErrorManager()

Method Summary

Modifier and Type	Method and Description
public void	error(String msg, Exception ex, int code) Overrides java.util.logging.ErrorManager.error. The error method is called when a Handler failure occurs.

Field Detail

lastException	back to summary
pack-priv Exception lastException

Constructor Detail

InitializationErrorManager	back to summary
private InitializationErrorManager()

Method Detail

error	back to summary
public void error(String msg, Exception ex, int code) Overrides java.util.logging.ErrorManager.error. Doc from java.util.logging.ErrorManager.error. The error method is called when a Handler failure occurs. This method may be overridden in subclasses. The default behavior in this base class is that the first call is reported to System.err, and subsequent calls are ignored. Annotations @Override

error

back to summary

public void error(String msg, Exception ex, int code)

Overrides java.util.logging.ErrorManager.error.

Doc from java.util.logging.ErrorManager.error.

The error method is called when a Handler failure occurs.

This method may be overridden in subclasses. The default behavior in this base class is that the first call is reported to System.err, and subsequent calls are ignored.

Annotations

@Override

java.util.logging back to summary

private final Class FileHandler.MeteredStream

Class Inheritance

extends OutputStream

java.lang.Object
java.io.OutputStream
java.util.logging.FileHandler.MeteredStream

A metered stream is a subclass of OutputStream that (a) forwards all its output to a target stream (b) keeps track of how many bytes have been written

Field Summary

Modifier and Type	Field and Description
pack-priv final OutputStream	out
pack-priv long	written

Constructor Summary

Access	Constructor and Description
pack-priv	MeteredStream(OutputStream out, long written)

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 void	flush() Overrides java.io.OutputStream.flush. Implements java.io.Flushable.flush. Flushes this output stream and forces any buffered output bytes to be written out.
public void	write(int b) Implements abstract java.io.OutputStream.write. Writes the specified byte to this output stream.
public void	write(byte[] buff) Overrides java.io.OutputStream.write. Writes `b.length` bytes from the specified byte array to this output stream.
public void	write(byte[] buff, int off, int len) Overrides java.io.OutputStream.write. Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.

Inherited from java.io.OutputStream:: nullOutputStream

Field Detail

out	back to summary
pack-priv final OutputStream out

written	back to summary
pack-priv long written

Constructor Detail

MeteredStream	back to summary
pack-priv MeteredStream(OutputStream out, long written)

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.

flush back to summary

flush	back to summary
public void flush() throws IOException Overrides java.io.OutputStream.flush. Implements java.io.Flushable.flush. Doc from java.io.OutputStream.flush. Flushes this output stream and forces any buffered output bytes to be written out. The general contract of `flush` is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination. If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void flush() throws IOException

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Doc from java.io.OutputStream.flush.

Flushes this output stream and forces any buffered output bytes to be written out. The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination.

If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

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. Annotations @Override 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.

Annotations

@Override

Exceptions

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

write back to summary

write	back to summary
public void write(byte[] buff) throws IOException Overrides java.io.OutputStream.write. Doc from java.io.OutputStream.write. Writes `b.length` bytes from the specified byte array to this output stream. The general contract for `write(b)` is that it should have exactly the same effect as the call `write(b, 0, b.length)`. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void write(byte[] buff) throws IOException

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

write back to summary

write	back to summary
public void write(byte[] buff, int off, int len) throws IOException Overrides java.io.OutputStream.write. Doc from java.io.OutputStream.write. Writes `len` bytes from the specified byte array starting at offset `off` to this output stream. The general contract for `write(b, off, len)` is that some of the bytes in the array `b` are written to the output stream in order; element `b[off]` is the first byte written and `b[off+len-1]` is the last byte written by this operation. If `b` is `null`, a `NullPointerException` is thrown. If `off` is negative, or `len` is negative, or `off+len` is greater than the length of the array `b`, then an `IndexOutOfBoundsException` is thrown. Annotations @Override Exceptions IOException: if an I/O error occurs. In particular, an `IOException` is thrown if the output stream is closed.

public void write(byte[] buff, int off, int len) throws IOException

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs. In particular, an IOException is thrown if the output stream is closed.

public Class FileHandler

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class FileHandler.InitializationErrorManager

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class FileHandler.MeteredStream

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail