This
Handler subclass formats
LogRecord objects and outputs the resulting
strings to a file or to a rotating set of files. Arguments passed to
the FileHandler( ) constructor specify which file
or files are used, and how they are used. The arguments are optional,
and if they are not specified, defaults are obtained through
LogManager.getProperty( ) as described below. The
constructor arguments are:
- pattern
-
A string containing substitution characters that describes one or
more files to use. The substitutions performed to convert this
pattern to a filename are described below.
- limit
-
An approximate maximum file size for the log file, or 0 for no limit.
If count is set to greater than one, then
when a log file reaches this maximum, FileHandler
closes it, renames it, and then starts a new log with the original
filename.
- count
-
When limit is set to be nonzero, this
arguemnt specifies the number of old log files to retain.
- append
-
TRue if the FileHandler should
append to log messages already in the named file, or
false if it should overwrite the file.
The pattern argument is the most important
of these: it specifies which file or files the
FileHandler will write to.
FileHandler performs the following substitutions
on the specified pattern to convert it to a filename:
For
|
Substitute
|
---|
/
|
The directory separator character for the platform. This means that
you can always use a forward slash in your patterns, even on Windows
filesystems that use backward slashes.
|
%%
|
A single literal percent sign.
|
%h
|
The user's home directory: the value of the system
property "user.home".
|
%t
|
The temporary directory for the system.
|
%u
|
A unique number to be used to distinguish this log file from other
log files with the same pattern (this may be necessary when multiple
Java programs are creating logs at the same time).
|
%g
|
The "generation number" of old log
files when the limit argument is nonzero
and the count argument is greater than
one. FileHandler always writes log records into a
file in which %g is replaced by 0. But when that file fills up, it is
closed and renamed with the 0 replaced by a 1. Older files are
similarly renamed, with their generation number being incremented.
When the number of log files reaches the number specifed by
count, then the oldest file is deleted to
make room for the new one.
|
When a FileHandler is created, the
LogManager.getProperty( ) method is used to obtain
defaults for any unspecified constructor arguments, and also to
obtian initial values for the various properties inherited from
Handler. The table below lists these arguments and
properties, the value passed to getProperty( ),
and the default value used if getProperty( )
returns null. See Handler for
further details.
Property or argument
|
LogManager property name
|
Default
|
---|
level
|
java.util.logging.FileHandler.level
|
Level.ALL
|
filter
|
java.util.logging.FileHandler.filter
|
null
|
formatter
|
java.util.logging.FileHandler.formatter
|
XMLFormatter
|
encoding
|
java.util.logging.FileHandler.encoding
|
platform default
|
pattern
|
java.util.logging.FileHandler.pattern
|
%h/java%u.log
|
limit
|
java.util.logging.FileHandler.limit
|
0 (no limit)
|
count
|
java.util.logging.FileHandler.count
|
1
|
append
|
java.util.logging.FileHandler.append
|
false
|

public class FileHandler extends StreamHandler {
// Public Constructors
public FileHandler( ) throws java.io.IOException, SecurityException;
public FileHandler(String pattern) throws java.io.IOException, SecurityException;
public FileHandler(String pattern, boolean append)
throws java.io.IOException, SecurityException;
public FileHandler(String pattern, int limit, int count)
throws java.io.IOException, SecurityException;
public FileHandler(String pattern, int limit, int count,
boolean append) throws java.io.IOException, SecurityException;
// Public Methods Overriding StreamHandler
public void close( ) throws SecurityException; synchronized
public void publish(LogRecord record); synchronized
}