Overview  Package   Class  Use  Deprecated  Index
Home >> All >> java >> util >> [ logging overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

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 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.

---

Nested Class Summary
private  class	FileHandler.ostr           An output stream that tracks the number of bytes written to it.

 

Field Summary
private  boolean	append           Indicates whether the handler will append log records to existing files (true), or whether the handler will clear log files upon switching to them (false).
private  int	count           The number of log files through which this handler cycles.
private  int	limit           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.
private  java.util.LinkedList	logFiles           A linked list of files we are, or have written to.
private  java.lang.String	pattern           The pattern for the location and name of the produced log files.
(package private)  long	written           The number of bytes that have currently been written to the stream.

 

Fields inherited from class java.util.logging.StreamHandler

 

Fields inherited from class java.util.logging.Handler

encoding, errorManager, filter, formatter, level

 

Constructor Summary

FileHandler()           Constructs a FileHandler, taking all property values from the current LogManager configuration.

FileHandler(java.lang.String pattern)

FileHandler(java.lang.String pattern, boolean append)

FileHandler(java.lang.String pattern, int limit, int count)

FileHandler(java.lang.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
private  java.io.OutputStream	createFileStream(java.lang.String pattern, int limit, int count, boolean append, int generation)
private static boolean	has(java.lang.String pattern, char escape)           Tell if pattern contains the pattern sequence with character escape.
void	publish(LogRecord record)           Publishes a LogRecord to the associated output stream, provided the record passes all tests for being loggable.
private static java.lang.String	replaceFileNameEscapes(java.lang.String pattern, int generation, int uniqueNumber, int count)           Replaces the substrings "/" by the value of the system property "file.separator", "%t" by the value of the system property "java.io.tmpdir", "%h" by the value of the system property "user.home", "%g" by the value of generation, "%u" by the value of uniqueNumber, and "%%" by a single percent character.
private  void	rotate()           Rotates the current log files, possibly removing one if we exceed the file count.

 

Methods inherited from class java.util.logging.StreamHandler

close, 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

 

Field Detail

limit

private final int limit

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

private final int count

The number of log files through which this handler cycles.

---

pattern

private final java.lang.String pattern

The pattern for the location and name of the produced log files. See the section on file name patterns for details.

---

append

private final boolean append

Indicates whether the handler will append log records to existing files (true), or whether the handler will clear log files upon switching to them (false).

---

written

long written

The number of bytes that have currently been written to the stream. Package private for use in inner classes.

---

logFiles

private java.util.LinkedList logFiles

A linked list of files we are, or have written to. The entries are file path strings, kept in the order

Constructor Detail

FileHandler

public FileHandler()
            throws java.io.IOException,
                   java.lang.SecurityException

Constructs a FileHandler, taking all property values from the current LogManager configuration.

---

FileHandler

public FileHandler(java.lang.String pattern)
            throws java.io.IOException,
                   java.lang.SecurityException

---

FileHandler

public FileHandler(java.lang.String pattern,
                   boolean append)
            throws java.io.IOException,
                   java.lang.SecurityException

---

FileHandler

public FileHandler(java.lang.String pattern,
                   int limit,
                   int count)
            throws java.io.IOException,
                   java.lang.SecurityException

---

FileHandler

public FileHandler(java.lang.String pattern,
                   int limit,
                   int count,
                   boolean append)
            throws java.io.IOException,
                   java.lang.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.

Method Detail

createFileStream

private java.io.OutputStream createFileStream(java.lang.String pattern,
                                              int limit,
                                              int count,
                                              boolean append,
                                              int generation)

---

replaceFileNameEscapes

private static java.lang.String replaceFileNameEscapes(java.lang.String pattern,
                                                       int generation,
                                                       int uniqueNumber,
                                                       int count)

Replaces the substrings "/" by the value of the system property "file.separator", "%t" by the value of the system property "java.io.tmpdir", "%h" by the value of the system property "user.home", "%g" by the value of generation, "%u" by the value of uniqueNumber, and "%%" by a single percent character. If pattern does not contain the sequence "%g", the value of generation will be appended to the result.

---

publish

public void publish(LogRecord record)

Description copied from class: StreamHandler

Publishes a LogRecord to the associated output stream, provided the record passes all tests for being loggable. The StreamHandler 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.

If a log record is being published to a StreamHandler that has been closed earlier, the Sun J2SE 1.4 reference can be observed to silently ignore the call. The GNU implementation, however, intentionally behaves differently by informing the ErrorManager associated with this StreamHandler. Since the condition indicates a programming error, the programmer should be informed. It also seems extremely unlikely that any application would depend on the exact behavior in this rather obscure, erroneous case -- especially since the API specification does not prescribe what is supposed to happen.

Overrides:

publish in class StreamHandler

---

rotate

private void rotate()

Rotates the current log files, possibly removing one if we exceed the file count.

---

has

private static boolean has(java.lang.String pattern,
                           char escape)

Tell if pattern contains the pattern sequence with character escape. That is, if escape is 'g', this method returns true if the given pattern contains "%g", and not just the substring "%g" (for example, in the case of "%%g").

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> java >> util >> [ logging overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---