java.util.logging
Class FileHandler

java.lang.Object
  java.util.logging.Handler
      java.util.logging.StreamHandler
          java.util.logging.FileHandler

public class FileHandler
extends StreamHandler

A FileHandler is a Handler that writes logging events to one or more files.

If multiple files are used, when a given amount of data has been written to one file, this file is closed, and the next file is opened. The names of these files are generated by the given name pattern, see below for details. When all the files have all been filled the Handler returns to the first one and goes through the set again.

FileHandler defines the following configuration properties, which are read by the LogManager on initialization. If the properties have not been specified then defaults will be used. The properties and defaults are as follows:

• java.util.logging.FileHandler.append - If true then this FileHandler appends to a file's existing content, if false it overwrites it. Default is false.
• java.util.logging.FileHandler.count - the number of output files to rotate. Default is 1.
• java.util.logging.FileHandler.filter - the name of the Filter class. No Filter is used by default.
• java.util.logging.FileHandler.formatter - the name of the Formatter class. Default is java.util.logging.XMLFormatter.
• java.util.logging.FileHandler.encoding - the name of the character set encoding. Default is the encoding used by the current platform.
• java.util.logging.FileHandler.level - the log level for this Handler. Default is Level.ALL.
• java.util.logging.FileHandler.limit - the limit at which no more bytes should be written to the current file. Default is no limit.
• java.util.logging.FileHandler.pattern - the pattern for the name of log files. Default is "%h/java%u.log".

The name pattern is a String that can contain some of the following sub-strings, which will be replaced to generate the output file names:

• "/" represents the local path separator
• "%g" represents the generation number used to enumerate log files
• "%h" represents the home directory of the current user, which is specified by the "user.home" system property
• "%t" represents the system's temporary directory
• "%u" represents a unique number added to the file name if the original file required is in use
• "%%" represents the percent sign character '%'

The generation numbers, denoted by "%g" in the filename pattern will be created in ascending numerical order from 0, i.e. 0,1,2,3... If "%g" was not present in the pattern and more than one file is being used then a dot and a generation number is appended to the filename at the end. This is equivalent to appending ".%g" to the pattern.

The unique identifier, denoted by "%u" in the filename pattern will always be 0 unless the FileHandler is unable to open the file. In that case 1 is tried, then 2, and so on until a file is found that can be opened. If "%u" was not present in the pattern but a unique number is required then a dot and a unique number is added to the end of the filename, equivalent to appending ".%u" to the pattern.

Constructor Summary

FileHandler()
Construct a FileHandler using LogManager properties or their default value

FileHandler(String pattern)
Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to zero(no limit), and the file count is set to one, other configuration using LogManager properties or their default value This handler write to only one file and no amount limit.

FileHandler(String pattern, boolean append)
Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to zero(i.e. no limit applies), the file count is initialized to one, and the value of append becomes the new instance's append mode.

FileHandler(String pattern, int limit, int count)
Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to given limit argument, and the file count is set to given count argument, other configuration using LogManager properties or their default value This handler is configured to write to a rotating set of count files, when the limit of bytes has been written to one output file, another file will be opened instead.

FileHandler(String pattern, int limit, int count, boolean append)
Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to given limit argument, the file count is set to given count argument, and the append mode is set to given append argument, other configuration using LogManager properties or their default value This handler is configured to write to a rotating set of count files, when the limit of bytes has been written to one output file, another file will be opened instead.

Method Summary

void	close() Flush and close all opened files.
void	publish(LogRecord record) Publish a LogRecord

Methods inherited from class java.util.logging.StreamHandler

flush, isLoggable, setEncoding, setOutputStream

Methods inherited from class java.util.logging.Handler

getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setErrorManager, setFilter, setFormatter, setLevel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileHandler

public FileHandler()
            throws IOException

Construct a FileHandler using LogManager properties or their default value

Throws:

IOException - if any IO exception happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

FileHandler

public FileHandler(String pattern)
            throws IOException

Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to zero(no limit), and the file count is set to one, other configuration using LogManager properties or their default value This handler write to only one file and no amount limit.

Parameters:

pattern - the name pattern of output file

Throws:

IOException - if any IO exception happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

NullPointerException - if the pattern is null.

IllegalArgumentException - if the pattern is empty.

FileHandler

public FileHandler(String pattern,
                   boolean append)
            throws IOException

Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to zero(i.e. no limit applies), the file count is initialized to one, and the value of append becomes the new instance's append mode. Other configuration is done using LogManager properties. This handler write to only one file and no amount limit.

Parameters:

pattern - the name pattern of output file

append - the append mode

Throws:

IOException - if any IO exception happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

NullPointerException - if the pattern is null.

IllegalArgumentException - if the pattern is empty.

FileHandler

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

Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to given limit argument, and the file count is set to given count argument, other configuration using LogManager properties or their default value This handler is configured to write to a rotating set of count files, when the limit of bytes has been written to one output file, another file will be opened instead.

Parameters:

pattern - the name pattern of output file

limit - the data amount limit in bytes of one output file, cannot less than one

count - the maximum number of files can be used, cannot less than one

Throws:

IOException - if any IO exception happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

NullPointerException - if pattern is null.

IllegalArgumentException - if count<1, or limit<0

FileHandler

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

Construct a FileHandler, the given name pattern is used as output filename, the file limit is set to given limit argument, the file count is set to given count argument, and the append mode is set to given append argument, other configuration using LogManager properties or their default value This handler is configured to write to a rotating set of count files, when the limit of bytes has been written to one output file, another file will be opened instead.

Parameters:

pattern - the name pattern of output file

limit - the data amount limit in bytes of one output file, cannot less than one

count - the maximum number of files can be used, cannot less than one

append - the append mode

Throws:

IOException - if any IO exception happened

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

NullPointerException - if pattern is null.

IllegalArgumentException - if count<1, or limit<0

Method Detail

close

public void close()

Flush and close all opened files.

Overrides:

close in class StreamHandler

Throws:

SecurityException - if security manager exists and it determines that caller does not have the required permissions to control this handler, required permissions include LogPermission("control") and other permission like FilePermission("write"), etc.

publish

public void publish(LogRecord record)

Publish a LogRecord

Overrides:

publish in class StreamHandler

Parameters:

record - the log record to be published