public class FileHandler extends StreamHandler
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
(defaults to Level.ALL
). Filter
class to use (defaults to no Filter
). Formatter
class to use (defaults to java.util.logging.XMLFormatter
) For example, the properties for FileHandler
would be:
For a custom handler, e.g. com.foo.MyHandler, the properties would be:
A pattern consists of a string that includes the following special components that will be replaced at runtime:
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.
Constructor | Description |
---|---|
FileHandler() |
Construct a default FileHandler . |
FileHandler |
Initialize a FileHandler to write to the given filename. |
FileHandler |
Initialize a FileHandler to write to the given filename, with optional append. |
FileHandler |
Initialize a FileHandler to write to a set of files. |
FileHandler |
Initialize a FileHandler to write to a set of files with optional append. |
FileHandler |
Initialize a FileHandler to write to a set of files with optional append. |
flush, isLoggable, setEncoding, setOutputStream
getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setErrorManager, setFilter, setFormatter, setLevel
public FileHandler() throws IOException, SecurityException
FileHandler
. This will be configured entirely from LogManager
properties (or their default values).IOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control"))
.NullPointerException
- if pattern property is an empty String.public FileHandler(String pattern) throws IOException, SecurityException
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.
pattern
- the name of the output fileIOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.IllegalArgumentException
- if pattern is an empty stringpublic FileHandler(String pattern, boolean append) throws IOException, SecurityException
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.
pattern
- the name of the output fileappend
- specifies append modeIOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.IllegalArgumentException
- if pattern is an empty stringpublic FileHandler(String pattern, int limit, int count) throws IOException, SecurityException
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.
pattern
- the pattern for naming the output filelimit
- the maximum number of bytes to write to any one filecount
- the number of files to useIOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.IllegalArgumentException
- if limit < 0
, or count < 1
.IllegalArgumentException
- if pattern is an empty stringpublic FileHandler(String pattern, int limit, int count, boolean append) throws IOException, SecurityException
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.
pattern
- the pattern for naming the output filelimit
- the maximum number of bytes to write to any one filecount
- the number of files to useappend
- specifies append modeIOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.IllegalArgumentException
- if limit < 0
, or count < 1
.IllegalArgumentException
- if pattern is an empty stringpublic FileHandler(String pattern, long limit, int count, boolean append) throws IOException
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.
pattern
- the pattern for naming the output filelimit
- the maximum number of bytes to write to any one filecount
- the number of files to useappend
- specifies append modeIOException
- if there are IO problems opening the files.SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.IllegalArgumentException
- if limit < 0
, or count < 1
.IllegalArgumentException
- if pattern is an empty stringpublic void publish(LogRecord record)
LogRecord
.publish
in class StreamHandler
record
- description of the log event. A null record is silently ignored and is not publishedpublic void close() throws SecurityException
close
in class StreamHandler
SecurityException
- if a security manager exists and if the caller does not have LoggingPermission("control")
.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.logging/java/util/logging/FileHandler.html