Summary: Ctors | Methods | Inherited Methods | [Expand All]

Since: API Level 1

public class

FileHandler

extends StreamHandler

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

Class Overview

A FileHandler writes logging records into a specified file or a rotating set of files.

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

By default, the I/O buffering mechanism is enabled, but when each log record is complete, it is flushed out.

XMLFormatter is the default formatter for FileHandler.

FileHandler reads the following LogManager properties for initialization; if a property is not defined or has an invalid value, a default value is used.

java.util.logging.FileHandler.append specifies whether this FileHandler should append onto existing files, defaults to false.
java.util.logging.FileHandler.count specifies how many output files to rotate, defaults to 1.
java.util.logging.FileHandler.filter specifies the Filter class name, defaults to no Filter.
java.util.logging.FileHandler.formatter specifies the Formatter class, defaults to java.util.logging.XMLFormatter.
java.util.logging.FileHandler.encoding specifies the character set encoding name, defaults to the default platform encoding.
java.util.logging.FileHandler.level specifies the level for this Handler, defaults to Level.ALL.
java.util.logging.FileHandler.limit specifies the maximum number of bytes to write to any one file, defaults to zero, which means no limit.
java.util.logging.FileHandler.pattern specifies name pattern for the output files. See below for details. Defaults to "%h/java%u.log".

Name pattern is a string that may include some special substrings, which will be replaced to generate output files:

"/" represents the local pathname separator
"%g" represents the generation number to distinguish rotated logs
"%h" represents the home directory of the current user, which is specified by "user.home" system property
"%t" represents the system's temporary directory
"%u" represents a unique number to resolve conflicts
"%%" represents the percent sign character '%'

Normally, the generation numbers are not larger than the given file count and follow the sequence 0, 1, 2.... If the file count is larger than one, but the generation field("%g") has not been specified in the pattern, then the generation number after a dot will be added to the end of the file name.

The "%u" unique field is used to avoid conflicts and is set to 0 at first. If one FileHandler tries to open the filename which is currently in use by another process, it will repeatedly increment the unique number field and try again. If the "%u" component has not been included in the file name pattern and some contention on a file does occur, then a unique numerical value will be added to the end of the filename in question immediately to the right of a dot. The generation of unique IDs for avoiding conflicts is only guaranteed to work reliably when using a local disk file system.

Summary

Public Constructors
	FileHandler() Construct a `FileHandler` using `LogManager` properties or their default value.
	FileHandler(String pattern) Constructs a new `FileHandler`.
	FileHandler(String pattern, boolean append) Construct a new `FileHandler`.
	FileHandler(String pattern, int limit, int count) Construct a new `FileHandler`.
	FileHandler(String pattern, int limit, int count, boolean append) Construct a new `FileHandler`.

Public Methods
void	close() Flushes and closes all opened files.
synchronized void	publish(LogRecord record) Publish a `LogRecord`.

[Expand]

Inherited Methods

From class java.util.logging.StreamHandler

From class java.util.logging.Handler

abstract void	close() Closes this handler.
abstract void	flush() Flushes any buffered output.
String	getEncoding() Gets the character encoding used by this handler, `null` for default encoding.
ErrorManager	getErrorManager() Gets the error manager used by this handler to report errors during logging.
Filter	getFilter() Gets the filter used by this handler.
Formatter	getFormatter() Gets the formatter used by this handler to format the logging messages.
Level	getLevel() Gets the logging level of this handler, records with levels lower than this value will be dropped.
boolean	isLoggable(LogRecord record) Determines whether the supplied log record needs to be logged.
abstract void	publish(LogRecord record) Accepts a logging request and sends it to the the target.
void	reportError(String msg, Exception ex, int code) Reports an error to the error manager associated with this handler, `ErrorManager` is used for that purpose.
void	setEncoding(String encoding) Sets the character encoding used by this handler, `null` indicates a default encoding.
void	setErrorManager(ErrorManager em) Sets the error manager for this handler.
void	setFilter(Filter newFilter) Sets the filter to be used by this handler.
void	setFormatter(Formatter newFormatter) Sets the formatter to be used by this handler.
void	setLevel(Level newLevel) Sets the logging level of the messages logged by this handler, levels lower than this value will be dropped.

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Called before the object's memory is reclaimed by the VM.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

Public Constructors

public FileHandler ()

Since: API Level 1

Construct a FileHandler using LogManager properties or their default value.

Throws

IOException	if any I/O error occurs.
SecurityException	if a security manager exists and it determines that the caller does not have the required permissions to control this handler; required permissions include `LogPermission("control")`, `FilePermission("write")` etc.

public FileHandler (String pattern)

Since: API Level 1

Constructs a new FileHandler. The given name pattern is used as output filename, the file limit is set to zero (no limit), the file count is set to one; the remaining configuration is done using LogManager properties or their default values. This handler writes to only one file with no size limit.

Parameters

pattern	the name pattern for the output file.

Throws

IOException	if any I/O error occurs.
SecurityException	if a security manager exists and it determines that the caller does not have the required permissions to control this handler; required permissions include `LogPermission("control")`, `FilePermission("write")` etc.
IllegalArgumentException	if the pattern is empty.
NullPointerException	if the pattern is `null`.

public FileHandler (String pattern, boolean append)

Since: API Level 1

Construct a new FileHandler. The given name pattern is used as output filename, the file limit is set to zero (no limit), the file count is initialized to one and the value of append becomes the new instance's append mode. The remaining configuration is done using LogManager properties. This handler writes to only one file with no size limit.

Parameters

pattern	the name pattern for the output file.
append	the append mode.

Throws

IOException	if any I/O error occurs.
SecurityException	if a security manager exists and it determines that the caller does not have the required permissions to control this handler; required permissions include `LogPermission("control")`, `FilePermission("write")` etc.
IllegalArgumentException	if `pattern` is empty.
NullPointerException	if `pattern` is `null`.

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

Since: API Level 1

Construct a new FileHandler. The given name pattern is used as output filename, the maximum file size is set to limit and the file count is initialized to count. The remaining configuration is done using LogManager properties. 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 for the output file.
limit	the data amount limit in bytes of one output file, can not be negative.
count	the maximum number of files to use, can not be less than one.

Throws

IOException	if any I/O error occurs.
SecurityException	if a security manager exists and it determines that the caller does not have the required permissions to control this handler; required permissions include `LogPermission("control")`, `FilePermission("write")` etc.
IllegalArgumentException	if `pattern` is empty, `limit < 0` or `count < 1`.
NullPointerException	if `pattern` is `null`.

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

Since: API Level 1

Construct a new FileHandler. The given name pattern is used as output filename, the maximum file size is set to limit, the file count is initialized to count and the append mode is set to append. The remaining configuration is done using LogManager properties. 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 for the output file.
limit	the data amount limit in bytes of one output file, can not be negative.
count	the maximum number of files to use, can not be less than one.
append	the append mode.

Throws

IOException	if any I/O error occurs.
SecurityException	if a security manager exists and it determines that the caller does not have the required permissions to control this handler; required permissions include `LogPermission("control")`, `FilePermission("write")` etc.
IllegalArgumentException	if `pattern` is empty, `limit < 0` or `count < 1`.
NullPointerException	if `pattern` is `null`.

Public Methods

public void close ()

Since: API Level 1

Flushes and closes all opened files.

Throws

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

public synchronized void publish (LogRecord record)

Since: API Level 1

Publish a LogRecord.

Parameters

record	the log record to publish.

Interfaces

Classes

FileHandler

Class Overview

Summary

Public Constructors

public FileHandler ()

Throws

public FileHandler (String pattern)

Parameters

Throws

public FileHandler (String pattern, boolean append)

Parameters

Throws

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

Parameters

Throws

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

Parameters

Throws

Public Methods

public void close ()

Throws

public synchronized void publish (LogRecord record)

Parameters