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 [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...
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();