You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by qi...@apache.org on 2009/04/26 14:30:06 UTC
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...
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;