harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [7/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/co...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Handler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Handler.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Handler.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Handler.java Sun Apr 26 12:30:01 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/branches/java6/modules/logging/src/main/java/java/util/logging/Level.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Level.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Level.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Level.java Sun Apr 26 12:30:01 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/branches/java6/modules/logging/src/main/java/java/util/logging/LogManager.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogManager.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogManager.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogManager.java Sun Apr 26 12:30:01 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/branches/java6/modules/logging/src/main/java/java/util/logging/LogRecord.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogRecord.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogRecord.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LogRecord.java Sun Apr 26 12:30:01 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