java.util.logging
public class FileHandler extends StreamHandler
FileHandler publishes log records to a set of log
files. A maximum file size can be specified; as soon as a log file
reaches the size limit, it is closed and the next file in the set
is taken.
Configuration: Values of the subsequent
LogManager properties are taken into consideration
when a FileHandler is initialized. If a property is
not defined, or if it has an invalid value, a default is taken
without an exception being thrown.
java.util.FileHandler.level - specifies
the initial severity level threshold. Default value:
Level.ALL.java.util.FileHandler.filter - specifies
the name of a Filter class. Default value: No Filter.java.util.FileHandler.formatter - specifies
the name of a Formatter class. Default value:
java.util.logging.XMLFormatter.java.util.FileHandler.encoding - specifies
the name of the character encoding. Default value:
the default platform encoding.java.util.FileHandler.limit - specifies the number
of bytes a log file is approximately allowed to reach before it
is closed and the handler switches to the next file in the
rotating set. A value of zero means that files can grow
without limit. Default value: 0 (unlimited growth).java.util.FileHandler.count - specifies the number
of log files through which this handler cycles. Default value:
1.java.util.FileHandler.pattern - specifies a
pattern for the location and name of the produced log files.
See the section on file name
patterns for details. Default value:
"%h/java%u.log".java.util.FileHandler.append - specifies
whether the handler will append log records to existing
files, or whether the handler will clear log files
upon switching to them. Default value: false,
indicating that files will be cleared.File Name Patterns: The name and location and log files are specified with pattern strings. The handler will replace the following character sequences when opening log files:
/ - replaced by the platform-specific path name
separator. This value is taken from the system property
file.separator.%t - replaced by the platform-specific location of
the directory intended for temporary files. This value is
taken from the system property java.io.tmpdir.%h - replaced by the location of the home
directory of the current user. This value is taken from the
system property user.home.%g - replaced by a generation number for
distinguisthing the individual items in the rotating set
of log files. The generation number cycles through the
sequence 0, 1, ..., count - 1.%u - replaced by a unique number for
distinguisthing the output files of several concurrently
running processes. The FileHandler starts
with 0 when it tries to open a log file. If the file
cannot be opened because it is currently in use,
the unique number is incremented by one and opening
is tried again. These steps are repeated until the
opening operation succeeds.
FIXME: Is the following correct? Please review. The unique number is determined for each log file individually when it is opened upon switching to the next file. Therefore, it is not correct to assume that all log files in a rotating set bear the same unique number.
FIXME: The Javadoc for the Sun reference implementation says: "Note that the use of unique ids to avoid conflicts is only guaranteed to work reliably when using a local disk file system." Why? This needs to be mentioned as well, in case the reviewers decide the statement is true. Otherwise, file a bug report with Sun.
%% - replaced by a single percent sign.If the pattern string does not contain %g and
count is greater than one, the handler will append
the string .%g to the specified pattern.
If the handler attempts to open a log file, this log file
is being used at the time of the attempt, and the pattern string
does not contain %u, the handler will append
the string .%u to the specified pattern. This
step is performed after any generation number has been
appended.
Examples for the GNU platform:
%h/java%u.log will lead to a single log file
/home/janet/java0.log, assuming count
equals 1, the user's home directory is
/home/janet, and the attempt to open the file
succeeds.%h/java%u.log will lead to three log files
/home/janet/java0.log.0,
/home/janet/java0.log.1, and
/home/janet/java0.log.2,
assuming count equals 3, the user's home
directory is /home/janet, and all attempts
to open files succeed.%h/java%u.log will lead to three log files
/home/janet/java0.log.0,
/home/janet/java1.log.1, and
/home/janet/java0.log.2,
assuming count equals 3, the user's home
directory is /home/janet, and the attempt
to open /home/janet/java0.log.1 fails.| Constructor Summary | |
|---|---|
| FileHandler()
Constructs a FileHandler, taking all property values
from the current {@link LogManager LogManager} configuration.
| |
| FileHandler(String pattern) | |
| FileHandler(String pattern, boolean append) | |
| FileHandler(String pattern, int limit, int count) | |
| FileHandler(String pattern, int limit, int count, boolean append)
Constructs a FileHandler given the pattern for the
location and name of the produced log files, the size limit, the
number of log files thorough which the handler will rotate, and
the append property. | |
| Method Summary | |
|---|---|
| void | publish(LogRecord record) |
FileHandler, taking all property values
from the current {@link LogManager LogManager} configuration.
Throws: java.io.IOException FIXME: The Sun Javadoc says: "if there are IO problems opening the files." This conflicts with the general principle that configuration errors do not prohibit construction. Needs review. SecurityException if a security manager exists and the caller is not granted the permission to control the logging infrastructure.
FileHandler given the pattern for the
location and name of the produced log files, the size limit, the
number of log files thorough which the handler will rotate, and
the append property. All other property values are
taken from the current {@link LogManager LogManager}
configuration.
Parameters: pattern The pattern for the location and name of the
produced log files. See the section on file name patterns for details.
If pattern is null, the value is
taken from the {@link LogManager LogManager} configuration
property
java.util.logging.FileHandler.pattern.
However, this is a pecularity of the GNU implementation,
and Sun's API specification does not mention what behavior
is to be expected for null. Therefore,
applications should not rely on this feature.
limit specifies the number of bytes a log file is
approximately allowed to reach before it is closed and the
handler switches to the next file in the rotating set. A
value of zero means that files can grow without limit.
count specifies the number of log files through which this
handler cycles.
append specifies whether the handler will append log
records to existing files (true), or whether the
handler will clear log files upon switching to them
(false).
Throws: java.io.IOException FIXME: The Sun Javadoc says: "if
there are IO problems opening the files." This conflicts
with the general principle that configuration errors do
not prohibit construction. Needs review.
SecurityException if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.
FIXME: This seems in contrast to all other handler
constructors -- verify this by running tests against
the Sun reference implementation.