harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [8/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/Logger.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Logger.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Logger.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/Logger.java Sun Apr 26 12:30:01 2009
@@ -32,43 +32,37 @@
  * etc. They use various handlers to actually do the output-dependent
  * operations.
  * <p>
- * Client applications can get named loggers by calling the methods
- * <code>getLogger</code>. They can also get anonymous loggers by calling the
- * methods <code>getAnonymousLogger</code>. Named loggers are organized in a
+ * Client applications can get named loggers by calling the {@code getLogger}
+ * methods. They can also get anonymous loggers by calling the
+ * {@code getAnonymousLogger} methods. Named loggers are organized in a
  * namespace hierarchy managed by a log manager. The naming convention is
- * usually the same as java package's naming convention, i.e., using
+ * usually the same as java package's naming convention, that is using
  * dot-separated strings. Anonymous loggers do not belong to any namespace.
- * </p>
  * <p>
- * Loggers "inherit" log level setting from their parent if its own level is set
- * to <code>null</code>. This is also true for the resource bundle. The
- * logger's resource bundle is used to localize the log messages if no resource
- * bundle name is given when a log method is called. If
- * <code>getUseParentHandlers</code> is <code>true</code>, loggers also
- * inherit their parent's handlers. Here "inherit" only means the "behaviors"
- * are inherited. The internal fields value will not change, for example,
- * <code>getLevel()</code> still returns <code>null</code>.
- * </p>
+ * Loggers "inherit" log level setting from their parent if their own level is
+ * set to {@code null}. This is also true for the resource bundle. The logger's
+ * resource bundle is used to localize the log messages if no resource bundle
+ * name is given when a log method is called. If {@code getUseParentHandlers()}
+ * returns {@code true}, loggers also inherit their parent's handlers. In this
+ * context, "inherit" only means that "behavior" is inherited. The internal
+ * field values will not change, for example, {@code getLevel()} still returns
+ * {@code null}.
  * <p>
  * When loading a given resource bundle, the logger first tries to use the
  * context classloader. If that fails, it tries the system classloader. And if
  * that still fails, it searches up the class stack and uses each class's
  * classloader to try to locate the resource bundle.
- * </p>
  * <p>
  * Some log methods accept log requests that do not specify the source class and
  * source method. In these cases, the logging framework will automatically infer
- * the calling class and method, but not guaranteed to be accurate.
- * </p>
+ * the calling class and method, but this is not guaranteed to be accurate.
  * <p>
- * Once a <code>LogRecord</code> object has been passed into the logging
- * framework, it is owned by the logging framework and the client applications
- * should not use it any longer.
- * </p>
+ * Once a {@code LogRecord} object has been passed into the logging framework,
+ * it is owned by the logging framework and the client applications should not
+ * use it any longer.
  * <p>
  * All methods of this class are thread-safe.
- * </p>
- * 
+ *
  * @see LogManager
  */
 public class Logger {
@@ -126,16 +120,19 @@
     private boolean handlerInited;
 
     /**
-     * Constructs a <code>Logger</code> object with the supplied name and
-     * resource bundle name.
-     * 
+     * Constructs a {@code Logger} object with the supplied name and resource
+     * bundle name; {@code notifiyParentHandlers} is set to {@code true}.
+     * <p>
+     * Notice : Loggers use a naming hierarchy. Thus "z.x.y" is a child of "z.x".
+     *
      * @param name
-     *            the name of this logger, may be null for anonymous loggers
+     *            the name of this logger, may be {@code null} for anonymous
+     *            loggers.
      * @param resourceBundleName
      *            the name of the resource bundle used to localize logging
-     *            messages, may be null
+     *            messages, may be {@code null}.
      * @throws MissingResourceException
-     *             If the specified resource bundle can not be loaded.
+     *             if the specified resource bundle can not be loaded.
      */
     protected Logger(String name, String resourceBundleName) {
         // try to load the specified resource bundle first
@@ -193,10 +190,10 @@
      * Load the specified resource bundle, use privileged code.
      * 
      * @param resourceBundleName
-     *            the name of the resource bundle to load, cannot be null
+     *            the name of the resource bundle to load, cannot be {@code null}.
      * @return the loaded resource bundle.
      * @throws MissingResourceException
-     *             If the specified resource bundle can not be loaded.
+     *             if the specified resource bundle can not be loaded.
      */
     static ResourceBundle loadResourceBundle(String resourceBundleName) {
         // try context class loader to load the resource
@@ -263,14 +260,12 @@
     /**
      * Gets an anonymous logger to use internally in a thread. Anonymous loggers
      * are not registered in the log manager's namespace. No security checks
-     * will be performed when updating an anonymous logger's control settings so
-     * that they can be used in applets.
+     * will be performed when updating an anonymous logger's control settings.
      * <p>
-     * Anonymous loggers' parent is set to be the root logger. This enables them
-     * to inherit default logging level and handlers from the root logger.
-     * </p>
-     * 
-     * @return a new instance of anonymous logger
+     * The anonymous loggers' parent is set to be the root logger. This way it
+     * inherits the default logging level and handlers from the root logger.
+     *
+     * @return a new instance of anonymous logger.
      */
     public static Logger getAnonymousLogger() {
         return getAnonymousLogger(null);
@@ -282,15 +277,14 @@
      * will be performed when updating an anonymous logger's control settings so
      * that they can be used in applets.
      * <p>
-     * Anonymous loggers' parent is set to be the root logger. This enables them
-     * to inherit default logging level and handlers from the root logger.
-     * </p>
-     * 
+     * The anonymous loggers' parent is set to be the root logger. This way it
+     * inherits default logging level and handlers from the root logger.
+     *
      * @param resourceBundleName
-     *            the name of the resource bundle used to localize log messages
-     * @return a new instance of anonymous logger
+     *            the name of the resource bundle used to localize log messages.
+     * @return a new instance of anonymous logger.
      * @throws MissingResourceException
-     *             If the specified resource bundle can not be loaded.
+     *             if the specified resource bundle can not be loaded.
      */
     public static Logger getAnonymousLogger(String resourceBundleName) {
         final Logger l = new Logger(null, resourceBundleName);
@@ -300,8 +294,9 @@
     }
 
     /*
-     * Check whether the same resource bundle has been specified. Synchronize to
-     * ensure the consistency between resource bundle and its name.
+     * Check whether the same resource bundle has been specified.
+     * Synchronize to ensure the consistency between resource bundle
+     * and its name.
      */
     private static void updateResourceBundle(Logger l, String resourceBundleName) {
         synchronized (l) {
@@ -355,13 +350,13 @@
     }
 
     /**
-     * Gets a named logger. The returned logger may already exist, or may be
-     * newly created. If the latter, its level will be set to the configured
-     * level according to the <code>LogManager</code>'s properties if any.
+     * Gets a named logger. The returned logger may already exist or may be
+     * newly created. In the latter case, its level will be set to the
+     * configured level according to the {@code LogManager}'s properties.
      * 
      * @param name
-     *            the name of the logger to get, cannot be null
-     * @return a named logger
+     *            the name of the logger to get, cannot be {@code null}.
+     * @return a named logger.
      * @throws MissingResourceException
      *             If the specified resource bundle can not be loaded.
      */
@@ -374,23 +369,29 @@
      * resource bundle will be used to localize logging messages.
      * 
      * @param name
-     *            the name of the logger to get, cannot be null
+     *            the name of the logger to get, cannot be {@code null}.
      * @param resourceBundleName
-     *            the name of the resource bundle, may be null
-     * @return a named logger
+     *            the name of the resource bundle, may be {@code null}.
+     * @throws IllegalArgumentException
+     *             if the logger identified by {@code name} is associated with a
+     *             resource bundle and its name is not equal to
+     *             {@code resourceBundleName}.
+     * @throws MissingResourceException
+     *             if the name of the resource bundle cannot be found.
+     * @return a named logger.
      */
     public static Logger getLogger(String name, String resourceBundleName) {
         return getLoggerWithRes(name, resourceBundleName, true);
     }
 
     /**
-     * Adds a handler to this logger. The handler will be fed with log records
-     * received by this logger.
+     * Adds a handler to this logger. The {@code name} will be fed with log
+     * records received by this logger.
      * 
      * @param handler
-     *            the handler object to add, cannot be null
+     *            the handler object to add, cannot 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 addHandler(Handler handler) {
@@ -409,9 +410,9 @@
     }
 
     /*
-     * Be cautious to avoid deadlock when using this method, it gets lock on
-     * manager at first, and then gets lock on this Logger, so any methods
-     * should not hold lock on this Logger when invoking this method.
+     * Be cautious to avoid deadlock when using this method, it gets lock on manager
+     * at first, and then gets lock on this Logger, so any methods should not hold
+     * lock on this Logger when invoking this method.
      */
     private void initHandler() {
         if (!handlerInited) {
@@ -453,7 +454,7 @@
     /**
      * Gets all the handlers associated with this logger.
      * 
-     * @return an array of all the handlers associated with this logger
+     * @return an array of all the handlers associated with this logger.
      */
     public Handler[] getHandlers() {
         initHandler();
@@ -463,13 +464,13 @@
     }
 
     /**
-     * Removes a handler for this logger. If the specified handler does not
-     * exist, this method has no effect.
+     * Removes a handler from this logger. If the specified handler does not
+     * exist then this method has no effect.
      * 
      * @param handler
-     *            the handler to be removed, cannot be null
+     *            the handler to be removed.
      * @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 removeHandler(Handler handler) {
@@ -489,7 +490,7 @@
     /**
      * Gets the filter used by this logger.
      * 
-     * @return the filter used by this logger
+     * @return the filter used by this logger, may be {@code null}.
      */
     public Filter getFilter() {
         return this.filter;
@@ -499,9 +500,9 @@
      * Sets the filter used by this logger.
      * 
      * @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) {
@@ -513,22 +514,23 @@
     }
 
     /**
-     * Gets the logging level of this logger.
+     * Gets the logging level of this logger. A {@code null} level indicates
+     * that this logger inherits its parent's level.
      * 
-     * @return the logging level of this logger
+     * @return the logging level of this logger.
      */
     public Level getLevel() {
         return levelObjVal;
     }
 
     /**
-     * Sets the logging level for this logger. A <code>null</code> level
-     * indicates this logger will inherit its parent's level.
+     * Sets the logging level for this logger. A {@code null} level indicates
+     * that this logger will inherit its parent's level.
      * 
      * @param newLevel
-     *            the logging level to set
+     *            the logging level 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.
      */
     public void setLevel(Level newLevel) {
@@ -542,24 +544,25 @@
     }
 
     /**
-     * Gets the flag which indicates whether to use parent's handlers to publish
-     * incoming log records, potentially recursively up the namespace.
+     * Gets the flag which indicates whether to use the handlers of this
+     * logger's parent to publish incoming log records, potentially recursively
+     * up the namespace.
      * 
-     * @return <code>true</code> if set to use parent's handlers, otherwise
-     *         <code>false</code>
+     * @return {@code true} if set to use parent's handlers, {@code false}
+     *         otherwise.
      */
     public boolean getUseParentHandlers() {
         return this.notifyParentHandlers;
     }
 
     /**
-     * Sets the flag which indicates whether to use parent's handlers to publish
-     * incoming log records, potentially recursively up the namespace.
+     * Sets the flag which indicates whether to use the handlers of this
+     * logger's parent, potentially recursively up the namespace.
      * 
      * @param notifyParentHandlers
-     *            the flag whether to use parent's handlers
+     *            the new flag indicating whether to use the parent's handlers.
      * @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 setUseParentHandlers(boolean notifyParentHandlers) {
@@ -571,9 +574,10 @@
     }
 
     /**
-     * Gets the parent of this logger in the namespace.
+     * Gets the nearest parent of this logger in the namespace, a {@code null}
+     * value will be returned if called on the root logger.
      * 
-     * @return the parent of this logger in the namespace
+     * @return the parent of this logger in the namespace.
      */
     public Logger getParent() {
         return parent;
@@ -581,11 +585,11 @@
 
     /**
      * Sets the parent of this logger in the namespace. This method should
-     * usually be used by the <code>LogManager</code> object only. This method
-     * does not check security.
+     * usually be used by the {@code LogManager} object only. This method does
+     * not check security.
      * 
      * @param newParent
-     *            the parent logger to set
+     *            the parent logger to set.
      */
     void internalSetParent(Logger newParent) {
         // All hierarchy related modifications should get LogManager lock at
@@ -602,13 +606,13 @@
     }
 
     /**
-     * Sets the parent of this logger in the namespace. This method should
-     * usually be used by the <code>LogManager</code> object only.
+     * Sets the parent of this logger in the namespace. This method should be
+     * used by the {@code LogManager} object only.
      * 
      * @param parent
-     *            the parent logger to set
+     *            the parent logger 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.
      */
     public void setParent(Logger parent) {
@@ -630,9 +634,9 @@
     }
 
     /**
-     * Gets the name of this logger.
+     * Gets the name of this logger, {@code null} for anonymous loggers.
      * 
-     * @return the name of this logger
+     * @return the name of this logger.
      */
     public String getName() {
         return this.name;
@@ -640,9 +644,10 @@
 
     /**
      * Gets the loaded resource bundle used by this logger to localize logging
-     * messages. If it's null, the parent's resource bundle will be inherited.
+     * messages. If the value is {@code null}, the parent's resource bundle will be
+     * inherited.
      * 
-     * @return the loaded resource bundle used by this logger
+     * @return the loaded resource bundle used by this logger.
      */
     public ResourceBundle getResourceBundle() {
         return this.resBundle;
@@ -650,10 +655,10 @@
 
     /**
      * Gets the name of the loaded resource bundle used by this logger to
-     * localize logging messages. If it's null, the parent's resource bundle
-     * name will be inherited.
+     * localize logging messages. If the value is {@code null}, the parent's resource
+     * bundle name will be inherited.
      * 
-     * @return the name of the loaded resource bundle used by this logger
+     * @return the name of the loaded resource bundle used by this logger.
      */
     public String getResourceBundleName() {
         return this.resBundleName;
@@ -677,12 +682,12 @@
     /**
      * Determines whether this logger will actually log messages of the
      * specified level. The effective level used to do the determination may be
-     * inherited from its parent. The default level is <code>Level.INFO</code>.
+     * inherited from its parent. The default level is {@code Level.INFO}.
      * 
      * @param l
-     *            the level to check
-     * @return <code>true</code> if this logger will actually log this level,
-     *         otherwise <code>false</code>
+     *            the level to check.
+     * @return {@code true} if this logger will actually log this level,
+     *         otherwise {@code false}.
      */
     public boolean isLoggable(Level l) {
         return internalIsLoggable(l);
@@ -715,14 +720,14 @@
     }
 
     /**
-     * Logs a message indicating entering a method. A log record with log level
-     * <code>Level.FINER</code>, log message "ENTRY", and the specified
+     * Logs a message indicating that a method has been entered. A log record
+     * with log level {@code Level.FINER}, log message "ENTRY", the specified
      * source class name and source method name is submitted for logging.
      * 
      * @param sourceClass
-     *            the calling class name
+     *            the calling class name.
      * @param sourceMethod
-     *            the method name
+     *            the method name.
      */
     public void entering(String sourceClass, String sourceMethod) {
         if (internalIsLoggable(Level.FINER)) {
@@ -736,17 +741,17 @@
     }
 
     /**
-     * Logs a message indicating entering a method. A log record with log level
-     * <code>Level.FINER</code>, log message "ENTRY", and the specified
-     * source class name and source method name and one parameter is submitted
-     * for logging.
+     * Logs a message indicating that a method has been entered. A log record
+     * with log level {@code Level.FINER}, log message "ENTRY", the specified
+     * source class name, source method name and one parameter is submitted for
+     * logging.
      * 
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param param
-     *            the parameter for the method call
+     *            the parameter for the method call.
      */
     public void entering(String sourceClass, String sourceMethod, Object param) {
         if (internalIsLoggable(Level.FINER)) {
@@ -761,17 +766,17 @@
     }
 
     /**
-     * Logs a message indicating entering a method. A log record with log level
-     * <code>Level.FINER</code>, log message "ENTRY", and the specified
-     * source class name and source method name and parameters is submitted for
-     * logging.
+     * Logs a message indicating that a method has been entered. A log record
+     * with log level {@code Level.FINER}, log message "ENTRY", the specified
+     * source class name, source method name and array of parameters is
+     * submitted for logging.
      * 
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param params
-     *            an array of parameters for the method call
+     *            an array of parameters for the method call.
      */
     public void entering(String sourceClass, String sourceMethod,
             Object[] params) {
@@ -795,14 +800,14 @@
     }
 
     /**
-     * Logs a message indicating existing a method. A log record with log level
-     * <code>Level.FINER</code>, log message "RETURN", and the specified
-     * source class name and source method name is submitted for logging.
+     * Logs a message indicating that a method is exited. A log record with log
+     * level {@code Level.FINER}, log message "RETURN", the specified source
+     * class name and source method name is submitted for logging.
      * 
      * @param sourceClass
-     *            the calling class name
+     *            the calling class name.
      * @param sourceMethod
-     *            the method name
+     *            the method name.
      */
     public void exiting(String sourceClass, String sourceMethod) {
         if (internalIsLoggable(Level.FINER)) {
@@ -816,17 +821,16 @@
     }
 
     /**
-     * Logs a message indicating exiting a method. A log record with log level
-     * <code>Level.FINER</code>, log message "RETURN", and the specified
-     * source class name and source method name and return value is submitted
-     * for logging.
+     * Logs a message indicating that a method is exited. A log record with log
+     * level {@code Level.FINER}, log message "RETURN", the specified source
+     * class name, source method name and return value is submitted for logging.
      * 
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param result
-     *            the return value of the method call
+     *            the return value of the method call.
      */
     public void exiting(String sourceClass, String sourceMethod, Object result) {
         if (internalIsLoggable(Level.FINER)) {
@@ -841,17 +845,17 @@
     }
 
     /**
-     * Logs a message indicating throwing an exception. A log record with log
-     * level <code>Level.FINER</code>, log message "THROW", and the specified
-     * source class name and source method name and <code>Throwable</code>
-     * object is submitted for logging.
+     * Logs a message indicating that an exception is thrown. A log record with
+     * log level {@code Level.FINER}, log message "THROW", the specified source
+     * class name, source method name and the {@code Throwable} object is
+     * submitted for logging.
      * 
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param thrown
-     *            the <code>Throwable</code> object
+     *            the {@code Throwable} object.
      */
     public void throwing(String sourceClass, String sourceMethod,
             Throwable thrown) {
@@ -867,10 +871,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.SEVERE</code>.
+     * Logs a message of level {@code Level.SEVERE}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void severe(String msg) {
         if (internalIsLoggable(Level.SEVERE)) {
@@ -882,10 +887,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.WARNING</code>.
+     * Logs a message of level {@code Level.WARNING}; the message is
+     * transmitted to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void warning(String msg) {
         if (internalIsLoggable(Level.WARNING)) {
@@ -897,10 +903,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.INFO</code>.
+     * Logs a message of level {@code Level.INFO}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void info(String msg) {
         if (internalIsLoggable(Level.INFO)) {
@@ -912,10 +919,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.CONFIG</code>.
+     * Logs a message of level {@code Level.CONFIG}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void config(String msg) {
         if (internalIsLoggable(Level.CONFIG)) {
@@ -927,10 +935,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.FINE</code>.
+     * Logs a message of level {@code Level.FINE}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void fine(String msg) {
         if (internalIsLoggable(Level.FINE)) {
@@ -942,10 +951,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.FINER</code>.
+     * Logs a message of level {@code Level.FINER}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void finer(String msg) {
         if (internalIsLoggable(Level.FINER)) {
@@ -957,10 +967,11 @@
     }
 
     /**
-     * Logs a message of level <code>Level.FINEST</code>.
+     * Logs a message of level {@code Level.FINEST}; the message is transmitted
+     * to all subscribed handlers.
      * 
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void finest(String msg) {
         if (internalIsLoggable(Level.FINEST)) {
@@ -972,12 +983,13 @@
     }
 
     /**
-     * Logs a message of the specified level.
+     * Logs a message of the specified level. The message is transmitted to all
+     * subscribed handlers.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the specified message.
      * @param msg
-     *            the message to log
+     *            the message to log.
      */
     public void log(Level logLevel, String msg) {
         if (internalIsLoggable(logLevel)) {
@@ -989,14 +1001,15 @@
     }
 
     /**
-     * Logs a message of the specified level with the supplied parameter.
+     * Logs a message of the specified level with the supplied parameter. The
+     * message is then transmitted to all subscribed handlers.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param msg
-     *            the message to log
+     *            the message to log.
      * @param param
-     *            the parameter associated with the event that need to be logged
+     *            the parameter associated with the event that is logged.
      */
     public void log(Level logLevel, String msg, Object param) {
         if (internalIsLoggable(logLevel)) {
@@ -1010,14 +1023,14 @@
 
     /**
      * Logs a message of the specified level with the supplied parameter array.
-     * 
+     * The message is then transmitted to all subscribed handlers.
+     *
      * @param logLevel
      *            the level of the given message
      * @param msg
-     *            the message to log
+     *            the message to log.
      * @param params
-     *            the parameter array associated with the event that need to be
-     *            logged
+     *            the parameter array associated with the event that is logged.
      */
     public void log(Level logLevel, String msg, Object[] params) {
         if (internalIsLoggable(logLevel)) {
@@ -1030,16 +1043,16 @@
     }
 
     /**
-     * Logs a message of the specified level with the supplied
-     * <code>Throwable</code> object.
+     * Logs a message of the specified level with the supplied {@code Throwable}
+     * object. The message is then transmitted to all subscribed handlers.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param msg
-     *            the message to log
+     *            the message to log.
      * @param thrown
-     *            the <code>Throwable</code> object associated with the event
-     *            that need to be logged
+     *            the {@code Throwable} object associated with the event that is
+     *            logged.
      */
     public void log(Level logLevel, String msg, Throwable thrown) {
         if (internalIsLoggable(logLevel)) {
@@ -1052,11 +1065,11 @@
     }
 
     /**
-     * Logs a given log record. Only those with a logging level no lower than
-     * this logger's level will be submitted to this logger's handlers for
-     * logging. If <code>getUseParentHandlers()</code> is <code>true</code>,
-     * the log record will also be submitted to the parent logger's handlers,
-     * potentially recursively up the namespace.
+     * Logs a given log record. Only records with a logging level that is equal
+     * or greater than this logger's level will be submitted to this logger's
+     * handlers for logging. If {@code getUseParentHandlers()} returns {@code
+     * true}, the log record will also be submitted to the handlers of this
+     * logger's parent, potentially recursively up the namespace.
      * <p>
      * Since all other log methods call this method to actually perform the
      * logging action, subclasses of this class can override this method to
@@ -1064,7 +1077,7 @@
      * </p>
      * 
      * @param record
-     *            the log record to be logged
+     *            the log record to be logged.
      */
     public void log(LogRecord record) {
         if (internalIsLoggable(record.getLevel())) {
@@ -1100,13 +1113,13 @@
      * and source method name.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      */
     public void logp(Level logLevel, String sourceClass, String sourceMethod,
             String msg) {
@@ -1121,8 +1134,8 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and parameter.
+     * Logs a message of the given level with the specified source class name,
+     * source method name and parameter.
      * 
      * @param logLevel
      *            the level of the given message
@@ -1133,7 +1146,7 @@
      * @param msg
      *            the message to be logged
      * @param param
-     *            the parameter associated with the event that need to be logged
+     *            the parameter associated with the event that is logged.
      */
     public void logp(Level logLevel, String sourceClass, String sourceMethod,
             String msg, Object param) {
@@ -1149,20 +1162,19 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and parameter array.
+     * Logs a message of the given level with the specified source class name,
+     * source method name and parameter array.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      * @param params
-     *            the parameter array associated with the event that need to be
-     *            logged
+     *            the parameter array associated with the event that is logged.
      */
     public void logp(Level logLevel, String sourceClass, String sourceMethod,
             String msg, Object[] params) {
@@ -1178,19 +1190,19 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and <code>Throwable</code> object.
+     * Logs a message of the given level with the specified source class name,
+     * source method name and {@code Throwable} object.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      * @param thrown
-     *            the <code>Throwable</code> object
+     *            the {@code Throwable} object.
      */
     public void logp(Level logLevel, String sourceClass, String sourceMethod,
             String msg, Throwable thrown) {
@@ -1208,18 +1220,19 @@
     /**
      * Logs a message of the given level with the specified source class name
      * and source method name, using the given resource bundle to localize the
-     * message.
+     * message. If {@code bundleName} is null, the empty string or not valid then
+     * the message is not localized.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param bundleName
-     *            the name of the resource bundle, used to localize the message
+     *            the name of the resource bundle used to localize the message.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      */
     public void logrb(Level logLevel, String sourceClass, String sourceMethod,
             String bundleName, String msg) {
@@ -1241,22 +1254,23 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and parameter, using the given resource bundle to
-     * localize the message.
-     * 
+     * Logs a message of the given level with the specified source class name,
+     * source method name and parameter, using the given resource bundle to
+     * localize the message. If {@code bundleName} is null, the empty string
+     * or not valid then the message is not localized.
+     *
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param bundleName
-     *            the name of the resource bundle, used to localize the message
+     *            the name of the resource bundle used to localize the message.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      * @param param
-     *            the parameter associated with the event that need to be logged
+     *            the parameter associated with the event that is logged.
      */
     public void logrb(Level logLevel, String sourceClass, String sourceMethod,
             String bundleName, String msg, Object param) {
@@ -1279,23 +1293,23 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and parameter array, using the given resource
-     * bundle to localize the message.
+     * Logs a message of the given level with the specified source class name,
+     * source method name and parameter array, using the given resource bundle
+     * to localize the message. If {@code bundleName} is null, the empty string
+     * or not valid then the message is not localized.
      * 
      * @param logLevel
-     *            the level of the given message
+     *            the level of the given message.
      * @param sourceClass
-     *            the source class name
+     *            the source class name.
      * @param sourceMethod
-     *            the source method name
+     *            the source method name.
      * @param bundleName
-     *            the name of the resource bundle, used to localize the message
+     *            the name of the resource bundle used to localize the message.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      * @param params
-     *            the parameter array associated with the event that need to be
-     *            logged
+     *            the parameter array associated with the event that is logged.
      */
     public void logrb(Level logLevel, String sourceClass, String sourceMethod,
             String bundleName, String msg, Object[] params) {
@@ -1318,9 +1332,10 @@
     }
 
     /**
-     * Logs a message of the given level with the specified source class name
-     * and source method name and <code>Throwable</code> object, using the
-     * given resource bundle to localize the message.
+     * Logs a message of the given level with the specified source class name,
+     * source method name and {@code Throwable} object, using the given resource
+     * bundle to localize the message. If {@code bundleName} is null, the empty
+     * string or not valid then the message is not localized.
      * 
      * @param logLevel
      *            the level of the given message
@@ -1329,11 +1344,11 @@
      * @param sourceMethod
      *            the source method name
      * @param bundleName
-     *            the name of the resource bundle, used to localize the message
+     *            the name of the resource bundle used to localize the message.
      * @param msg
-     *            the message to be logged
+     *            the message to be logged.
      * @param thrown
-     *            the <code>Throwable</code> object
+     *            the {@code Throwable} object.
      */
     public void logrb(Level logLevel, String sourceClass, String sourceMethod,
             String bundleName, String msg, Throwable thrown) {

Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingMXBean.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingMXBean.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingMXBean.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingMXBean.java Sun Apr 26 12:30:01 2009
@@ -20,10 +20,10 @@
 import java.util.List;
 
 /**
- * The management interface for the logging sub-system.
+ * {@code LoggingMXBean} is the management interface for the logging sub-system.
  * <p>
- * ObjectName =
- * {@link LogManager#LOGGING_MXBEAN_NAME java.util.logging:type=Logging}
+ * The ObjectName for identifying the {@code LoggingMXBean} in a bean server is
+ * {@link LogManager#LOGGING_MXBEAN_NAME}.
  * </p>
  * 
  * @since 1.5
@@ -31,46 +31,48 @@
 public interface LoggingMXBean {
 
     /**
-     * Gets the String value of the logging level of a logger. An empty String
-     * is returned when the logger's level is defined by its parent.
+     * Gets the string value of the logging level of a logger. An empty string
+     * is returned when the logger's level is defined by its parent. A
+     * {@code null} is returned if the specified logger does not exist.
      * 
      * @param loggerName
-     *            The name of the logger lookup.
-     * @return A String if the logger was found, otherwise <code>null</code>.
+     *            the name of the logger lookup.
+     * @return a {@code String} if the logger is found, otherwise {@code null}.
      * @see Level#getName()
      */
     String getLoggerLevel(String loggerName);
 
     /**
-     * Gets a list of all currently registered logger's names. This is performed
+     * Gets a list of all currently registered logger names. This is performed
      * using the {@link LogManager#getLoggerNames()}.
      * 
-     * @return A List of String instances.
+     * @return a list of logger names.
      */
     List<String> getLoggerNames();
 
     /**
      * Gets the name of the parent logger of a logger. If the logger doesn't
-     * exist then <code>null</code> is returned. If the logger is the root
-     * logger, then an empty String is returned.
+     * exist then {@code null} is returned. If the logger is the root logger,
+     * then an empty {@code String} is returned.
      * 
      * @param loggerName
-     *            The name of the logger to lookup.
-     * @return A String if the logger was found, otherwise <code>null</code>.
+     *            the name of the logger to lookup.
+     * @return a {@code String} if the logger was found, otherwise {@code null}.
      */
     String getParentLoggerName(String loggerName);
 
     /**
-     * Sets the log level of a logger.
+     * Sets the log level of a logger. LevelName set to {@code null} means the
+     * level is inherited from the nearest non-null ancestor.
      * 
      * @param loggerName
-     *            The name of the logger to set the level on, which must not be
-     *            <code>null</code>.
+     *            the name of the logger to set the level on, which must not be
+     *            {@code null}.
      * @param levelName
-     *            The level to set on the logger, which may be <code>null</code>.
+     *            the level to set on the logger, which may be {@code null}.
      * @throws IllegalArgumentException
-     *             if <code>loggerName</code> is not a registered logger or if
-     *             <code>levelName</code> is not null and an invalid value.
+     *             if {@code loggerName} is not a registered logger or if
+     *             {@code levelName} is not null and not valid.
      * @throws SecurityException
      *             if a security manager exists and the caller doesn't have
      *             LoggingPermission("control").

Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingPermission.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingPermission.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/LoggingPermission.java Sun Apr 26 12:30:01 2009
@@ -25,7 +25,7 @@
 
 /**
  * The permission required to control the logging when run with a
- * <code>SecurityManager</code>.
+ * {@code SecurityManager}.
  */
 public final class LoggingPermission extends BasicPermission implements Guard,
         Serializable {
@@ -34,14 +34,20 @@
     private static final long serialVersionUID = 63564341580231582L;
 
     /**
-     * Constructs a <code>LoggingPermission</code> object required to control
-     * the logging.
+     * Constructs a {@code LoggingPermission} object required to control the
+     * logging. The {@code SecurityManager} checks the permissions.
+     * <p>
+     * {@code LoggingPermission} objects are created by the security policy code
+     * and depends on the security policy file, therefore programmers shouldn't
+     * normally use them directly.
+     * </p>
      * 
      * @param name
-     *            Currently must be "control".
+     *            currently must be "control".
      * @param actions
-     *            Currently must be either <code>null</code> or the empty
-     *            string.
+     *            currently must be either {@code null} or the empty string.
+     * @throws IllegalArgumentException
+     *             if name null or different from {@code string} control.
      */
     public LoggingPermission(String name, String actions) {
         super(name, actions);

Modified: harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/MemoryHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/MemoryHandler.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/MemoryHandler.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/logging/src/main/java/java/util/logging/MemoryHandler.java Sun Apr 26 12:30:01 2009
@@ -23,45 +23,39 @@
 import org.apache.harmony.logging.internal.nls.Messages;
 
 /**
- * <code>MemoryHandler</code> is a <code>Handler</code> that 'remembers' a
- * finite number of <code>LogRecord</code>s at a time and stores them in a
- * buffer without formatting them. When the buffer is full this
- * <code>Handler</code> overwrites the oldest record as each new record is
- * added.
- * 
+ * A {@code Handler} put the description of log events into a cycled memory
+ * buffer.
  * <p>
- * Every <code>MemoryHandler</code> has a target <code>Handler</code>, and
- * calling the <code>push()</code> method on the <code>MemoryHandler</code>
- * will output all buffered records to the target <code>Handler</code> After
- * the push action, the buffer will be cleared.
- * </p>
- * 
+ * Mostly this {@code MemoryHandler} just puts the given {@code LogRecord} into
+ * the internal buffer and doesn't perform any formatting or any other process.
+ * When the buffer is full, the earliest buffered records will be discarded.
+ * <p>
+ * Every {@code MemoryHandler} has a target handler, and push action can be
+ * triggered so that all buffered records will be output to the target handler
+ * and normally the latter will publish the records. After the push action, the
+ * buffer will be cleared.
  * <p>
  * The push method can be called directly, but will also be called automatically
  * if a new <code>LogRecord</code> is added that has a level greater than or
  * equal to than the value defined for the property
  * java.util.logging.MemoryHandler.push.
- * </p>
- * 
  * <p>
- * <code>MemoryHandler</code> defines the following configuration properties,
- * which are read by the <code>LogManager</code> on initialization. If the
- * properties have not been specified then defaults will be used. The properties
- * and defaults are as follows:
+ * {@code MemoryHandler} will read following {@code LogManager} properties for
+ * initialization, if given properties are not defined or has invalid values,
+ * default value will be used.
  * <ul>
- * <li>java.util.logging.MemoryHandler.filter - the <code>Filter</code> class
- * name. No <code>Filter</code> is used by default.</li>
- * <li>java.util.logging.MemoryHandler.level - the log level for this
- * <code>Handler</code>. Default is <code>Level.ALL</code>.</li>
- * <li>java.util.logging.MemoryHandler.push - the push level. Default is
- * <code>Level.SEVERE</code>.</li>
- * <li>java.util.logging.MemoryHandler.size - the buffer size in number of
- * <code>LogRecord</code>s. Default is 1000.</li>
- * <li>java.util.logging.MemoryHandler.target - the class name of the target
- * <code>Handler</code>. No default value, which means this property must be
+ * <li>java.util.logging.MemoryHandler.filter specifies the {@code Filter}
+ * class name, defaults to no {@code Filter}.</li>
+ * <li>java.util.logging.MemoryHandler.level specifies the level for this
+ * {@code Handler}, defaults to {@code Level.ALL}.</li>
+ * <li>java.util.logging.MemoryHandler.push specifies the push level, defaults
+ * to level.SEVERE.</li>
+ * <li>java.util.logging.MemoryHandler.size specifies the buffer size in number
+ * of {@code LogRecord}, defaults to 1000.</li>
+ * <li>java.util.logging.MemoryHandler.target specifies the class of the target
+ * {@code Handler}, no default value, which means this property must be
  * specified either by property setting or by constructor.</li>
  * </ul>
- * </p>
  */
 public class MemoryHandler extends Handler {
 
@@ -87,8 +81,12 @@
     private int cursor;
 
     /**
-     * Default constructor, construct and init a <code>MemoryHandler</code>
-     * using <code>LogManager</code> properties or default values
+     * Default constructor, construct and init a {@code MemoryHandler} using
+     * {@code LogManager} properties or default values.
+     *
+     * @throws RuntimeException
+     *             if property value are invalid and no default value could be
+     *             used.
      */
     public MemoryHandler() {
         super();
@@ -140,18 +138,22 @@
     }
 
     /**
-     * Construct and init a <code>MemoryHandler</code> using given target,
-     * size and push level, other properties using <code>LogManager</code>
-     * properties or default values
+     * Construct and init a {@code MemoryHandler} using given target, size and
+     * push level, other properties using {@code LogManager} properties or
+     * default values.
      * 
      * @param target
-     *            the given <code>Handler</code> to output
+     *            the given {@code Handler} to output
      * @param size
-     *            the maximum number of buffered <code>LogRecord</code>
+     *            the maximum number of buffered {@code LogRecord}, greater than
+     *            zero
      * @param pushLevel
      *            the push level
      * @throws IllegalArgumentException
-     *             if size<=0
+     *             if {@code size <= 0}
+     * @throws RuntimeException
+     *             if property value are invalid and no default value could be
+     *             used.
      */
     public MemoryHandler(Handler target, int size, Level pushLevel) {
         if (size <= 0) {
@@ -168,11 +170,11 @@
     }
 
     /**
-     * Close this handler and target handler, free all associated resources
+     * Close this handler and target handler, free all associated resources.
      * 
      * @throws SecurityException
      *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler
+     *             not have the required permissions to control this handler.
      */
     @Override
     public void close() {
@@ -182,9 +184,8 @@
     }
 
     /**
-     * Call target handler to flush any buffered output.
-     * 
-     * Note that this doesn't cause this <code>MemoryHandler</code> to push.
+     * Call target handler to flush any buffered output. Note that this doesn't
+     * cause this {@code MemoryHandler} to push.
      */
     @Override
     public void flush() {
@@ -192,15 +193,14 @@
     }
 
     /**
-     * Put a given <code>LogRecord</code> into internal buffer.
-     * 
-     * If given record is not loggable, just return. Otherwise it is stored in
-     * the buffer. Furthermore if the record's level is not less than the push
-     * level, the push action is triggered to output all the buffered records to
-     * the target handler, and the target handler will publish them.
+     * Put a given {@code LogRecord} into internal buffer. If given record is
+     * not loggable, just return. Otherwise it is stored in the buffer.
+     * Furthermore if the record's level is not less than the push level, the
+     * push action is triggered to output all the buffered records to the target
+     * handler, and the target handler will publish them.
      * 
      * @param record
-     *            the log record.
+     *            the log record
      */
     @Override
     public synchronized void publish(LogRecord record) {
@@ -227,19 +227,18 @@
     }
 
     /**
-     * Check if given <code>LogRecord</code> would be put into this
-     * <code>MemoryHandler</code>'s internal buffer.
+     * Check if given {@code LogRecord} would be put into this
+     * {@code MemoryHandler}'s internal buffer.
      * <p>
-     * The given <code>LogRecord</code> is loggable if and only if it has
-     * appropriate level and it pass any associated filter's check.
-     * </p>
+     * The given {@code LogRecord} is loggable if and only if it has appropriate
+     * level and it pass any associated filter's check.
      * <p>
      * Note that the push level is not used for this check.
-     * </p>
-     * 
+     *
      * @param record
-     *            the given <code>LogRecord</code>
-     * @return if the given <code>LogRecord</code> should be logged
+     *            the given {@code LogRecord}
+     * @return the given {@code LogRecord} if it should be logged, {@code false}
+     *         if {@code LogRecord} is {@code null}.
      */
     @Override
     public boolean isLoggable(LogRecord record) {
@@ -247,9 +246,8 @@
     }
 
     /**
-     * Triggers a push action to output all buffered records to the target
-     * handler, and the target handler will publish them. Then the buffer is
-     * cleared.
+     * Triggers a push action to output all buffered records to the target handler,
+     * and the target handler will publish them. Then the buffer is cleared.
      */
     public void push() {
         for (int i = cursor; i < size; i++) {
@@ -269,16 +267,15 @@
 
     /**
      * Set the push level. The push level is used to check the push action
-     * triggering. When a new <code>LogRecord</code> is put into the internal
+     * triggering. When a new {@code LogRecord} is put into the internal
      * buffer and its level is not less than the push level, the push action
-     * will be triggered. Note that set new push level won't trigger push
-     * action.
+     * will be triggered. Note that set new push level won't trigger push action.
      * 
      * @param newLevel
-     *            the new level to set
+     *                 the new level to set.
      * @throws SecurityException
-     *             if security manager exists and it determines that caller does
-     *             not have the required permissions to control this handler
+     *                 if security manager exists and it determines that caller
+     *                 does not have the required permissions to control this handler.
      */
     public void setPushLevel(Level newLevel) {
         manager.checkAccess();



Mime
View raw message