java.util.logging
Class FileHandler
A
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.
FileHandler()- Constructs a
FileHandler, taking all property values
from the current 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.
|
void | publish(LogRecord record)- Publishes a
LogRecord to an appropriate sink,
provided the record passes all tests for being loggable.
|
close, flush, getEncoding, getErrorManager, getFilter, getFormatter, getLevel, isLoggable, publish, reportError, setEncoding, setErrorManager, setFilter, setFormatter, setLevel |
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait |
FileHandler
public FileHandler()
throws IOException,
SecurityException Constructs a
FileHandler, taking all property values
from the current
LogManager configuration.
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
public FileHandler(String pattern,
int limit,
int count,
boolean append)
throws IOException,
SecurityException 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. All other property values are
taken from the current
LogManager
configuration.
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 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).
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.
publish
public void publish(LogRecord record)
Publishes a
LogRecord to an appropriate sink,
provided the record passes all tests for being loggable. The
Handler will localize the message of the log
record and substitute any message parameters.
Most applications do not need to call this method directly.
Instead, they will use use a
Logger, which will
create LogRecords and distribute them to registered handlers.
In case of an I/O failure, the
ErrorManager
of this
Handler will be informed, but the caller
of this method will not receive an exception.
- publish in interface StreamHandler
record - the log event to be published.
FileHandler.java -- a class for publishing log messages to log files
Copyright (C) 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.