svn commit: r542441 - /harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java

[ap...@apache.org]

Author: apetrenko
Date: Tue May 29 00:26:29 2007
New Revision: 542441

URL: http://svn.apache.org/viewvc?view=rev&rev=542441
Log:
Patch for HARMONY-3980 "[classlib] [logging] Updated Javadoc for java.util.logging.FileHandler"

Modified:
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java?view=diff&rev=542441&r1=542440&r2=542441
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java Tue May 29 00:26:29 2007
@@ -32,74 +32,75 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * A <code>Handler</code> writes description of logging event into a specified
- * file or a rotating set of files.
- * <p>
- * 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.
- * </p>
- * <p>
- * By default the IO buffering mechanism is enabled, but when each log record is
- * complete, it is flushed out.
- * </p>
+ * A <code>FileHandler</code> is a Handler that writes logging events to one
+ * or more files.
+ * 
  * <p>
- * <code>XMLFormatter</code> is default formatter for <code>FileHandler</code>.
+ * 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.
  * </p>
+ * 
  * <p>
- * <code>MemoryHandler</code> will read following <code>LogManager</code>
- * properties for initialization, if given properties are not defined or has
- * invalid values, default value will be used.
+ * <code>FileHandler</code> defines the following configuration properties,
+ * which are read by the <code>LogManager</code> on initialization. If the
+ * properties have not been specified then defaults will be used. The properties
+ * and defaults are as follows:
  * <ul>
- * <li>java.util.logging.FileHandler.level specifies the level for this
- * <code>Handler</code>, defaults to <code>Level.ALL</code>.</li>
- * <li>java.util.logging.FileHandler.filter specifies the <code>Filter</code>
- * class name, defaults to no <code>Filter</code>.</li>
- * <li>java.util.logging.FileHandler.formatter specifies the
- * <code>Formatter</code> class, defaults to
+ * <li>java.util.logging.FileHandler.append - If true then this
+ * <code>FileHandler</code> appends to a file's existing content, if false it
+ * overwrites it. Default is false.</li>
+ * <li>java.util.logging.FileHandler.count - the number of output files to
+ * rotate. Default is 1.</li>
+ * <li>java.util.logging.FileHandler.filter - the name of the
+ * <code>Filter</code> class. No <code>Filter</code> is used by default.</li>
+ * <li>java.util.logging.FileHandler.formatter - the name of the
+ * <code>Formatter</code> class. Default is
  * <code>java.util.logging.XMLFormatter</code>.</li>
- * <li>java.util.logging.FileHandler.encoding specifies the character set
- * encoding name, defaults to the default platform encoding.</li>
- * <li>java.util.logging.FileHandler.limit specifies an maximum bytes to write
- * to any one file, defaults to zero, which means no limit.</li>
- * <li>java.util.logging.FileHandler.count specifies how many output files to
- * rotate, defaults to 1.</li>
- * <li>java.util.logging.FileHandler.pattern specifies name pattern for the
- * output files. See below for details. Defaults to "%h/java%u.log".</li>
- * <li>java.util.logging.FileHandler.append specifies whether this
- * <code>FileHandler</code> should append onto existing files, defaults to
- * false.</li>
+ * <li>java.util.logging.FileHandler.encoding - the name of the character set
+ * encoding. Default is the encoding used by the current platform.</li>
+ * <li>java.util.logging.FileHandler.level - the log level for this
+ * <code>Handler</code>. Default is <code>Level.ALL</code>.</li>
+ * <li>java.util.logging.FileHandler.limit - the limit at which no more bytes
+ * should be written to the current file. Default is no limit.</li>
+ * <li>java.util.logging.FileHandler.pattern - the pattern for the name of log
+ * files. Default is "%h/java%u.log".</li>
  * </ul>
  * </p>
+ * 
  * <p>
- * 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:
  * <ul>
- * <li>"/" represents the local pathname separator</li>
- * <li>"%t" represents the system temporary directory</li>
- * <li>"%h" represents the home directory of current user, which is specified
- * by "user.home" system property</li>
- * <li>"%g" represents the generation number to distinguish rotated logs</li>
- * <li>"%u" represents a unique number to resolve conflicts</li>
- * <li>"%%" represents percent sign character '%'</li>
+ * <li>"/" represents the local path separator</li>
+ * <li>"%g" represents the generation number used to enumerate log files</li>
+ * <li>"%h" represents the home directory of the current user, which is
+ * specified by the "user.home" system property</li>
+ * <li>"%t" represents the system's temporary directory</li>
+ * <li>"%u" represents a unique number added to the file name if the original
+ * file required is in use</li>
+ * <li>"%%" represents the percent sign character '%'</li>
  * </ul>
  * </p>
- * 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,
- * </p>
+ * 
  * <p>
- * The "%u" unique field is used to avoid conflicts and set to 0 at first. If
- * one <code>FileHandler</code> 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 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.
  * </p>
  * 
+ * <p>
+ * The unique identifier, denoted by "%u" in the filename pattern will always be
+ * 0 unless the <code>FileHandler</code> 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.
+ * </p>
  */
 public class FileHandler extends StreamHandler {