harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ndbe...@apache.org
Subject svn commit: r768119 [1/2] - /harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/
Date Fri, 24 Apr 2009 01:48:53 GMT
Author: ndbeyer
Date: Fri Apr 24 01:48:52 2009
New Revision: 768119

URL: http://svn.apache.org/viewvc?rev=768119&view=rev
Log:
Apply patch for HARMONY-6176 - Javadocs for java.util.logging.*

Modified:
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ErrorManager.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/FileHandler.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Filter.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Formatter.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Handler.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Level.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogManager.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogRecord.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Logger.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LoggingMXBean.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LoggingPermission.java
    harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/MemoryHandler.java

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ConsoleHandler.java Fri Apr 24 01:48:52 2009
@@ -19,42 +19,39 @@
 
 /**
  * A handler that writes log messages to the standard output stream
- * <code>System.err</code>.
+ * {@code System.err}.
  * <p>
  * This handler reads the following properties from the log manager to
  * initialize itself:
  * <ul>
  * <li>java.util.logging.ConsoleHandler.level specifies the logging level,
- * defaults to <code>Level.INFO</code> if this property is not found or has an
- * invalid value;
+ * defaults to {@code Level.INFO} if this property is not found or has an
+ * invalid value.
  * <li>java.util.logging.ConsoleHandler.filter specifies the name of the filter
- * class to be associated with this handler, defaults to <code>null</code> if
- * this property is not found or has an invalid value;
+ * class to be associated with this handler, defaults to {@code null} if this
+ * property is not found or has an invalid value.
  * <li>java.util.logging.ConsoleHandler.formatter specifies the name of the
  * formatter class to be associated with this handler, defaults to
- * <code>java.util.logging.SimpleFormatter</code> if this property is not
- * found or has an invalid value;
+ * {@code java.util.logging.SimpleFormatter} if this property is not found or
+ * has an invalid value.
  * <li>java.util.logging.ConsoleHandler.encoding specifies the encoding this
- * handler will use to encode log messages, defaults to <code>null</code> if
- * this property is not found or has an invalid value.
+ * handler will use to encode log messages, defaults to {@code null} if this
+ * property is not found or has an invalid value.
  * </ul>
- * </p>
  * <p>
  * This class is not thread-safe.
- * </p>
  */
 public class ConsoleHandler extends StreamHandler {
 
     /**
-     * Constructs a <code>ConsoleHandler</code> object.
+     * Constructs a {@code ConsoleHandler} object.
      */
     public ConsoleHandler() {
         super(System.err);
     }
 
     /**
-     * Closes this handler. The <code>System.err</code> is flushed but not
-     * closed.
+     * Closes this handler. The {@code System.err} is flushed but not closed.
      */
     @Override
     public void close() {
@@ -65,7 +62,7 @@
      * Logs a record if necessary. A flush operation will be done.
      * 
      * @param record
-     *            the log record to be logged
+     *            the log record to be logged.
      */
     @Override
     public void publish(LogRecord record) {

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ErrorManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ErrorManager.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ErrorManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/ErrorManager.java Fri Apr 24 01:48:52 2009
@@ -21,9 +21,9 @@
 
 /**
  * An error reporting facility for {@link Handler} implementations to record any
- * error that may happen during logging. <code>Handlers</code> should report
- * errors to an <code>ErrorManager</code>, instead of throwing exceptions,
- * which would interfere with the log issuer's execution.
+ * error that may happen during logging. {@code Handlers} should report errors
+ * to an {@code ErrorManager}, instead of throwing exceptions, which would
+ * interfere with the log issuer's execution.
  */
 public class ErrorManager {
 
@@ -70,7 +70,7 @@
     private boolean called;
 
     /**
-     * Constructs an instance of <code>ErrorManager</code>.
+     * Constructs an instance of {@code ErrorManager}.
      */
     public ErrorManager() {
         super();
@@ -83,13 +83,13 @@
      * should override this method.
      * 
      * @param message
-     *            The error message, which may be <code>null</code>.
+     *            the error message, which may be {@code null}.
      * @param exception
-     *            The exception associated with the error, which may be
-     *            <code>null</code>.
+     *            the exception associated with the error, which may be
+     *            {@code null}.
      * @param errorCode
-     *            The error code that identifies the type of error; see the
-     *            constant fields on this class.
+     *            the error code that identifies the type of error; see the
+     *            constant fields of this class for possible values.
      */
     public void error(String message, Exception exception, int errorCode) {
         synchronized (this) {

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?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- 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 Fri Apr 24 01:48:52 2009
@@ -32,75 +32,68 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * A <code>FileHandler</code> is a Handler that writes logging events to one
- * or more files.
- * 
+ * A {@code FileHandler} writes logging records into a specified file or a
+ * rotating set of files.
  * <p>
- * 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>
- * 
+ * 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.
  * <p>
- * <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:
+ * By default, the I/O buffering mechanism is enabled, but when each log record
+ * is complete, it is flushed out.
+ * <p>
+ * {@code XMLFormatter} is the default formatter for {@code FileHandler}.
+ * <p>
+ * {@code FileHandler} reads the following {@code LogManager} properties for
+ * initialization; if a property is not defined or has an invalid value, a
+ * default value is used.
  * <ul>
- * <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 - 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>
+ * <li>java.util.logging.FileHandler.append specifies whether this
+ * {@code FileHandler} should append onto existing files, defaults to
+ * {@code false}.</li>
+ * <li>java.util.logging.FileHandler.count specifies how many output files to
+ * rotate, defaults to 1.</li>
+ * <li>java.util.logging.FileHandler.filter specifies the {@code Filter} class
+ * name, defaults to no {@code Filter}.</li>
+ * <li>java.util.logging.FileHandler.formatter specifies the {@code Formatter}
+ * class, defaults to {@code java.util.logging.XMLFormatter}.</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.level specifies the level for this
+ * {@code Handler}, defaults to {@code Level.ALL}.</li>
+ * <li>java.util.logging.FileHandler.limit specifies the maximum number of
+ * bytes to write to any one file, defaults to zero, which means no limit.</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>
  * </ul>
- * </p>
- * 
  * <p>
- * 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:
+ * Name pattern is a string that may include some special substrings, which will
+ * be replaced to generate output files:
  * <ul>
- * <li>"/" represents the local path separator</li>
- * <li>"%g" represents the generation number used to enumerate log files</li>
+ * <li>"/" represents the local pathname separator</li>
+ * <li>"%g" represents the generation number to distinguish rotated logs</li>
  * <li>"%h" represents the home directory of the current user, which is
- * specified by the "user.home" system property</li>
+ * specified by "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>"%u" represents a unique number to resolve conflicts</li>
  * <li>"%%" represents the percent sign character '%'</li>
  * </ul>
- * </p>
- * 
  * <p>
- * 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>
- * 
+ * 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.
  * <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>
+ * The "%u" unique field is used to avoid conflicts and is set to 0 at first. If
+ * one {@code 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.
  */
 public class FileHandler extends StreamHandler {
 
@@ -149,17 +142,17 @@
     int uniqueID = -1;
 
     /**
-     * Construct a <code>FileHandler</code> using <code>LogManager</code>
-     * properties or their default value
+     * Construct a {@code FileHandler} using {@code LogManager} properties or
+     * their default value.
      * 
      * @throws IOException
-     *             if any IO exception happened
+     *             if any I/O error occurs.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      */
     public FileHandler() throws IOException {
         init(null, null, null, null);
@@ -386,27 +379,26 @@
     }
 
     /**
-     * Construct a <code>FileHandler</code>, the given name pattern is used
-     * as output filename, the file limit is set to zero(no limit), and the file
-     * count is set to one, other configuration using <code>LogManager</code>
-     * properties or their default value
-     * 
-     * This handler write to only one file and no amount limit.
-     * 
+     * Constructs a new {@code 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
+     * {@code LogManager} properties or their default values. This handler
+     * writes to only one file with no size limit.
+     *
      * @param pattern
-     *            the name pattern of output file
+     *            the name pattern for the output file.
      * @throws IOException
-     *             if any IO exception happened
+     *             if any I/O error occurs.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
-     * @throws NullPointerException
-     *             if the pattern is <code>null</code>.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      * @throws IllegalArgumentException
      *             if the pattern is empty.
+     * @throws NullPointerException
+     *             if the pattern is {@code null}.
      */
     public FileHandler(String pattern) throws IOException {
         if (pattern.equals("")) { //$NON-NLS-1$
@@ -418,30 +410,29 @@
     }
 
     /**
-     * Construct a <code>FileHandler</code>, the given name pattern is used
-     * as output filename, the file limit is set to zero(i.e. no limit applies),
-     * the file count is initialized to one, and the value of
-     * <code>append</code> becomes the new instance's append mode. Other
-     * configuration is done using <code>LogManager</code> properties.
-     * 
-     * This handler write to only one file and no amount limit.
-     * 
+     * Construct a new {@code 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 {@code append} becomes the new
+     * instance's append mode. The remaining configuration is done using
+     * {@code LogManager} properties. This handler writes to only one file
+     * with no size limit.
+     *
      * @param pattern
-     *            the name pattern of output file
+     *            the name pattern for the output file.
      * @param append
-     *            the append mode
+     *            the append mode.
      * @throws IOException
-     *             if any IO exception happened
+     *             if any I/O error occurs.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
-     * @throws NullPointerException
-     *             if the pattern is <code>null</code>.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      * @throws IllegalArgumentException
-     *             if the pattern is empty.
+     *             if {@code pattern} is empty.
+     * @throws NullPointerException
+     *             if {@code pattern} is {@code null}.
      */
     public FileHandler(String pattern, boolean append) throws IOException {
         if (pattern.equals("")) { //$NON-NLS-1$
@@ -453,34 +444,33 @@
     }
 
     /**
-     * Construct a <code>FileHandler</code>, the given name pattern is used
-     * as output filename, the file limit is set to given limit argument, and
-     * the file count is set to given count argument, other configuration using
-     * <code>LogManager</code> properties or their default value
-     * 
-     * 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.
-     * 
+     * Construct a new {@code FileHandler}. The given name pattern is used as
+     * output filename, the maximum file size is set to {@code limit} and the
+     * file count is initialized to {@code count}. The remaining configuration
+     * is done using {@code 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.
+     *
      * @param pattern
-     *            the name pattern of output file
+     *            the name pattern for the output file.
      * @param limit
-     *            the data amount limit in bytes of one output file, cannot less
-     *            than one
+     *            the data amount limit in bytes of one output file, can not be
+     *            negative.
      * @param count
-     *            the maximum number of files can be used, cannot less than one
+     *            the maximum number of files to use, can not be less than one.
      * @throws IOException
-     *             if any IO exception happened
+     *             if any I/O error occurs.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
-     * @throws NullPointerException
-     *             if pattern is <code>null</code>.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      * @throws IllegalArgumentException
-     *             if count<1, or limit<0
+     *             if {@code pattern} is empty, {@code limit < 0} or
+     *             {@code count < 1}.
+     * @throws NullPointerException
+     *             if {@code pattern} is {@code null}.
      */
     public FileHandler(String pattern, int limit, int count) throws IOException {
         if (pattern.equals("")) { //$NON-NLS-1$
@@ -495,37 +485,36 @@
     }
 
     /**
-     * Construct a <code>FileHandler</code>, the given name pattern is used
-     * as output filename, the file limit is set to given limit argument, the
-     * file count is set to given count argument, and the append mode is set to
-     * given append argument, other configuration using <code>LogManager</code>
-     * properties or their default value
-     * 
-     * 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.
-     * 
+     * Construct a new {@code FileHandler}. The given name pattern is used as
+     * output filename, the maximum file size is set to {@code limit}, the file
+     * count is initialized to {@code count} and the append mode is set to
+     * {@code append}. The remaining configuration is done using
+     * {@code 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.
+     *
      * @param pattern
-     *            the name pattern of output file
+     *            the name pattern for the output file.
      * @param limit
-     *            the data amount limit in bytes of one output file, cannot less
-     *            than one
+     *            the data amount limit in bytes of one output file, can not be
+     *            negative.
      * @param count
-     *            the maximum number of files can be used, cannot less than one
+     *            the maximum number of files to use, can not be less than one.
      * @param append
-     *            the append mode
+     *            the append mode.
      * @throws IOException
-     *             if any IO exception happened
+     *             if any I/O error occurs.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
-     * @throws NullPointerException
-     *             if pattern is <code>null</code>.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      * @throws IllegalArgumentException
-     *             if count<1, or limit<0
+     *             if {@code pattern} is empty, {@code limit < 0} or
+     *             {@code count < 1}.
+     * @throws NullPointerException
+     *             if {@code pattern} is {@code null}.
      */
     public FileHandler(String pattern, int limit, int count, boolean append)
             throws IOException {
@@ -542,14 +531,14 @@
     }
 
     /**
-     * Flush and close all opened files.
+     * Flushes and closes all opened files.
      * 
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler,
-     *             required permissions include
-     *             <code>LogPermission("control")</code> and other permission
-     *             like <code>FilePermission("write")</code>, etc.
+     *             if a security manager exists and it determines that the
+     *             caller does not have the required permissions to control this
+     *             handler; required permissions include
+     *             {@code LogPermission("control")},
+     *             {@code FilePermission("write")} etc.
      */
     @Override
     public void close() {
@@ -568,10 +557,10 @@
     }
 
     /**
-     * Publish a <code>LogRecord</code>
+     * Publish a {@code LogRecord}.
      * 
      * @param record
-     *            the log record to be published
+     *            the log record to publish.
      */
     @Override
     public void publish(LogRecord record) {
@@ -588,9 +577,9 @@
     }
 
     /**
-     * This output stream use decorator pattern to add measure feature to
-     * OutputStream which can detect the total size(in bytes) of output, the
-     * initial size can be set
+     * This output stream uses the decorator pattern to add measurement features
+     * to OutputStream which can detect the total size(in bytes) of output, the
+     * initial size can be set.
      */
     static class MeasureOutputStream extends OutputStream {
 

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Filter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Filter.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Filter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Filter.java Fri Apr 24 01:48:52 2009
@@ -18,18 +18,18 @@
 package java.util.logging;
 
 /**
- * A Filter provides a mechanism for exercising fine-grained control over what
- * records get logged.
+ * A {@code Filter} provides a mechanism for exercising fine-grained control
+ * over which records get logged.
  */
 public interface Filter {
 
     /**
-     * Checks the {@link LogRecord} to determine if it should be logged.
+     * Checks {@code record} to determine if it should be logged.
      * 
      * @param record
-     *            The {@link LogRecord} to be checked.
-     * @return <code>true</code> if the supplied log record needs to be
-     *         logged, otherwise <code>false</code>
+     *            the {@link LogRecord} to be checked.
+     * @return {@code true} if the supplied log record needs to be logged,
+     *         {@code false} otherwise.
      */
     boolean isLoggable(LogRecord record);
 }

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Formatter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Formatter.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Formatter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Formatter.java Fri Apr 24 01:48:52 2009
@@ -21,44 +21,45 @@
 import java.util.ResourceBundle;
 
 /**
- * <code>Formatter</code> objects are used to format <code>LogRecord</code>
- * objects into a string representation. Head and tail strings are sometime used
- * to wrap a set of records. The <code>getHead</code> and <code>getTail</code>
- * methods are presented for this purpose.
+ * {@code Formatter} objects are used to format {@link LogRecord} objects into a
+ * string representation. Head and tail strings are sometimes used to wrap a set
+ * of records. The {@code getHead} and {@code getTail} methods are used for this
+ * purpose.
  */
 public abstract class Formatter {
 
     /**
-     * Constructs a <code>Formatter</code> object.
+     * Constructs a {@code Formatter} object.
      */
     protected Formatter() {
         super();
     }
 
     /**
-     * Formats a <code>LogRecord</code> object into a string representation.
-     * The resulted string is usually localized and includes the message field
-     * of the supplied <code>LogRecord</code> object.
+     * Converts a {@link LogRecord} object into a string representation. The
+     * resulted string is usually localized and includes the message field of
+     * the record.
      * 
      * @param r
-     *            the log record to be formatted into a string
-     * @return the string resulted from the formatting
+     *            the log record to be formatted into a string.
+     * @return the formatted string.
      */
     public abstract String format(LogRecord r);
 
     /**
-     * Formats a <code>LogRecord</code> object into a localized string
-     * representation. This method can be regarded as a convenience for
-     * subclasses of <code>Formatter</code> to use.
+     * Formats a {@code LogRecord} object into a localized string
+     * representation. This is a convenience method for subclasses of {@code
+     * Formatter}.
      * <p>
-     * The message string is firstly localized using the
-     * <code>ResourceBundle</code> object associated with the supplied
-     * <code>LogRecord</code>.
-     * </p>
-     * 
+     * The message string is firstly localized using the {@code ResourceBundle}
+     * object associated with the supplied {@code LogRecord}.
+     * <p>
+     * Notice : if message contains "{0", then java.text.MessageFormat is used.
+     * Otherwise no formatting is performed.
+     *
      * @param r
-     *            the log record to be formatted
-     * @return the string resulted from the formatting
+     *            the log record to be formatted.
+     * @return the string resulted from the formatting.
      */
     public String formatMessage(LogRecord r) {
         String pattern = r.getMessage();
@@ -91,11 +92,12 @@
 
     /**
      * Gets the head string used to wrap a set of log records. This base class
-     * always returns the empty string.
+     * always returns an empty string.
      * 
      * @param h
-     *            the target handler
-     * @return the head string used to wrap a set of log records
+     *            the target handler.
+     * @return the head string used to wrap a set of log records, empty in this
+     *         implementation.
      */
     @SuppressWarnings("unused")
     public String getHead(Handler h) {
@@ -107,8 +109,9 @@
      * always returns the empty string.
      * 
      * @param h
-     *            the target handler
-     * @return the tail string used to wrap a set of log records
+     *            the target handler.
+     * @return the tail string used to wrap a set of log records, empty in this
+     *         implementation.
      */
     @SuppressWarnings("unused")
     public String getTail(Handler h) {

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Handler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Handler.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Handler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Handler.java Fri Apr 24 01:48:52 2009
@@ -25,9 +25,9 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * A <code>Handler</code> object accepts a logging request and exports the
- * desired messages to a target, for example, a file, the console, etc. It can
- * be disabled by setting its logging level to <code>Level.OFF</code>.
+ * A {@code Handler} object accepts a logging request and exports the desired
+ * messages to a target, for example, a file, the console, etc. It can be
+ * disabled by setting its logging level to {@code Level.OFF}.
  */
 public abstract class Handler {
 
@@ -52,9 +52,9 @@
     private String prefix;
 
     /**
-     * Constructs a <code>Handler</code> object with a default error manager,
-     * the default encoding, and the default logging level
-     * <code>Level.ALL</code>. It has no filter and no formatter.
+     * Constructs a {@code Handler} object with a default error manager instance
+     * {@code ErrorManager}, the default encoding, and the default logging
+     * level {@code Level.ALL}. It has no filter and no formatter.
      */
     protected Handler() {
         this.errorMan = new ErrorManager();
@@ -164,12 +164,12 @@
     }
 
     /**
-     * Closes this handler. A flush operation will usually be performed and all
-     * the associated resources will be freed. Client applications should not
-     * use a handler after closing it.
+     * Closes this handler. A flush operation will be performed and all the
+     * associated resources will be freed. Client applications should not use
+     * this handler after closing it.
      * 
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public abstract void close();
@@ -180,17 +180,18 @@
     public abstract void flush();
 
     /**
-     * Accepts an actual logging request.
+     * Accepts a logging request and sends it to the the target.
      * 
      * @param record
-     *            the log record to be logged
+     *            the log record to be logged; {@code null} records are ignored.
      */
     public abstract void publish(LogRecord record);
 
     /**
-     * Gets the character encoding used by this handler.
+     * Gets the character encoding used by this handler, {@code null} for
+     * default encoding.
      * 
-     * @return the character encoding used by this handler
+     * @return the character encoding used by this handler.
      */
     public String getEncoding() {
         return this.encoding;
@@ -200,9 +201,9 @@
      * Gets the error manager used by this handler to report errors during
      * logging.
      * 
-     * @return the error manager used by this handler
+     * @return the error manager used by this handler.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public ErrorManager getErrorManager() {
@@ -213,7 +214,7 @@
     /**
      * Gets the filter used by this handler.
      * 
-     * @return the filter used by this handler
+     * @return the filter used by this handler (possibly {@code null}).
      */
     public Filter getFilter() {
         return this.filter;
@@ -222,29 +223,30 @@
     /**
      * Gets the formatter used by this handler to format the logging messages.
      * 
-     * @return the formatter used by this handler
+     * @return the formatter used by this handler (possibly {@code null}).
      */
     public Formatter getFormatter() {
         return this.formatter;
     }
 
     /**
-     * Gets the logging level of this handler.
+     * Gets the logging level of this handler, records with levels lower than
+     * this value will be dropped.
      * 
-     * @return the logging level of this handler
+     * @return the logging level of this handler.
      */
     public Level getLevel() {
         return this.level;
     }
 
     /**
-     * Determines whether the supplied log record need to be logged. The logging
-     * levels will be checked as well as the filter.
+     * Determines whether the supplied log record needs to be logged. The
+     * logging levels will be checked as well as the filter.
      * 
      * @param record
-     *            the log record to be checked
-     * @return <code>true</code> if the supplied log record need to be logged,
-     *         otherwise <code>false</code>
+     *            the log record to be checked.
+     * @return {@code true} if the supplied log record needs to be logged,
+     *         otherwise {@code false}.
      */
     public boolean isLoggable(LogRecord record) {
         if (null == record) {
@@ -259,28 +261,31 @@
     }
 
     /**
-     * Report an error to the error manager associated with this handler.
-     * 
+     * Reports an error to the error manager associated with this handler,
+     * {@code ErrorManager} is used for that purpose. No security checks are
+     * done, therefore this is compatible with environments where the caller
+     * is non-privileged.
+     *
      * @param msg
-     *            the error message
+     *            the error message, may be {@code null}.
      * @param ex
-     *            the associated exception
+     *            the associated exception, may be {@code null}.
      * @param code
-     *            the error code
+     *            an {@code ErrorManager} error code.
      */
     protected void reportError(String msg, Exception ex, int code) {
         this.errorMan.error(msg, ex, code);
     }
 
     /**
-     * Sets the character encoding used by this handler. A <code>null</code>
-     * value indicates the using of the default encoding. This internal method
-     * does not check security.
+     * Sets the character encoding used by this handler. A {@code null} value
+     * indicates the use of the default encoding. This internal method does
+     * not check security.
      * 
      * @param newEncoding
-     *            the character encoding to set
+     *            the character encoding to set.
      * @throws UnsupportedEncodingException
-     *             If the specified encoding is not supported by the runtime.
+     *             if the specified encoding is not supported by the runtime.
      */
     void internalSetEncoding(String newEncoding)
             throws UnsupportedEncodingException {
@@ -301,16 +306,16 @@
     }
 
     /**
-     * Sets the character encoding used by this handler. A <code>null</code>
-     * value indicates the using of the default encoding.
+     * Sets the character encoding used by this handler, {@code null} indicates
+     * a default encoding.
      * 
      * @param encoding
-     *            the character encoding to set
+     *            the character encoding to set.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      * @throws UnsupportedEncodingException
-     *             If the specified encoding is not supported by the runtime.
+     *             if the specified encoding is not supported by the runtime.
      */
     public void setEncoding(String encoding) throws SecurityException,
             UnsupportedEncodingException {
@@ -322,9 +327,11 @@
      * Sets the error manager for this handler.
      * 
      * @param em
-     *            the error manager to set
+     *            the error manager to set.
+     * @throws NullPointerException
+     *             if {@code em} is {@code null}.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public void setErrorManager(ErrorManager em) {
@@ -339,9 +346,9 @@
      * Sets the filter to be used by this handler.
      * 
      * @param newFilter
-     *            the filter to set
+     *            the filter to set, may be {@code null}.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public void setFilter(Filter newFilter) {
@@ -354,7 +361,7 @@
      * not check security.
      * 
      * @param newFormatter
-     *            the formatter to set
+     *            the formatter to set.
      */
     void internalSetFormatter(Formatter newFormatter) {
         if (null == newFormatter) {
@@ -367,9 +374,11 @@
      * Sets the formatter to be used by this handler.
      * 
      * @param newFormatter
-     *            the formatter to set
+     *            the formatter to set.
+     * @throws NullPointerException
+     *             if {@code newFormatter} is {@code null}.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public void setFormatter(Formatter newFormatter) {
@@ -378,12 +387,15 @@
     }
 
     /**
-     * Sets the logging level of this handler.
+     * Sets the logging level of the messages logged by this handler, levels
+     * lower than this value will be dropped.
      * 
      * @param newLevel
-     *            the logging level to set
+     *            the logging level to set.
+     * @throws NullPointerException
+     *             if {@code newLevel} is {@code null}.
      * @throws SecurityException
-     *             If a security manager determines that the caller does not
+     *             if a security manager determines that the caller does not
      *             have the required permission.
      */
     public void setLevel(Level newLevel) {

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Level.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Level.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Level.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/Level.java Fri Apr 24 01:48:52 2009
@@ -30,16 +30,15 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * <code>Level</code> objects are used to indicate the level of logging. There
- * are a set of predefined logging levels, each associated with an integer
- * value. Enabling a certain logging level also enables all logging levels with
- * larger values.
+ * {@code Level} objects are used to indicate the level of logging. There are a
+ * set of predefined logging levels, each associated with an integer value.
+ * Enabling a certain logging level also enables all logging levels with larger
+ * values.
  * <p>
  * The predefined levels in ascending order are FINEST, FINER, FINE, CONFIG,
  * INFO, WARNING, SEVERE. There are two additional predefined levels, which are
  * ALL and OFF. ALL indicates logging all messages, and OFF indicates logging no
  * messages.
- * </p>
  */
 public class Level implements Serializable {
 
@@ -53,22 +52,22 @@
     public static final Level OFF = new Level("OFF", Integer.MAX_VALUE); //$NON-NLS-1$
 
     /**
-     * The SEVERE level indicates a severe failure.
+     * The SEVERE level provides severe failure messages.
      */
     public static final Level SEVERE = new Level("SEVERE", 1000); //$NON-NLS-1$
 
     /**
-     * The WARNING level indicates a warning.
+     * The WARNING level provides warnings.
      */
     public static final Level WARNING = new Level("WARNING", 900); //$NON-NLS-1$
 
     /**
-     * The INFO level indicates an informative message.
+     * The INFO level provides informative messages.
      */
     public static final Level INFO = new Level("INFO", 800); //$NON-NLS-1$
 
     /**
-     * The CONFIG level indicates a static configuration message.
+     * The CONFIG level provides static configuration messages.
      */
     public static final Level CONFIG = new Level("CONFIG", 700); //$NON-NLS-1$
 
@@ -93,15 +92,16 @@
     public static final Level ALL = new Level("ALL", Integer.MIN_VALUE); //$NON-NLS-1$
 
     /**
-     * Parses a level name into a <code>Level</code> object.
+     * Parses a level name into a {@code Level} object.
      * 
      * @param name
-     *            the name of the desired level, which cannot be null
-     * @return a <code>Level</code> object with the specified name
+     *            the name of the desired {@code level}, which cannot be
+     *            {@code null}.
+     * @return the level with the specified name.
      * @throws NullPointerException
-     *             if <code>name</code> is <code>null</code>.
+     *             if {@code name} is {@code null}.
      * @throws IllegalArgumentException
-     *             if <code>name</code> is not valid.
+     *             if {@code name} is not valid.
      */
     public static Level parse(String name) throws IllegalArgumentException {
         if (name == null) {
@@ -176,32 +176,32 @@
     private transient ResourceBundle rb;
 
     /**
-     * Constructs an instance of <code>Level</code> taking the supplied name
-     * and level value.
+     * Constructs an instance of {@code Level} taking the supplied name and
+     * level value.
      * 
      * @param name
-     *            name of the level
+     *            the name of the level.
      * @param level
-     *            an integer value indicating the level
+     *            an integer value indicating the level.
      * @throws NullPointerException
-     *             if <code>name</code> is <code>null</code>.
+     *             if {@code name} is {@code null}.
      */
     protected Level(String name, int level) {
         this(name, level, null);
     }
 
     /**
-     * Constructs an instance of <code>Level</code> taking the supplied name
-     * and level value.
+     * Constructs an instance of {@code Level} taking the supplied name, level
+     * value and resource bundle name.
      * 
      * @param name
-     *            name of the level
+     *            the name of the level.
      * @param level
-     *            an integer value indicating the level
+     *            an integer value indicating the level.
      * @param resourceBundleName
-     *            the name of the resource bundle to use
+     *            the name of the resource bundle to use.
      * @throws NullPointerException
-     *             if <code>name</code> is <code>null</code>.
+     *             if {@code name} is {@code null}.
      */
     protected Level(String name, int level, String resourceBundleName) {
         if (name == null) {
@@ -225,29 +225,27 @@
     }
 
     /**
-     * Gets the name of this <code>Level</code>.
+     * Gets the name of this level.
      * 
-     * @return the name of this <code>Level</code>
+     * @return this level's name.
      */
     public String getName() {
         return this.name;
     }
 
     /**
-     * Gets the name of the resource bundle associated with this
-     * <code>Level</code>.
+     * Gets the name of the resource bundle associated with this level.
      * 
-     * @return the name of the resource bundle associated with this
-     *         <code>Level</code>
+     * @return the name of this level's resource bundle.
      */
     public String getResourceBundleName() {
         return this.resourceBundleName;
     }
 
     /**
-     * Gets the integer value indicating this <code>Level</code>.
+     * Gets the integer value indicating this level.
      * 
-     * @return the integer value indicating this <code>Level</code>
+     * @return this level's integer value.
      */
     public final int intValue() {
         return this.value;
@@ -257,7 +255,7 @@
      * Serialization helper method to maintain singletons and add any new
      * levels.
      * 
-     * @return The resolved instance.
+     * @return the resolved instance.
      */
     private Object readResolve() {
         synchronized (levels) {
@@ -285,7 +283,7 @@
      * Serialization helper to setup transient resource bundle instance.
      * 
      * @param in
-     *            The input stream to read the instance data from.
+     *            the input stream to read the instance data from.
      * @throws IOException
      *             if an IO error occurs.
      * @throws ClassNotFoundException
@@ -305,10 +303,10 @@
 
     /**
      * Gets the localized name of this level. The default locale is used. If no
-     * resource bundle is associated with this <code>Level</code>, the
-     * original level name is returned.
+     * resource bundle is associated with this level then the original level
+     * name is returned.
      * 
-     * @return the localized name of this level
+     * @return the localized name of this level.
      */
     public String getLocalizedName() {
         if (rb == null) {
@@ -323,13 +321,13 @@
     }
 
     /**
-     * Compares two <code>Level</code> objects for equality. They are
-     * considered to be equal if they have the same value.
+     * Compares two {@code Level} objects for equality. They are considered to
+     * be equal if they have the same level value.
      * 
      * @param o
-     *            the other object to be compared with
-     * @return <code>true</code> if this object equals to the supplied object,
-     *         otherwise <code>false</code>
+     *            the other object to compare this level to.
+     * @return {@code true} if this object equals to the supplied object,
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object o) {
@@ -345,9 +343,9 @@
     }
 
     /**
-     * Returns the hash code of this <code>Level</code> object.
+     * Returns the hash code of this {@code Level} object.
      * 
-     * @return the hash code of this <code>Level</code> object
+     * @return this level's hash code.
      */
     @Override
     public int hashCode() {
@@ -355,10 +353,10 @@
     }
 
     /**
-     * Returns the string representation of this <code>Level</code> object.
-     * Usually this will include its name.
+     * Returns the string representation of this {@code Level} object. In
+     * this case, it is the level's name.
      * 
-     * @return the string representation of this <code>Level</code> object
+     * @return the string representation of this level.
      */
     @Override
     public final String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogManager.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogManager.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogManager.java Fri Apr 24 01:48:52 2009
@@ -43,83 +43,87 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * <code>LogManager</code> is used to manage named <code>Logger</code>s and
- * any shared logging properties.
+ * {@code LogManager} is used to maintain configuration properties of the
+ * logging framework, and to manage a hierarchical namespace of all named
+ * {@code Logger} objects.
+ * <p>
+ * There is only one global {@code LogManager} instance in the
+ * application, which can be get by calling static method
+ * {@link #getLogManager()}. This instance is created and
+ * initialized during class initialization and cannot be changed.
+ * <p>
+ * The {@code LogManager} class can be specified by
+ * java.util.logging.manager system property, if the property is unavailable or
+ * invalid, the default class {@link java.util.logging.LogManager} will
+ * be used.
+ * <p>
+ * On initialization, {@code LogManager} reads its configuration from a
+ * properties file, which by default is the "lib/logging.properties" in the JRE
+ * directory.
  * <p>
- * There is one global <code>LogManager</code> instance in the application,
- * which can be obtained by calling the static method
- * <code>LogManager.getLogManager()</code>.
- * </p>
- * <p>
- * All methods on this type can be taken as being thread safe.
- * </p>
- * <p>
- * The <code>LogManager</code> class can be specified by the
- * "java.util.logging.manager" system property. If the property is unavailable
- * or invalid <code>java.util.logging.LogManager</code> will be used by
- * default.
- * </p>
- * <p>
- * On initialization, <code>LogManager</code> reads its configuration data
- * from a properties file, which by default is the "lib/logging.properties" file
- * in the JRE directory.
- * </p>
- * <p>
- * However, two system properties can be used instead to customize the
- * initialization of the <code>LogManager</code>:
+ * However, two optional system properties can be used to customize the initial
+ * configuration process of {@code LogManager}.
  * <ul>
  * <li>"java.util.logging.config.class"</li>
  * <li>"java.util.logging.config.file"</li>
  * </ul>
- * </p>
  * <p>
- * These properties can be set either by using the Preferences API, as a command
- * line option or by passing the appropriate system property definitions to
- * JNI_CreateJavaVM.
- * </p>
- * <p>
- * The "java.util.logging.config.class" property should specify a class name. If
- * it is set, this class will be loaded and instantiated during
- * <code>LogManager</code>'s initialization, so that this object's default
- * constructor can read the initial configuration and define properties for the
- * <code>LogManager</code>.
- * </p>
- * <p>
- * The "java.util.logging.config.file" system property can be used to specify a
- * properties file if the "java.util.logging.config.class" property has not been
- * used. This file will be read instead of the default properties file.
- * </p>
+ * These two properties can be set in three ways, by the Preferences API, by the
+ * "java" command line property definitions, or by system property definitions
+ * passed to JNI_CreateJavaVM.
+ * <p>
+ * The "java.util.logging.config.class" should specifies a class name. If it is
+ * set, this given class will be loaded and instantiated during
+ * {@code LogManager} initialization, so that this object's default
+ * constructor can read the initial configuration and define properties for
+ * {@code LogManager}.
+ * <p>
+ * If "java.util.logging.config.class" property is not set, or it is invalid, or
+ * some exception is thrown during the instantiation, then the
+ * "java.util.logging.config.file" system property can be used to specify a
+ * properties file. The {@code LogManager} will read initial
+ * configuration from this file.
+ * <p>
+ * If neither of these properties is defined, or some exception is thrown
+ * during these two properties using, the {@code LogManager} will read
+ * its initial configuration from default properties file, as described above.
  * <p>
- * Some global logging properties are as follows:
+ * The global logging properties may include:
  * <ul>
- * <li>"handlers" - a list of handler classes, separated by whitespace. These
- * classes must be subclasses of <code>Handler</code> and must have a public
- * no-argument constructor. They will be registered with the root
- * <code>Logger</code>.</li>
- * <li>"config" - a list of configuration classes, separated by whitespace.
- * These classes should also have a public no-argument default constructor,
- * which should contain all the code for applying that configuration to the
- * logging system.
+ * <li>"handlers". This property's values should be a list of class names for
+ * handler classes separated by whitespace, these classes must be subclasses of
+ * {@code Handler} and each must have a default constructor, these
+ * classes will be loaded, instantiated and registered as handlers on the root
+ * {@code Logger} (the {@code Logger} named ""). These
+ * {@code Handler}s maybe initialized lazily.</li>
+ * <li>"config". The property defines a list of class names separated by
+ * whitespace. Each class must have a default constructor, in which it can
+ * update the logging configuration, such as levels, handlers, or filters for
+ * some logger, etc. These classes will be loaded and instantiated during
+ * {@code LogManager} configuration</li>
  * </ul>
- * </p>
  * <p>
- * Besides global properties, properties for individual <code>Loggers</code>
- * and <code>Handlers</code> can be specified in the property files. The names
- * of these properties will start with the fully qualified name of the handler
- * or logger.
- * </p>
- * <p>
- * The <code>LogManager</code> organizes <code>Loggers</code> based on their
- * fully qualified names. For example, "x.y.z" is child of "x.y".
- * </p>
- * <p>
- * Levels for <code>Loggers</code> can be defined by properties whose name end
- * with ".level". For example, "alogger.level = 4" sets the level for the logger
- * "alogger" to 4, Any children of "alogger" will also be given the level 4
- * unless specified lower down in the properties file. The property ".level"
- * will set the log level for the root logger.
- * </p>
- * 
+ * This class, together with any handler and configuration classes associated
+ * with it, <b>must</b> be loaded from the system classpath when
+ * {@code LogManager} configuration occurs.
+ * <p>
+ * Besides global properties, the properties for loggers and Handlers can be
+ * specified in the property files. The names of these properties will start
+ * with the complete dot separated names for the handlers or loggers.
+ * <p>
+ * In the {@code LogManager}'s hierarchical namespace,
+ * {@code Loggers} are organized based on their dot separated names. For
+ * example, "x.y.z" is child of "x.y".
+ * <p>
+ * Levels for {@code Loggers} can be defined by properties whose name end
+ * with ".level". Thus "alogger.level" defines a level for the logger named as
+ * "alogger" and for all its children in the naming hierarchy. Log levels
+ * properties are read and applied in the same order as they are specified in
+ * the property file. The root logger's level can be defined by the property
+ * named as ".level".
+ * <p>
+ * All methods on this type can be taken as being thread safe.
+ *
  */
 public class LogManager {
     /*
@@ -140,16 +144,15 @@
     static LogManager manager;
 
     /**
-     * <p>
-     * The String value of the {@link LoggingMXBean}'s ObjectName.
-     * </p>
+     * The {@code String} value of the {@link LoggingMXBean}'s ObjectName.
      */
     public static final String LOGGING_MXBEAN_NAME = "java.util.logging:type=Logging"; //$NON-NLS-1$
 
     /**
-     * Get the <code>LoggingMXBean</code> instance
+     * Get the {@code LoggingMXBean} instance. this implementation always throws
+     * an UnsupportedOperationException.
      * 
-     * @return the <code>LoggingMXBean</code> instance
+     * @return the {@code LoggingMXBean} instance
      */
     public static LoggingMXBean getLoggingMXBean() {
         try {
@@ -226,8 +229,8 @@
 
     /**
      * Default constructor. This is not public because there should be only one
-     * <code>LogManager</code> instance, which can be get by
-     * <code>LogManager.getLogManager(</code>. This is protected so that
+     * {@code LogManager} instance, which can be get by
+     * {@code LogManager.getLogManager(}. This is protected so that
      * application can subclass the object.
      */
     protected LogManager() {
@@ -258,15 +261,15 @@
     }
 
     /**
-     * Check that the caller has <code>LoggingPermission("control")</code> so
+     * Check that the caller has {@code LoggingPermission("control")} so
      * that it is trusted to modify the configuration for logging framework. If
-     * the check passes, just return, otherwise <code>SecurityException</code>
+     * the check passes, just return, otherwise {@code SecurityException}
      * will be thrown.
      * 
      * @throws SecurityException
      *             if there is a security manager in operation and the invoker
      *             of this method does not have the required security permission
-     *             <code>LoggingPermission("control")</code>
+     *             {@code LoggingPermission("control")}
      */
     public void checkAccess() {
         if (null != System.getSecurityManager()) {
@@ -276,21 +279,20 @@
 
     /**
      * Add a given logger into the hierarchical namespace. The
-     * <code>Logger.addLogger()</code> factory methods call this method to add
-     * newly created Logger. This returns false if a logger with the given name
-     * has existed in the namespace
+     * {@code Logger.addLogger()} factory methods call this method to add newly
+     * created Logger. This returns false if a logger with the given name has
+     * existed in the namespace
      * <p>
-     * Note that the <code>LogManager</code> may only retain weak references
-     * to registered loggers. In order to prevent <code>Logger</code> objects
-     * from being unexpectedly garbage collected it is necessary for
-     * <i>applications</i> to maintain references to them.
+     * Note that the {@code LogManager} may only retain weak references to
+     * registered loggers. In order to prevent {@code Logger} objects from being
+     * unexpectedly garbage collected it is necessary for <i>applications</i>
+     * to maintain references to them.
      * </p>
      * 
      * @param logger
-     *            the logger to be added
+     *            the logger to be added.
      * @return true if the given logger is added into the namespace
-     *         successfully, false if the logger of given name has existed in
-     *         the namespace
+     *         successfully, false if the given logger exists in the namespace.
      */
     public synchronized boolean addLogger(Logger logger) {
         String name = logger.getName();
@@ -349,18 +351,18 @@
     }
 
     /**
-     * Get the logger with the given name
+     * Get the logger with the given name.
      * 
      * @param name
      *            name of logger
-     * @return logger with given name, or null if nothing is found
+     * @return logger with given name, or {@code null} if nothing is found.
      */
     public synchronized Logger getLogger(String name) {
         return loggers.get(name);
     }
 
     /**
-     * Get a <code>Enumeration</code> of all registered logger names
+     * Get a {@code Enumeration} of all registered logger names.
      * 
      * @return enumeration of registered logger names
      */
@@ -369,16 +371,16 @@
     }
 
     /**
-     * Get the global <code>LogManager</code> instance
+     * Get the global {@code LogManager} instance.
      * 
-     * @return the global <code>LogManager</code> instance
+     * @return the global {@code LogManager} instance
      */
     public static LogManager getLogManager() {
         return manager;
     }
 
     /**
-     * Get the value of property with given name
+     * Get the value of property with given name.
      * 
      * @param name
      *            the name of property
@@ -390,16 +392,16 @@
 
     /**
      * Re-initialize the properties and configuration. The initialization
-     * process is same as the <code>LogManager</code> instantiation.
+     * process is same as the {@code LogManager} instantiation.
      * <p>
-     * A <code>PropertyChangeEvent</code> must be fired.
+     * Notice : No {@code PropertyChangeEvent} are fired.
      * </p>
      * 
      * @throws IOException
-     *             if any IO related problems happened
+     *             if any IO related problems happened.
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
-     *             not have the required permissions to perform this action
+     *             not have the required permissions to perform this action.
      */
     public void readConfiguration() throws IOException {
         checkAccess();
@@ -494,18 +496,18 @@
 
     /**
      * Re-initialize the properties and configuration from the given
-     * <code>InputStream</code>
+     * {@code InputStream}
      * <p>
-     * A <code>PropertyChangeEvent</code> must be fired.
+     * Notice : No {@code PropertyChangeEvent} are fired.
      * </p>
      * 
      * @param ins
-     *            the input stream.
+     *            the input stream
      * @throws IOException
-     *             if any IO related problems happened
+     *             if any IO related problems happened.
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
-     *             not have the required permissions to perform this action
+     *             not have the required permissions to perform this action.
      */
     public void readConfiguration(InputStream ins) throws IOException {
         checkAccess();
@@ -517,12 +519,12 @@
      * <p>
      * All handlers are closed and removed from any named loggers. All loggers'
      * level is set to null, except the root logger's level is set to
-     * <code>Level.INFO</code>.
+     * {@code Level.INFO}.
      * </p>
      * 
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
-     *             not have the required permissions to perform this action
+     *             not have the required permissions to perform this action.
      */
     public void reset() {
         checkAccess();
@@ -542,11 +544,11 @@
     }
 
     /**
-     * Add a <code>PropertyChangeListener</code>, which will be invoked when
+     * Add a {@code PropertyChangeListener}, which will be invoked when
      * the properties are reread.
      * 
      * @param l
-     *            the <code>PropertyChangeListener</code> to be added
+     *            the {@code PropertyChangeListener} to be added.
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
      *             not have the required permissions to perform this action
@@ -560,11 +562,11 @@
     }
 
     /**
-     * Remove a <code>PropertyChangeListener</code>, do nothing if the given
+     * Remove a {@code PropertyChangeListener}, do nothing if the given
      * listener is not found.
      * 
      * @param l
-     *            the <code>PropertyChangeListener</code> to be removed
+     *            the {@code PropertyChangeListener} to be removed.
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
      *             not have the required permissions to perform this action

Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogRecord.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogRecord.java?rev=768119&r1=768118&r2=768119&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogRecord.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/LogRecord.java Fri Apr 24 01:48:52 2009
@@ -27,20 +27,19 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * A <code>LogRecord</code> object represents a logging request. It is passed
- * between the logging framework and individual logging handlers. Client
- * applications should not modify a <code>LogRecord</code> object that has
- * been passed into the logging framework.
+ * A {@code LogRecord} object represents a logging request. It is passed between
+ * the logging framework and individual logging handlers. Client applications
+ * should not modify a {@code LogRecord} object that has been passed into the
+ * logging framework.
  * <p>
- * The <code>LogRecord</code> class will infer the source method name and
- * source class name the first time they are accessed if the client application
- * didn't specify them explicitly. This automatic inference is based on the
- * analysis of the call stack and is not guaranteed to be precise. Client
- * applications should force the initialization of these two fields by calling
- * <code>getSourceClassName</code> or <code>getSourceMethodName</code> if
- * they expect to use them after passing the <code>LogRecord</code> object to
- * another thread or transmitting it over RMI.
- * </p>
+ * The {@code LogRecord} class will infer the source method name and source
+ * class name the first time they are accessed if the client application didn't
+ * specify them explicitly. This automatic inference is based on the analysis of
+ * the call stack and is not guaranteed to be precise. Client applications
+ * should force the initialization of these two fields by calling
+ * {@code getSourceClassName} or {@code getSourceMethodName} if they expect to
+ * use them after passing the {@code LogRecord} object to another thread or
+ * transmitting it over RMI.
  */
 public class LogRecord implements Serializable {
 
@@ -111,7 +110,7 @@
     private long millis;
 
     /**
-     * The associated <code>Throwable</code> object if any.
+     * The associated {@code Throwable} object if any.
      * 
      * @serial
      */
@@ -141,16 +140,18 @@
     private transient boolean sourceInited;
 
     /**
-     * Constructs a <code>LogRecord</code> object using the supplied the
-     * logging level and message. The millis property is set to the current
-     * time. The sequence property is set to a new unique value, allocated in
-     * increasing order within a VM. The thread ID is set to a unique value for
-     * the current thread. All other properties are set to <code>null</code>.
-     * 
+     * Constructs a {@code LogRecord} object using the supplied the logging
+     * level and message. The millis property is set to the current time. The
+     * sequence property is set to a new unique value, allocated in increasing
+     * order within the virtual machine. The thread ID is set to a unique value
+     * for the current thread. All other properties are set to {@code null}.
+     *
      * @param level
-     *            the logging level which may not be null
+     *            the logging level, may not be {@code null}.
      * @param msg
-     *            the raw message
+     *            the raw message.
+     * @throws NullPointerException
+     *             if {@code level} is {@code null}.
      */
     public LogRecord(Level level, String msg) {
         if (null == level) {
@@ -184,7 +185,7 @@
     /**
      * Gets the logging level.
      * 
-     * @return the logging level
+     * @return the logging level.
      */
     public Level getLevel() {
         return level;
@@ -194,7 +195,9 @@
      * Sets the logging level.
      * 
      * @param level
-     *            the level to set
+     *            the level to set.
+     * @throws NullPointerException
+     *             if {@code level} is {@code null}.
      */
     public void setLevel(Level level) {
         if (null == level) {
@@ -207,7 +210,7 @@
     /**
      * Gets the name of the logger.
      * 
-     * @return the logger name
+     * @return the logger name.
      */
     public String getLoggerName() {
         return loggerName;
@@ -217,7 +220,7 @@
      * Sets the name of the logger.
      * 
      * @param loggerName
-     *            the logger name to set
+     *            the logger name to set.
      */
     public void setLoggerName(String loggerName) {
         this.loggerName = loggerName;
@@ -226,36 +229,38 @@
     /**
      * Gets the raw message.
      * 
-     * @return the raw message
+     * @return the raw message, may be {@code null}.
      */
     public String getMessage() {
         return message;
     }
 
     /**
-     * Sets the raw message.
+     * Sets the raw message. When this record is formatted by a logger that has
+     * a localization resource bundle that contains an entry for {@code message},
+     * then the raw message is replaced with its localized version.
      * 
      * @param message
-     *            the raw message to set
+     *            the raw message to set, may be {@code null}.
      */
     public void setMessage(String message) {
         this.message = message;
     }
 
     /**
-     * Gets the time that the event occurred, in milliseconds since 1970.
+     * Gets the time when this event occurred, in milliseconds since 1970.
      * 
-     * @return the time that the event occurred, in milliseconds since 1970
+     * @return the time when this event occurred, in milliseconds since 1970.
      */
     public long getMillis() {
         return millis;
     }
 
     /**
-     * Sets the time that the event occurred, in milliseconds since 1970.
+     * Sets the time when this event occurred, in milliseconds since 1970.
      * 
      * @param millis
-     *            the time that the event occurred, in milliseconds since 1970
+     *            the time when this event occurred, in milliseconds since 1970.
      */
     public void setMillis(long millis) {
         this.millis = millis;
@@ -264,7 +269,8 @@
     /**
      * Gets the parameters.
      * 
-     * @return the array of parameters
+     * @return the array of parameters or {@code null} if there are no
+     *         parameters.
      */
     public Object[] getParameters() {
         return parameters;
@@ -274,7 +280,7 @@
      * Sets the parameters.
      * 
      * @param parameters
-     *            the array of parameters to set
+     *            the array of parameters to set, may be {@code null}.
      */
     public void setParameters(Object[] parameters) {
         this.parameters = parameters;
@@ -284,7 +290,8 @@
      * Gets the resource bundle used to localize the raw message during
      * formatting.
      * 
-     * @return the associated resource bundle
+     * @return the associated resource bundle, {@code null} if none is
+     *         available or the message is not localizable.
      */
     public ResourceBundle getResourceBundle() {
         return resourceBundle;
@@ -293,9 +300,9 @@
     /**
      * Sets the resource bundle used to localize the raw message during
      * formatting.
-     * 
+     *
      * @param resourceBundle
-     *            the resource bundle to set
+     *            the resource bundle to set, may be {@code null}.
      */
     public void setResourceBundle(ResourceBundle resourceBundle) {
         this.resourceBundle = resourceBundle;
@@ -304,7 +311,8 @@
     /**
      * Gets the name of the resource bundle.
      * 
-     * @return the name of the resource bundle
+     * @return the name of the resource bundle, {@code null} if none is
+     *         available or the message is not localizable.
      */
     public String getResourceBundleName() {
         return resourceBundleName;
@@ -314,7 +322,7 @@
      * Sets the name of the resource bundle.
      * 
      * @param resourceBundleName
-     *            the name of the resource bundle to set
+     *            the name of the resource bundle to set.
      */
     public void setResourceBundleName(String resourceBundleName) {
         this.resourceBundleName = resourceBundleName;
@@ -323,28 +331,29 @@
     /**
      * Gets the sequence number.
      * 
-     * @return the sequence number
+     * @return the sequence number.
      */
     public long getSequenceNumber() {
         return sequenceNumber;
     }
 
     /**
-     * Sets the sequence number. It is usually unnecessary to call this method
+     * Sets the sequence number. It is usually not necessary to call this method
      * to change the sequence number because the number is allocated when this
      * instance is constructed.
      * 
      * @param sequenceNumber
-     *            the sequence number to set
+     *            the sequence number to set.
      */
     public void setSequenceNumber(long sequenceNumber) {
         this.sequenceNumber = sequenceNumber;
     }
 
     /**
-     * Gets the name of the class that issued the logging call.
+     * Gets the name of the class that is the source of this log record. This
+     * information can be changed, may be {@code null} and is untrusted.
      * 
-     * @return the name of the class that issued the logging call
+     * @return the name of the source class of this log record (possiblity {@code null})
      */
     public String getSourceClassName() {
         initSource();
@@ -352,7 +361,7 @@
     }
 
     /*
-     * Init the sourceClass and sourceMethod fields.
+     *  Init the sourceClass and sourceMethod fields.
      */
     private void initSource() {
         if (!sourceInited) {
@@ -378,10 +387,11 @@
     }
 
     /**
-     * Sets the name of the class that issued the logging call.
+     * Sets the name of the class that is the source of this log record.
      * 
      * @param sourceClassName
-     *            the name of the class that issued the logging call
+     *            the name of the source class of this log record, may be
+     *            {@code null}.
      */
     public void setSourceClassName(String sourceClassName) {
         sourceInited = true;
@@ -389,9 +399,9 @@
     }
 
     /**
-     * Gets the name of the method that issued the logging call.
+     * Gets the name of the method that is the source of this log record.
      * 
-     * @return the name of the method that issued the logging call
+     * @return the name of the source method of this log record.
      */
     public String getSourceMethodName() {
         initSource();
@@ -399,10 +409,11 @@
     }
 
     /**
-     * Sets the name of the method that issued the logging call.
+     * Sets the name of the method that is the source of this log record.
      * 
      * @param sourceMethodName
-     *            the name of the method that issued the logging call
+     *            the name of the source method of this log record, may be
+     *            {@code null}.
      */
     public void setSourceMethodName(String sourceMethodName) {
         sourceInited = true;
@@ -410,40 +421,43 @@
     }
 
     /**
-     * Gets the ID of the thread originating the message.
+     * Gets a unique ID of the thread originating the log record. Every thread
+     * becomes a different ID.
+     * <p>
+     * Notice : the ID doesn't necessary map the OS thread ID
+     * </p>
      * 
-     * @return the ID of the thread originating the message
+     * @return the ID of the thread originating this log record.
      */
     public int getThreadID() {
         return threadID;
     }
 
     /**
-     * Sets the ID of the thread originating the message.
+     * Sets the ID of the thread originating this log record.
      * 
      * @param threadID
-     *            the ID of the thread originating the message
+     *            the new ID of the thread originating this log record.
      */
     public void setThreadID(int threadID) {
         this.threadID = threadID;
     }
 
     /**
-     * Gets the <code>Throwable</code> object associated with this log record.
+     * Gets the {@code Throwable} object associated with this log record.
      * 
-     * @return the <code>Throwable</code> object associated with this log
-     *         record
+     * @return the {@code Throwable} object associated with this log record.
      */
     public Throwable getThrown() {
         return thrown;
     }
 
     /**
-     * Sets the <code>Throwable</code> object associated with this log record.
+     * Sets the {@code Throwable} object associated with this log record.
      * 
      * @param thrown
-     *            the <code>Throwable</code> object associated with this log
-     *            record
+     *            the new {@code Throwable} object to associate with this log
+     *            record.
      */
     public void setThrown(Throwable thrown) {
         this.thrown = thrown;



Mime
View raw message