Index: src/main/java/java/util/logging/FileHandler.java =================================================================== --- src/main/java/java/util/logging/FileHandler.java (revision 537769) +++ src/main/java/java/util/logging/FileHandler.java (working copy) @@ -32,74 +32,75 @@ import org.apache.harmony.logging.internal.nls.Messages; /** - * A Handler writes description of logging event into a specified - * file or a rotating set of files. + * A FileHandler is a Handler that writes logging events to one + * or more files. + * *

- * If a set of files are used, when a given amount of data has been written to - * one file, this file is closed, and another file is opened. The name of these - * files are generated by given name pattern, see below for details. + * 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. *

- *

- * By default the IO buffering mechanism is enabled, but when each log record is - * complete, it is flushed out. - *

+ * *

- * XMLFormatter is default formatter for FileHandler. - *

- *

- * MemoryHandler will read following LogManager - * properties for initialization, if given properties are not defined or has - * invalid values, default value will be used. + * 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: *

*

+ * *

- * Name pattern is a string that may includes some special sub-strings, which - * will be replaced to generate output files: + * 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: *

*

- * Normally, the generation numbers are not larger than 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 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 "%u" unique field is used to avoid conflicts and 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 unique IDs for avoiding conflicts is only guaranteed to - * work reliably when using a local disk file system. + * 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. *

- * */ public class FileHandler extends StreamHandler {