diff options
Diffstat (limited to 'logging/src/main/java')
19 files changed, 1199 insertions, 904 deletions
diff --git a/logging/src/main/java/java/util/logging/ConsoleHandler.java b/logging/src/main/java/java/util/logging/ConsoleHandler.java index 9cea60f..a88cf0c 100644 --- a/logging/src/main/java/java/util/logging/ConsoleHandler.java +++ b/logging/src/main/java/java/util/logging/ConsoleHandler.java @@ -19,43 +19,47 @@ package java.util.logging; /** * A handler that writes log messages to the standard output stream - * <code>System.err</code>. + * {@code System.err}. * <p> * This handler reads the following properties from the log manager to * initialize itself: * <ul> * <li>java.util.logging.ConsoleHandler.level specifies the logging level, - * defaults to <code>Level.INFO</code> if this property is not found or has an - * invalid value; + * defaults to {@code Level.INFO} if this property is not found or has an + * invalid value. * <li>java.util.logging.ConsoleHandler.filter specifies the name of the filter - * class to be associated with this handler, defaults to <code>null</code> if - * this property is not found or has an invalid value; + * class to be associated with this handler, defaults to {@code null} if this + * property is not found or has an invalid value. * <li>java.util.logging.ConsoleHandler.formatter specifies the name of the * formatter class to be associated with this handler, defaults to - * <code>java.util.logging.SimpleFormatter</code> if this property is not - * found or has an invalid value; + * {@code java.util.logging.SimpleFormatter} if this property is not found or + * has an invalid value. * <li>java.util.logging.ConsoleHandler.encoding specifies the encoding this - * handler will use to encode log messages, defaults to <code>null</code> if - * this property is not found or has an invalid value. + * handler will use to encode log messages, defaults to {@code null} if this + * property is not found or has an invalid value. * </ul> * </p> * <p> * This class is not thread-safe. * </p> * + * @since Android 1.0 */ public class ConsoleHandler extends StreamHandler { /** - * Constructs a <code>ConsoleHandler</code> object. + * Constructs a {@code ConsoleHandler} object. + * + * @since Android 1.0 */ public ConsoleHandler() { super(System.err); } /** - * Closes this handler. The <code>System.err</code> is flushed but not - * closed. + * Closes this handler. The {@code System.err} is flushed but not closed. + * + * @since Android 1.0 */ @Override public void close() { @@ -65,7 +69,10 @@ public class ConsoleHandler extends StreamHandler { /** * Logs a record if necessary. A flush operation will be done. * - * @param record the log record to be logged + * @param record + * the log record to be logged. + * + * @since Android 1.0 */ @Override public void publish(LogRecord record) { diff --git a/logging/src/main/java/java/util/logging/ErrorManager.java b/logging/src/main/java/java/util/logging/ErrorManager.java index 0b12df1..6f5084c 100644 --- a/logging/src/main/java/java/util/logging/ErrorManager.java +++ b/logging/src/main/java/java/util/logging/ErrorManager.java @@ -20,43 +20,55 @@ package java.util.logging; import org.apache.harmony.logging.internal.nls.Messages; /** - * <p> * An error reporting facility for {@link Handler} implementations to record any - * error that may happen during logging. <code>Handlers</code> should report - * errors to an <code>ErrorManager</code>, instead of throwing exceptions, - * which would interfere with the log issuer's execution. - * </p> + * error that may happen during logging. {@code Handlers} should report errors + * to an {@code ErrorManager}, instead of throwing exceptions, which would + * interfere with the log issuer's execution. + * + * @since Android 1.0 */ public class ErrorManager { /** * The error code indicating a failure that does not fit in any of the * specific types of failures that follow. + * + * @since Android 1.0 */ public static final int GENERIC_FAILURE = 0; /** * The error code indicating a failure when writing to an output stream. + * + * @since Android 1.0 */ public static final int WRITE_FAILURE = 1; /** * The error code indicating a failure when flushing an output stream. + * + * @since Android 1.0 */ public static final int FLUSH_FAILURE = 2; /** * The error code indicating a failure when closing an output stream. + * + * @since Android 1.0 */ public static final int CLOSE_FAILURE = 3; /** * The error code indicating a failure when opening an output stream. + * + * @since Android 1.0 */ public static final int OPEN_FAILURE = 4; /** * The error code indicating a failure when formatting the error messages. + * + * @since Android 1.0 */ public static final int FORMAT_FAILURE = 5; @@ -72,7 +84,9 @@ public class ErrorManager { private boolean called; /** - * Constructs an instance of <code>ErrorManager</code>. + * Constructs an instance of {@code ErrorManager}. + * + * @since Android 1.0 */ public ErrorManager() { super(); @@ -87,13 +101,15 @@ public class ErrorManager { * </p> * * @param message - * The error message, which may be <code>null</code>. + * the error message, which may be {@code null}. * @param exception - * The exception associated with the error, which may be - * <code>null</code>. + * the exception associated with the error, which may be + * {@code null}. * @param errorCode - * The error code that identifies the type of error; see the - * constant fields on this class. + * the error code that identifies the type of error; see the + * constant fields of this class for possible values. + * + * @since Android 1.0 */ public void error(String message, Exception exception, int errorCode) { synchronized (this) { diff --git a/logging/src/main/java/java/util/logging/FileHandler.java b/logging/src/main/java/java/util/logging/FileHandler.java index be21ebc..af71a6d 100644 --- a/logging/src/main/java/java/util/logging/FileHandler.java +++ b/logging/src/main/java/java/util/logging/FileHandler.java @@ -32,74 +32,74 @@ import java.util.Hashtable; import org.apache.harmony.logging.internal.nls.Messages; /** - * A <code>Handler</code> writes description of logging event into a specified - * file or a rotating set of files. + * A {@code FileHandler} writes logging records into a specified file or a + * rotating set of files. * <p> - * If a set of files are used, when a given amount of data has been written to - * one file, this file is closed, and another file is opened. The name of these - * files are generated by given name pattern, see below for details. + * When a set of files is used and a given amount of data has been written to + * one file, then this file is closed and another file is opened. The name of + * these files are generated by given name pattern, see below for details. * </p> * <p> - * By default the IO buffering mechanism is enabled, but when each log record is - * complete, it is flushed out. + * By default, the I/O buffering mechanism is enabled, but when each log record + * is complete, it is flushed out. * </p> * <p> - * <code>XMLFormatter</code> is default formatter for <code>FileHandler</code>. + * {@code XMLFormatter} is the default formatter for {@code FileHandler}. * </p> * <p> - * <code>MemoryHandler</code> will read following <code>LogManager</code> - * properties for initialization, if given properties are not defined or has - * invalid values, default value will be used. + * {@code FileHandler} reads the following {@code LogManager} properties for + * initialization; if a property is not defined or has an invalid value, a + * default value is used. * <ul> * <li>java.util.logging.FileHandler.level specifies the level for this - * <code>Handler</code>, defaults to <code>Level.ALL</code>.</li> - * <li>java.util.logging.FileHandler.filter specifies the <code>Filter</code> - * class name, defaults to no <code>Filter</code>.</li> - * <li>java.util.logging.FileHandler.formatter specifies the - * <code>Formatter</code> class, defaults to - * <code>java.util.logging.XMLFormatter</code>.</li> + * {@code Handler}, defaults to {@code Level.ALL}.</li> + * <li>java.util.logging.FileHandler.filter specifies the {@code Filter} class + * name, defaults to no {@code Filter}.</li> + * <li>java.util.logging.FileHandler.formatter specifies the {@code Formatter} + * class, defaults to {@code java.util.logging.XMLFormatter}.</li> * <li>java.util.logging.FileHandler.encoding specifies the character set * encoding name, defaults to the default platform encoding.</li> - * <li>java.util.logging.FileHandler.limit specifies an maximum bytes to write - * to any one file, defaults to zero, which means no limit.</li> + * <li>java.util.logging.FileHandler.limit specifies the maximum number of + * bytes to write to any one file, defaults to zero, which means no limit.</li> * <li>java.util.logging.FileHandler.count specifies how many output files to * rotate, defaults to 1.</li> * <li>java.util.logging.FileHandler.pattern specifies name pattern for the * output files. See below for details. Defaults to "%h/java%u.log".</li> * <li>java.util.logging.FileHandler.append specifies whether this - * <code>FileHandler</code> should append onto existing files, defaults to - * false.</li> + * {@code FileHandler} should append onto existing files, defaults to + * {@code false}.</li> * </ul> * </p> * <p> - * Name pattern is a string that may includes some special sub-strings, which - * will be replaced to generate output files: + * Name pattern is a string that may include some special substrings, which will + * be replaced to generate output files: + * </p> * <ul> * <li>"/" represents the local pathname separator</li> - * <li>"%t" represents the system temporary directory</li> - * <li>"%h" represents the home directory of current user, which is specified - * by "user.home" system property</li> + * <li>"%t" represents the system's temporary directory</li> + * <li>"%h" represents the home directory of the current user, which is + * specified by "user.home" system property</li> * <li>"%g" represents the generation number to distinguish rotated logs</li> * <li>"%u" represents a unique number to resolve conflicts</li> - * <li>"%%" represents percent sign character '%'</li> + * <li>"%%" represents the percent sign character '%'</li> * </ul> - * </p> - * Normally, the generation numbers are not larger than given file count and + * <p> + * Normally, the generation numbers are not larger than the given file count and * follow the sequence 0, 1, 2.... If the file count is larger than one, but the * generation field("%g") has not been specified in the pattern, then the - * generation number after a dot will be added to the end of the file name, + * generation number after a dot will be added to the end of the file name. * </p> * <p> - * The "%u" unique field is used to avoid conflicts and set to 0 at first. If - * one <code>FileHandler</code> tries to open the filename which is currently - * in use by another process, it will repeatedly increment the unique number - * field and try again. If the "%u" component has not been included in the file - * name pattern and some contention on a file does occur then a unique numerical + * The "%u" unique field is used to avoid conflicts and is set to 0 at first. If + * one {@code FileHandler} tries to open the filename which is currently in use + * by another process, it will repeatedly increment the unique number field and + * try again. If the "%u" component has not been included in the file name + * pattern and some contention on a file does occur, then a unique numerical * value will be added to the end of the filename in question immediately to the - * right of a dot. The unique IDs for avoiding conflicts is only guaranteed to - * work reliably when using a local disk file system. + * right of a dot. The generation of unique IDs for avoiding conflicts is only + * guaranteed to work reliably when using a local disk file system. * </p> - * + * @since Android 1.0 */ public class FileHandler extends StreamHandler { @@ -148,17 +148,18 @@ public class FileHandler extends StreamHandler { int uniqueID = -1; /** - * Construct a <code>FileHandler</code> using <code>LogManager</code> - * properties or their default value + * Construct a {@code FileHandler} using {@code LogManager} properties or + * their default value. * * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. + * @since Android 1.0 */ public FileHandler() throws IOException { init(null, null, null, null); @@ -277,11 +278,11 @@ public class FileHandler extends StreamHandler { /** * Transform the pattern to the valid file name, replacing any patterns, and - * applying generation and uniqueID if present + * applying generation and uniqueID if present. * * @param gen * generation of this file - * @return transformed filename ready for use + * @return transformed filename ready for use. */ private String parseFileName(int gen) { int cur = 0; @@ -392,27 +393,27 @@ public class FileHandler extends StreamHandler { } /** - * Construct a <code>FileHandler</code>, the given name pattern is used - * as output filename, the file limit is set to zero(no limit), and the file - * count is set to one, other configuration using <code>LogManager</code> - * properties or their default value - * - * This handler write to only one file and no amount limit. + * Constructs a new {@code FileHandler}. The given name pattern is used as + * output filename, the file limit is set to zero (no limit), the file count + * is set to one; the remaining configuration is done using + * {@code LogManager} properties or their default values. This handler write + * to only one file without size limit. * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. - * @throws NullPointerException - * if the pattern is <code>null</code>. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException * if the pattern is empty. + * @throws NullPointerException + * if the pattern is {@code null}. + * @since Android 1.0 */ public FileHandler(String pattern) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -424,30 +425,30 @@ public class FileHandler extends StreamHandler { } /** - * Construct a <code>FileHandler</code>, the given name pattern is used - * as output filename, the file limit is set to zero(i.e. no limit applies), - * the file count is initialized to one, and the value of - * <code>append</code> becomes the new instance's append mode. Other - * configuration is done using <code>LogManager</code> properties. - * - * This handler write to only one file and no amount limit. + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the file limit is set to zero (no limit), the file count + * is initialized to one and the value of {@code append} becomes the new + * instance's append mode. The remaining configuration is done using + * {@code LogManager} properties. This handler write to only one file + * without size limit. * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param append - * the append mode + * the append mode. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. - * @throws NullPointerException - * if the pattern is <code>null</code>. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if the pattern is empty. + * if {@code pattern} is empty. + * @throws NullPointerException + * if {@code pattern} is {@code null}. + * @since Android 1.0 */ public FileHandler(String pattern, boolean append) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -459,34 +460,34 @@ public class FileHandler extends StreamHandler { } /** - * Construct a <code>FileHandler</code>, the given name pattern is used - * as output filename, the file limit is set to given limit argument, and - * the file count is set to given count argument, other configuration using - * <code>LogManager</code> properties or their default value - * - * This handler is configured to write to a rotating set of count files, - * when the limit of bytes has been written to one output file, another file - * will be opened instead. + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the maximum file size is set to {@code limit} and the + * file count is initialized to {@code count}. The remaining configuration + * is done using {@code LogManager} properties. This handler is configured + * to write to a rotating set of count files, when the limit of bytes has + * been written to one output file, another file will be opened instead. * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param limit - * the data amount limit in bytes of one output file, cannot less - * than one + * the data amount limit in bytes of one output file, can not be + * negative. * @param count - * the maximum number of files can be used, cannot less than one + * the maximum number of files to use, can not be less than one. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. - * @throws NullPointerException - * if pattern is <code>null</code>. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if count<1, or limit<0 + * if {@code pattern} is empty, {@code limit < 0} or + * {@code count < 1}. + * @throws NullPointerException + * if {@code pattern} is {@code null}. + * @since Android 1.0 */ public FileHandler(String pattern, int limit, int count) throws IOException { if (pattern.equals("")) { //$NON-NLS-1$ @@ -501,37 +502,37 @@ public class FileHandler extends StreamHandler { } /** - * Construct a <code>FileHandler</code>, the given name pattern is used - * as output filename, the file limit is set to given limit argument, the - * file count is set to given count argument, and the append mode is set to - * given append argument, other configuration using <code>LogManager</code> - * properties or their default value - * - * This handler is configured to write to a rotating set of count files, - * when the limit of bytes has been written to one output file, another file - * will be opened instead. + * Construct a new {@code FileHandler}. The given name pattern is used as + * output filename, the maximum file size is set to {@code limit}, the file + * count is initialized to {@code count} and the append mode is set to + * {@code append}. The remaining configuration is done using + * {@code LogManager} properties. This handler is configured to write to a + * rotating set of count files, when the limit of bytes has been written to + * one output file, another file will be opened instead. * * @param pattern - * the name pattern of output file + * the name pattern for the output file. * @param limit - * the data amount limit in bytes of one output file, cannot less - * than one + * the data amount limit in bytes of one output file, can not be + * negative. * @param count - * the maximum number of files can be used, cannot less than one + * the maximum number of files to use, can not be less than one. * @param append - * the append mode + * the append mode. * @throws IOException - * if any IO exception happened + * if any I/O error occurs. * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. - * @throws NullPointerException - * if pattern is <code>null</code>. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. * @throws IllegalArgumentException - * if count<1, or limit<0 + * if {@code pattern} is empty, {@code limit < 0} or + * {@code count < 1}. + * @throws NullPointerException + * if {@code pattern} is {@code null}. + * @since Android 1.0 */ public FileHandler(String pattern, int limit, int count, boolean append) throws IOException { @@ -548,14 +549,15 @@ public class FileHandler extends StreamHandler { } /** - * Flush and close all opened files. + * Flushes and closes all opened files. * * @throws SecurityException - * if security manager exists and it determines that caller does - * not have the required permissions to control this handler, - * required permissions include - * <code>LogPermission("control")</code> and other permission - * like <code>FilePermission("write")</code>, etc. + * if a security manager exists and it determines that the + * caller does not have the required permissions to control this + * handler; required permissions include + * {@code LogPermission("control")}, + * {@code FilePermission("write")} etc. + * @since Android 1.0 */ @Override public void close() { @@ -574,10 +576,11 @@ public class FileHandler extends StreamHandler { } /** - * Publish a <code>LogRecord</code> + * Publish a {@code LogRecord}. * * @param record - * the log record to be published + * the log record to publish. + * @since Android 1.0 */ @Override public void publish(LogRecord record) { @@ -594,9 +597,9 @@ public class FileHandler extends StreamHandler { } /** - * This output stream use decorator pattern to add measure feature to - * OutputStream which can detect the total size(in bytes) of output, the - * initial size can be set + * This output stream uses the decorator pattern to add measurement features + * to OutputStream which can detect the total size(in bytes) of output, the + * initial size can be set. */ static class MeasureOutputStream extends OutputStream { diff --git a/logging/src/main/java/java/util/logging/Filter.java b/logging/src/main/java/java/util/logging/Filter.java index d96f3ce..e81f216 100644 --- a/logging/src/main/java/java/util/logging/Filter.java +++ b/logging/src/main/java/java/util/logging/Filter.java @@ -18,17 +18,21 @@ package java.util.logging; /** - * <p>A Filter provides a mechanism for exercising fine-grained control over - * what records get logged.</p> + * A {@code Filter} provides a mechanism for exercising fine-grained control + * over which records get logged. + * + * @since Android 1.0 */ public interface Filter { /** - * <p>Checks the {@link LogRecord} to determine if it should be logged.</p> + * Checks {@code record} to determine if it should be logged. * - * @param record The {@link LogRecord} to be checked. - * @return <code>true</code> if the supplied log record needs to be - * logged, otherwise <code>false</code> + * @param record + * the {@link LogRecord} to be checked. + * @return {@code true} if the supplied log record needs to be logged, + * {@code false} otherwise. + * @since Android 1.0 */ boolean isLoggable(LogRecord record); } diff --git a/logging/src/main/java/java/util/logging/Formatter.java b/logging/src/main/java/java/util/logging/Formatter.java index 7321aa2..2941c24 100644 --- a/logging/src/main/java/java/util/logging/Formatter.java +++ b/logging/src/main/java/java/util/logging/Formatter.java @@ -22,11 +22,12 @@ import java.text.MessageFormat; import java.util.ResourceBundle; /** - * <code>Formatter</code> objects are used to format <code>LogRecord</code> - * objects into a string representation. Head and tail strings are sometime used - * to wrap a set of records. The <code>getHead</code> and <code>getTail</code> - * methods are presented for this purpose. + * {@code Formatter} objects are used to format {@link LogRecord} objects into a + * string representation. Head and tail strings are sometimes used to wrap a set + * of records. The {@code getHead} and {@code getTail} methods are used for this + * purpose. * + * @since Android 1.0 */ public abstract class Formatter { @@ -37,7 +38,9 @@ public abstract class Formatter { */ /** - * Constructs a <code>Formatter</code> object. + * Constructs a {@code Formatter} object. + * + * @since Android 1.0 */ protected Formatter() { super(); @@ -50,29 +53,34 @@ public abstract class Formatter { */ /** - * Formats a <code>LogRecord</code> object into a string representation. - * The resulted string is usually localized and includes the message field - * of the supplied <code>LogRecord</code> object. + * Converts a {@link LogRecord} object into a string representation. The + * resulted string is usually localized and includes the message field of + * the record. * * @param r - * the log record to be formatted into a string - * @return the string resulted from the formatting + * the log record to be formatted into a string. + * @return the formatted string. + * @since Android 1.0 */ public abstract String format(LogRecord r); /** - * Formats a <code>LogRecord</code> object into a localized string - * representation. This method can be regarded as a convenience for - * subclasses of <code>Formatter</code> to use. + * Formats a {@code LogRecord} object into a localized string + * representation. This is a convenience method for subclasses of {@code + * Formatter}. + * <p> + * The message string is firstly localized using the {@code ResourceBundle} + * object associated with the supplied {@code LogRecord}. + * </p> * <p> - * The message string is firstly localized using the - * <code>ResourceBundle</code> object associated with the supplied - * <code>LogRecord</code>. + * Notice : if message contains "{0", then java.text.MessageFormat is used. + * Otherwise no formatting is performed. * </p> * * @param r - * the log record to be formatted - * @return the string resulted from the formatting + * the log record to be formatted. + * @return the string resulted from the formatting. + * @since Android 1.0 */ public String formatMessage(LogRecord r) { String pattern = r.getMessage(); @@ -105,11 +113,13 @@ public abstract class Formatter { /** * Gets the head string used to wrap a set of log records. This base class - * always returns the empty string. + * always returns an empty string. * * @param h - * the target handler - * @return the head string used to wrap a set of log records + * the target handler. + * @return the head string used to wrap a set of log records, empty in this + * implementation. + * @since Android 1.0 */ @SuppressWarnings("unused") public String getHead(Handler h) { @@ -121,8 +131,10 @@ public abstract class Formatter { * always returns the empty string. * * @param h - * the target handler - * @return the tail string used to wrap a set of log records + * the target handler. + * @return the tail string used to wrap a set of log records, empty in this + * implementation. + * @since Android 1.0 */ @SuppressWarnings("unused") public String getTail(Handler h) { diff --git a/logging/src/main/java/java/util/logging/Handler.java b/logging/src/main/java/java/util/logging/Handler.java index 9bad459..d28bce0 100644 --- a/logging/src/main/java/java/util/logging/Handler.java +++ b/logging/src/main/java/java/util/logging/Handler.java @@ -26,10 +26,11 @@ import java.io.UnsupportedEncodingException; import org.apache.harmony.logging.internal.nls.Messages; /** - * A <code>Handler</code> object accepts a logging request and exports the - * desired messages to a target, for example, a file, the console, etc. It can - * be disabled by setting its logging level to <code>Level.OFF</code>. + * A {@code Handler} object accepts a logging request and exports the desired + * messages to a target, for example, a file, the console, etc. It can be + * disabled by setting its logging level to {@code Level.OFF}. * + * @since Android 1.0 */ public abstract class Handler { @@ -71,9 +72,11 @@ public abstract class Handler { */ /** - * Constructs a <code>Handler</code> object with a default error manager, - * the default encoding, and the default logging level - * <code>Level.ALL</code>. It has no filter and no formatter. + * Constructs a {@code Handler} object with a default error manager instance + * {@code ErrorManager}, the default encoding, and the default logging + * level {@code Level.ALL}. It has no filter and no formatter. + * + * @since Android 1.0 */ protected Handler() { this.errorMan = new ErrorManager(); @@ -187,33 +190,40 @@ public abstract class Handler { } /** - * Closes this handler. A flush operation will usually be performed and all - * the associated resources will be freed. Client applications should not - * use a handler after closing it. + * Closes this handler. A flush operation will be performed and all the + * associated resources will be freed. Client applications should not use + * this handler after closing it. * * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * + * @since Android 1.0 */ public abstract void close(); /** * Flushes any buffered output. + * + * @since Android 1.0 */ public abstract void flush(); /** - * Accepts an actual logging request. + * Accepts a logging request and sends it to the the target. * * @param record - * the log record to be logged + * the log record to be logged; {@code null} records are ignored. + * @since Android 1.0 */ public abstract void publish(LogRecord record); /** - * Gets the character encoding used by this handler. + * Gets the character encoding used by this handler, {@code null} for + * default encoding. * - * @return the character encoding used by this handler + * @return the character encoding used by this handler. + * @since Android 1.0 */ public String getEncoding() { return this.encoding; @@ -223,10 +233,11 @@ public abstract class Handler { * Gets the error manager used by this handler to report errors during * logging. * - * @return the error manager used by this handler + * @return the error manager used by this handler. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ public ErrorManager getErrorManager() { LogManager.getLogManager().checkAccess(); @@ -236,7 +247,8 @@ public abstract class Handler { /** * Gets the filter used by this handler. * - * @return the filter used by this handler + * @return the filter used by this handler (possibly {@code null}). + * @since Android 1.0 */ public Filter getFilter() { return this.filter; @@ -245,29 +257,33 @@ public abstract class Handler { /** * Gets the formatter used by this handler to format the logging messages. * - * @return the formatter used by this handler + * @return the formatter used by this handler (possibly {@code null}). + * @since Android 1.0 */ public Formatter getFormatter() { return this.formatter; } /** - * Gets the logging level of this handler. + * Gets the logging level of this handler, records with levels lower than + * this value will be dropped. * - * @return the logging level of this handler + * @return the logging level of this handler. + * @since Android 1.0 */ public Level getLevel() { return this.level; } /** - * Determines whether the supplied log record need to be logged. The logging - * levels will be checked as well as the filter. + * Determines whether the supplied log record needs to be logged. The + * logging levels will be checked as well as the filter. * * @param record - * the log record to be checked - * @return <code>true</code> if the supplied log record need to be logged, - * otherwise <code>false</code> + * the log record to be checked. + * @return {@code true} if the supplied log record needs to be logged, + * otherwise {@code false}. + * @since Android 1.0 */ public boolean isLoggable(LogRecord record) { if (null == record) { @@ -282,28 +298,33 @@ public abstract class Handler { } /** - * Report an error to the error manager associated with this handler. + * Reports an error to the error manager associated with this handler, + * {@code ErrorManager} is used for that purpose. No security checks are + * done, therefore this is compatible with environments where the caller + * is non-privileged. * * @param msg - * the error message + * the error message, may be {@code null}. * @param ex - * the associated exception + * the associated exception, may be {@code null}. * @param code - * the error code + * an {@code ErrorManager} error code. + * @since Android 1.0 */ protected void reportError(String msg, Exception ex, int code) { this.errorMan.error(msg, ex, code); } /** - * Sets the character encoding used by this handler. A <code>null</code> - * value indicates the using of the default encoding. This internal method - * does not check security. + * Sets the character encoding used by this handler. A {@code null} value + * indicates the use of the default encoding. This internal method does + * not check security. * * @param newEncoding - * the character encoding to set + * the character encoding to set. * @throws UnsupportedEncodingException - * If the specified encoding is not supported by the runtime. + * if the specified encoding is not supported by the runtime. + * @since Android 1.0 */ void internalSetEncoding(String newEncoding) throws UnsupportedEncodingException { @@ -324,16 +345,17 @@ public abstract class Handler { } /** - * Sets the character encoding used by this handler. A <code>null</code> - * value indicates the using of the default encoding. + * Sets the character encoding used by this handler, {@code null} indicates + * a default encoding. * * @param encoding - * the character encoding to set + * the character encoding to set. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. * @throws UnsupportedEncodingException - * If the specified encoding is not supported by the runtime. + * if the specified encoding is not supported by the runtime. + * @since Android 1.0 */ public void setEncoding(String encoding) throws SecurityException, UnsupportedEncodingException { @@ -345,10 +367,13 @@ public abstract class Handler { * Sets the error manager for this handler. * * @param em - * the error manager to set + * the error manager to set. + * @throws NullPointerException + * if {@code em} is {@code null}. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ public void setErrorManager(ErrorManager em) { LogManager.getLogManager().checkAccess(); @@ -362,10 +387,11 @@ public abstract class Handler { * Sets the filter to be used by this handler. * * @param newFilter - * the filter to set + * the filter to set, may be {@code null}. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ public void setFilter(Filter newFilter) { LogManager.getLogManager().checkAccess(); @@ -377,7 +403,7 @@ public abstract class Handler { * not check security. * * @param newFormatter - * the formatter to set + * the formatter to set. */ void internalSetFormatter(Formatter newFormatter) { if (null == newFormatter) { @@ -390,10 +416,13 @@ public abstract class Handler { * Sets the formatter to be used by this handler. * * @param newFormatter - * the formatter to set + * the formatter to set. + * @throws NullPointerException + * if {@code newFormatter} is {@code null}. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ public void setFormatter(Formatter newFormatter) { LogManager.getLogManager().checkAccess(); @@ -401,13 +430,17 @@ public abstract class Handler { } /** - * Sets the logging level of this handler. + * Sets the logging level of the messages logged by this handler, levels + * lower than this value will be dropped. * * @param newLevel - * the logging level to set + * the logging level to set. + * @throws NullPointerException + * if {@code newLevel} is {@code null}. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ public void setLevel(Level newLevel) { if (null == newLevel) { diff --git a/logging/src/main/java/java/util/logging/Level.java b/logging/src/main/java/java/util/logging/Level.java index bb39d51..32ba017 100644 --- a/logging/src/main/java/java/util/logging/Level.java +++ b/logging/src/main/java/java/util/logging/Level.java @@ -27,20 +27,22 @@ import java.util.MissingResourceException; import java.util.ResourceBundle; import org.apache.harmony.logging.internal.nls.Messages; -import org.apache.harmony.kernel.vm.VM; +// BEGIN android-changed +import dalvik.system.VMStack; +// END android-changed /** - * <code>Level</code> objects are used to indicate the level of logging. There - * are a set of predefined logging levels, each associated with an integer - * value. Enabling a certain logging level also enables all logging levels with - * larger values. + * {@code Level} objects are used to indicate the level of logging. There are a + * set of predefined logging levels, each associated with an integer value. + * Enabling a certain logging level also enables all logging levels with larger + * values. * <p> * The predefined levels in ascending order are FINEST, FINER, FINE, CONFIG, * INFO, WARNING, SEVERE. There are two additional predefined levels, which are * ALL and OFF. ALL indicates logging all messages, and OFF indicates logging no * messages. * </p> - * + * @since Android 1.0 */ public class Level implements Serializable { @@ -50,61 +52,85 @@ public class Level implements Serializable { /** * The OFF level provides no logging messages. + * + * @since Android 1.0 */ public static final Level OFF = new Level("OFF", Integer.MAX_VALUE); //$NON-NLS-1$ /** - * The SEVERE level indicates a severe failure. + * The SEVERE level provides severe failure messages. + * + * @since Android 1.0 */ public static final Level SEVERE = new Level("SEVERE", 1000); //$NON-NLS-1$ /** - * The WARNING level indicates a warning. + * The WARNING level provides warnings. + * + * @since Android 1.0 */ public static final Level WARNING = new Level("WARNING", 900); //$NON-NLS-1$ /** - * The INFO level indicates an informative message. + * The INFO level provides informative messages. + * + * @since Android 1.0 */ public static final Level INFO = new Level("INFO", 800); //$NON-NLS-1$ /** - * The CONFIG level indicates a static configuration message. + * The CONFIG level provides static configuration messages. + * + * @since Android 1.0 */ public static final Level CONFIG = new Level("CONFIG", 700); //$NON-NLS-1$ /** * The FINE level provides tracing messages. + * + * @since Android 1.0 */ public static final Level FINE = new Level("FINE", 500); //$NON-NLS-1$ /** * The FINER level provides more detailed tracing messages. + * + * @since Android 1.0 */ public static final Level FINER = new Level("FINER", 400); //$NON-NLS-1$ /** * The FINEST level provides highly detailed tracing messages. + * + * @since Android 1.0 */ public static final Level FINEST = new Level("FINEST", 300); //$NON-NLS-1$ /** * The ALL level provides all logging messages. + * + * @since Android 1.0 */ public static final Level ALL = new Level("ALL", Integer.MIN_VALUE); //$NON-NLS-1$ /** - * Parses a level name into a <code>Level</code> object. + * Parses a level name into a {@code Level} object. * * @param name - * the name of the desired level, which cannot be null - * @return a <code>Level</code> object with the specified name + * the name of the desired {@code level}, which cannot be + * {@code null}. + * @return the level with the specified name. * @throws NullPointerException - * if <code>name</code> is <code>null</code>. + * if {@code name} is {@code null}. * @throws IllegalArgumentException - * if <code>name</code> is not valid. + * if {@code name} is not valid. + * @since Android 1.0 */ - public static final Level parse(String name) { + public static Level parse(String name) throws IllegalArgumentException { + // BEGIN android-note + // final modifier removed and IAE added to get closer to the RI + // copied from newer version of harmony + // END android-note if (name == null) { // logging.1C=The 'name' parameter is null. throw new NullPointerException(Messages.getString("logging.1C")); //$NON-NLS-1$ @@ -176,25 +202,34 @@ public class Level implements Serializable { private transient ResourceBundle rb; /** - * Constructs an instance of <code>Level</code> taking the supplied name - * and level value. + * Constructs an instance of {@code Level} taking the supplied name and + * level value. * - * @param name name of the level - * @param level an integer value indicating the level - * @throws NullPointerException if <code>name</code> is <code>null</code>. + * @param name + * the name of the level. + * @param level + * an integer value indicating the level. + * @throws NullPointerException + * if {@code name} is {@code null}. + * @since Android 1.0 */ protected Level(String name, int level) { this(name, level, null); } /** - * Constructs an instance of <code>Level</code> taking the supplied name - * and level value. + * Constructs an instance of {@code Level} taking the supplied name, level + * value and resource bundle name. * - * @param name name of the level - * @param level an integer value indicating the level - * @param resourceBundleName the name of the resource bundle to use - * @throws NullPointerException if <code>name</code> is <code>null</code>. + * @param name + * the name of the level. + * @param level + * an integer value indicating the level. + * @param resourceBundleName + * the name of the resource bundle to use. + * @throws NullPointerException + * if {@code name} is {@code null}. + * @since Android 1.0 */ protected Level(String name, int level, String resourceBundleName) { if (name == null) { @@ -206,11 +241,10 @@ public class Level implements Serializable { this.resourceBundleName = resourceBundleName; if (resourceBundleName != null) { try { - rb = ResourceBundle.getBundle(resourceBundleName, - // TODO Implement kernel.vm.VM.callerClassLoader, or find - // another way to get the caller class loader - // Locale.getDefault(), VM.callerClassLoader()); - Locale.getDefault(), ClassLoader.getSystemClassLoader()); + rb = ResourceBundle.getBundle(resourceBundleName, + // BEGIN android-changed + Locale.getDefault(), VMStack.getCallingClassLoader()); + // BEGIN android-changed } catch (MissingResourceException e) { rb = null; } @@ -221,29 +255,30 @@ public class Level implements Serializable { } /** - * Gets the name of this <code>Level</code>. + * Gets the name of this level. * - * @return the name of this <code>Level</code> + * @return this level's name. + * @since Android 1.0 */ public String getName() { return this.name; } /** - * Gets the name of the resource bundle associated with this - * <code>Level</code>. + * Gets the name of the resource bundle associated with this level. * - * @return the name of the resource bundle associated with this - * <code>Level</code> + * @return the name of this level's resource bundle. + * @since Android 1.0 */ public String getResourceBundleName() { return this.resourceBundleName; } /** - * Gets the integer value indicating this <code>Level</code>. + * Gets the integer value indicating this level. * - * @return the integer value indicating this <code>Level</code> + * @return this level's integer value. + * @since Android 1.0 */ public final int intValue() { return this.value; @@ -255,7 +290,7 @@ public class Level implements Serializable { * levels. * </p> * - * @return The resolved instance. + * @return the resolved instance. */ private Object readResolve() { synchronized (levels) { @@ -280,10 +315,14 @@ public class Level implements Serializable { } /** - * <p>Serialization helper to setup transient resource bundle instance.</p> - * @param in The input stream to read the instance data from. - * @throws IOException if an IO error occurs. - * @throws ClassNotFoundException if a class is not found. + * Serialization helper to setup transient resource bundle instance. + * + * @param in + * the input stream to read the instance data from. + * @throws IOException + * if an IO error occurs. + * @throws ClassNotFoundException + * if a class is not found. */ private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); @@ -298,10 +337,11 @@ public class Level implements Serializable { /** * Gets the localized name of this level. The default locale is used. If no - * resource bundle is associated with this <code>Level</code>, the - * original level name is returned. + * resource bundle is associated with this level then the original level + * name is returned. * - * @return the localized name of this level + * @return the localized name of this level. + * @since Android 1.0 */ public String getLocalizedName() { if (rb == null) { @@ -316,12 +356,14 @@ public class Level implements Serializable { } /** - * Compares two <code>Level</code> objects for equality. They are - * considered to be equal if they have the same value. + * Compares two {@code Level} objects for equality. They are considered to + * be equal if they have the same level value. * - * @param o the other object to be compared with - * @return <code>true</code> if this object equals to the supplied object, - * otherwise <code>false</code> + * @param o + * the other object to compare this level to. + * @return {@code true} if this object equals to the supplied object, + * {@code false} otherwise. + * @since Android 1.0 */ @Override public boolean equals(Object o) { @@ -337,9 +379,10 @@ public class Level implements Serializable { } /** - * Returns the hash code of this <code>Level</code> object. + * Returns the hash code of this {@code Level} object. * - * @return the hash code of this <code>Level</code> object + * @return this level's hash code. + * @since Android 1.0 */ @Override public int hashCode() { @@ -347,14 +390,14 @@ public class Level implements Serializable { } /** - * Returns the string representation of this <code>Level</code> object. - * Usually this will include its name. + * Returns the string representation of this {@code Level} object. In + * this case, it is the level's name. * - * @return the string representation of this <code>Level</code> object + * @return the string representation of this level. + * @since Android 1.0 */ @Override public final String toString() { return this.name; } - } diff --git a/logging/src/main/java/java/util/logging/LogManager.java b/logging/src/main/java/java/util/logging/LogManager.java index 462b658..8409b81 100644 --- a/logging/src/main/java/java/util/logging/LogManager.java +++ b/logging/src/main/java/java/util/logging/LogManager.java @@ -17,10 +17,8 @@ package java.util.logging; -// BEGIN android-removed -// import java.beans.PropertyChangeListener; -// import java.beans.PropertyChangeSupport; -// END android-removed +import java.beans.PropertyChangeListener; +import java.beans.PropertyChangeSupport; import java.io.BufferedInputStream; import java.io.File; import java.io.FileInputStream; @@ -47,29 +45,30 @@ import java.util.StringTokenizer; import org.apache.harmony.logging.internal.nls.Messages; /** - * <code>LogManager</code> is used to maintain configuration properties of the + * {@code LogManager} is used to maintain configuration properties of the * logging framework, and to manage a hierarchical namespace of all named - * <code>Logger</code> objects. + * {@code Logger} objects. * <p> - * There is only one global <code>LogManager</code> instance in the + * + * There is only one global {@code LogManager} instance in the * application, which can be get by calling static method - * <code>LogManager.getLogManager()</code>. This instance is created and + * {@link #getLogManager()}. This instance is created and * initialized during class initialization and cannot be changed. * </p> * <p> - * The <code>LogManager</code> class can be specified by + * The {@code LogManager} class can be specified by * java.util.logging.manager system property, if the property is unavailable or - * invalid, the default class <code>java.util.logging.LogManager</code> will + * invalid, the default class {@link java.util.logging.LogManager} will * be used. * </p> * <p> - * When initialization, <code>LogManager</code> read its configuration from a + * When initialization, {@code LogManager} read its configuration from a * properties file, which by default is the "lib/logging.properties" in the JRE * directory. * </p> * <p> * However, two optional system properties can be used to customize the initial - * configuration process of <code>LogManager</code>. + * configuration process of {@code LogManager}. * <ul> * <li>"java.util.logging.config.class"</li> * <li>"java.util.logging.config.file"</li> @@ -83,20 +82,20 @@ import org.apache.harmony.logging.internal.nls.Messages; * <p> * The "java.util.logging.config.class" should specifies a class name. If it is * set, this given class will be loaded and instantiated during - * <code>LogManager</code> initialization, so that this object's default + * {@code LogManager} initialization, so that this object's default * constructor can read the initial configuration and define properties for - * <code>LogManager</code>. + * {@code LogManager}. * </p> * <p> * If "java.util.logging.config.class" property is not set, or it is invalid, or * some exception is thrown during the instantiation, then the * "java.util.logging.config.file" system property can be used to specify a - * properties file. The <code>LogManager</code> will read initial + * properties file. The {@code LogManager} will read initial * configuration from this file. * </p> * <p> * If neither of these properties is defined, or some exception is thrown - * during these two properties using, the <code>LogManager</code> will read + * during these two properties using, the {@code LogManager} will read * its initial configuration from default properties file, as described above. * </p> * <p> @@ -104,21 +103,21 @@ import org.apache.harmony.logging.internal.nls.Messages; * <ul> * <li>"handlers". This property's values should be a list of class names for * handler classes separated by whitespace, these classes must be subclasses of - * <code>Handler</code> and each must have a default constructor, these + * {@code Handler} and each must have a default constructor, these * classes will be loaded, instantiated and registered as handlers on the root - * <code>Logger</code> (the <code>Logger</code> named ""). These - * <code>Handler</code>s maybe initialized lazily.</li> + * {@code Logger} (the {@code Logger} named ""). These + * {@code Handler}s maybe initialized lazily.</li> * <li>"config". The property defines a list of class names separated by * whitespace. Each class must have a default constructor, in which it can * update the logging configuration, such as levels, handlers, or filters for * some logger, etc. These classes will be loaded and instantiated during - * <code>LogManager</code> configuration</li> + * {@code LogManager} configuration</li> * </ul> * </p> * <p> * This class, together with any handler and configuration classes associated * with it, <b>must</b> be loaded from the system classpath when - * <code>LogManager</code> configuration occurs. + * {@code LogManager} configuration occurs. * </p> * <p> * Besides global properties, the properties for loggers and Handlers can be @@ -126,12 +125,12 @@ import org.apache.harmony.logging.internal.nls.Messages; * with the complete dot separated names for the handlers or loggers. * </p> * <p> - * In the <code>LogManager</code>'s hierarchical namespace, - * <code>Loggers</code> are organized based on their dot separated names. For + * In the {@code LogManager}'s hierarchical namespace, + * {@code Loggers} are organized based on their dot separated names. For * example, "x.y.z" is child of "x.y". * </p> * <p> - * Levels for <code>Loggers</code> can be defined by properties whose name end + * Levels for {@code Loggers} can be defined by properties whose name end * with ".level". Thus "alogger.level" defines a level for the logger named as * "alogger" and for all its children in the naming hierarchy. Log levels * properties are read and applied in the same order as they are specified in @@ -163,48 +162,54 @@ public class LogManager { static LogManager manager; /** - * <p>The String value of the {@link LoggingMXBean}'s ObjectName.</p> + * The {@code String} value of the {@link LoggingMXBean}'s ObjectName. + * + * @since Android 1.0 */ public static final String LOGGING_MXBEAN_NAME = "java.util.logging:type=Logging"; //$NON-NLS-1$ -// BENGIN android-removed -// /** -// * Get the <code>LoggingMXBean</code> instance -// * -// * @return the <code>LoggingMXBean</code> instance -// */ -// public static LoggingMXBean getLoggingMXBean() { -// try { -// ObjectName loggingMXBeanName = new ObjectName(LOGGING_MXBEAN_NAME); -// MBeanServer platformBeanServer = -// ManagementFactory.getPlatformMBeanServer(); -// Set loggingMXBeanSet = platformBeanServer.queryMBeans( -// loggingMXBeanName, null); -// -// if (loggingMXBeanSet.size() != 1) { -// // logging.21=There Can Be Only One logging MX bean. -// throw new AssertionError(Messages.getString("logging.21")); -// } -// -// Iterator i = loggingMXBeanSet.iterator(); -// ObjectInstance loggingMXBeanOI = (ObjectInstance) i.next(); -// String lmxbcn = loggingMXBeanOI.getClassName(); -// Class lmxbc = Class.forName(lmxbcn); -// Method giMethod = lmxbc.getDeclaredMethod("getInstance"); -// giMethod.setAccessible(true); -// LoggingMXBean lmxb = (LoggingMXBean) -// giMethod.invoke(null, new Object[] {}); -// -// return lmxb; -// } catch (Exception e) { -// //TODO -// //e.printStackTrace(); -// } -// // logging.22=Exception occurred while getting the logging MX bean. -// throw new AssertionError(Messages.getString("logging.22")); //$NON-NLS-1$ -// } -// END android-removed + /** + * Get the {@code LoggingMXBean} instance. this implementation always throws + * an UnsupportedOperationException. + * + * @return the {@code LoggingMXBean} instance + */ + public static LoggingMXBean getLoggingMXBean() { + // BEGIN android-added + throw new UnsupportedOperationException(); + // END android-added + // BEGIN android-removed + // try { + // ObjectName loggingMXBeanName = new ObjectName(LOGGING_MXBEAN_NAME); + // MBeanServer platformBeanServer = + // ManagementFactory.getPlatformMBeanServer(); + // Set loggingMXBeanSet = platformBeanServer.queryMBeans( + // loggingMXBeanName, null); + // + // if (loggingMXBeanSet.size() != 1) { + // // logging.21=There Can Be Only One logging MX bean. + // throw new AssertionError(Messages.getString("logging.21")); + // } + // + // Iterator i = loggingMXBeanSet.iterator(); + // ObjectInstance loggingMXBeanOI = (ObjectInstance) i.next(); + // String lmxbcn = loggingMXBeanOI.getClassName(); + // Class lmxbc = Class.forName(lmxbcn); + // Method giMethod = lmxbc.getDeclaredMethod("getInstance"); + // giMethod.setAccessible(true); + // LoggingMXBean lmxb = (LoggingMXBean) + // giMethod.invoke(null, new Object[] {}); + // + // return lmxb; + // } catch (Exception e) { + // //TODO + // //e.printStackTrace(); + // } + // // logging.22=Exception occurred while getting the logging MX bean. + // throw new AssertionError(Messages.getString("logging.22")); //$NON-NLS-1$ + // END android-removed + } /* * ------------------------------------------------------------------- @@ -218,9 +223,7 @@ public class LogManager { private Properties props; // the property change listener -// BEGIN android-removed -// private PropertyChangeSupport listeners; -// END android-removed + private PropertyChangeSupport listeners; /* * ------------------------------------------------------------------- @@ -263,16 +266,14 @@ public class LogManager { /** * Default constructor. This is not public because there should be only one - * <code>LogManager</code> instance, which can be get by - * <code>LogManager.getLogManager(</code>. This is protected so that + * {@code LogManager} instance, which can be get by + * {@code LogManager.getLogManager(}. This is protected so that * application can subclass the object. */ protected LogManager() { loggers = new Hashtable<String, Logger>(); props = new Properties(); -// BEGIN android-removed -// listeners = new PropertyChangeSupport(this); -// END android-removed + listeners = new PropertyChangeSupport(this); // add shutdown hook to ensure that the associated resource will be // freed when JVM exits AccessController.doPrivileged(new PrivilegedAction<Void>() { @@ -302,15 +303,15 @@ public class LogManager { } /** - * Check that the caller has <code>LoggingPermission("control")</code> so + * Check that the caller has {@code LoggingPermission("control")} so * that it is trusted to modify the configuration for logging framework. If - * the check passes, just return, otherwise <code>SecurityException</code> + * the check passes, just return, otherwise {@code SecurityException} * will be thrown. * * @throws SecurityException * if there is a security manager in operation and the invoker * of this method does not have the required security permission - * <code>LoggingPermission("control")</code> + * {@code LoggingPermission("control")} */ public void checkAccess() { if (null != System.getSecurityManager()) { @@ -320,21 +321,20 @@ public class LogManager { /** * Add a given logger into the hierarchical namespace. The - * <code>Logger.addLogger()</code> factory methods call this method to add - * newly created Logger. This returns false if a logger with the given name - * has existed in the namespace + * {@code Logger.addLogger()} factory methods call this method to add newly + * created Logger. This returns false if a logger with the given name has + * existed in the namespace * <p> - * Note that the <code>LogManager</code> may only retain weak references - * to registered loggers. In order to prevent <code>Logger</code> objects - * from being unexpectedly garbage collected it is necessary for - * <i>applications</i> to maintain references to them. + * Note that the {@code LogManager} may only retain weak references to + * registered loggers. In order to prevent {@code Logger} objects from being + * unexpectedly garbage collected it is necessary for <i>applications</i> + * to maintain references to them. * </p> * * @param logger - * the logger to be added + * the logger to be added. * @return true if the given logger is added into the namespace - * successfully, false if the logger of given name has existed in - * the namespace + * successfully, false if the given logger exists in the namespace. */ public synchronized boolean addLogger(Logger logger) { String name = logger.getName(); @@ -388,18 +388,18 @@ public class LogManager { } /** - * Get the logger with the given name + * Get the logger with the given name. * * @param name * name of logger - * @return logger with given name, or null if nothing is found + * @return logger with given name, or {@code null} if nothing is found. */ public synchronized Logger getLogger(String name) { return loggers.get(name); } /** - * Get a <code>Enumeration</code> of all registered logger names + * Get a {@code Enumeration} of all registered logger names. * * @return enumeration of registered logger names */ @@ -408,16 +408,16 @@ public class LogManager { } /** - * Get the global <code>LogManager</code> instance + * Get the global {@code LogManager} instance. * - * @return the global <code>LogManager</code> instance + * @return the global {@code LogManager} instance */ public static LogManager getLogManager() { return manager; } /** - * Get the value of property with given name + * Get the value of property with given name. * * @param name * the name of property @@ -428,17 +428,17 @@ public class LogManager { } /** - * Re-initialize the properties and configuration. The initialization process - * is same as the <code>LogManager</code> instantiation. + * Re-initialize the properties and configuration. The initialization + * process is same as the {@code LogManager} instantiation. * <p> - * A <code>PropertyChangeEvent</code> must be fired. + * Notice : No {@code PropertyChangeEvent} are fired. * </p> * * @throws IOException - * if any IO related problems happened + * if any IO related problems happened. * @throws SecurityException * if security manager exists and it determines that caller does - * not have the required permissions to perform this action + * not have the required permissions to perform this action. */ public void readConfiguration() throws IOException { checkAccess(); @@ -466,10 +466,13 @@ public class LogManager { // BEGIN android-added try { - input = new BufferedInputStream(new FileInputStream(configFile), 8192); + input = new BufferedInputStream( + new FileInputStream(configFile), 8192); } catch (Exception ex) { // consult fixed resource as a last resort - input = new BufferedInputStream(getClass().getResourceAsStream("logging.properties"), 8192); + input = new BufferedInputStream( + getClass().getResourceAsStream( + "logging.properties"), 8192); } // END android-added readConfigurationImpl(input); @@ -520,7 +523,7 @@ public class LogManager { throws IOException { reset(); props.load(ins); - + // parse property "config" and apply setting String configs = props.getProperty("config"); //$NON-NLS-1$ if (null != configs) { @@ -540,26 +543,24 @@ public class LogManager { logger.setLevel(Level.parse(property)); } } -// BEGIN android-removed -// listeners.firePropertyChange(null, null, null); -// END android-removed + listeners.firePropertyChange(null, null, null); } /** * Re-initialize the properties and configuration from the given - * <code>InputStream</code> + * {@code InputStream} * <p> - * A <code>PropertyChangeEvent</code> must be fired. + * Notice : No {@code PropertyChangeEvent} are fired. * </p> * * @param ins - * the input stream. + * the input stream * @throws IOException - * if any IO related problems happened + * if any IO related problems happened. * @throws SecurityException * if security manager exists and it determines that caller does - * not have the required permissions to perform this action + * not have the required permissions to perform this action. */ public void readConfiguration(InputStream ins) throws IOException { checkAccess(); @@ -571,12 +572,12 @@ public class LogManager { * <p> * All handlers are closed and removed from any named loggers. All loggers' * level is set to null, except the root logger's level is set to - * <code>Level.INFO</code>. + * {@code Level.INFO}. * </p> * * @throws SecurityException * if security manager exists and it determines that caller does - * not have the required permissions to perform this action + * not have the required permissions to perform this action. */ public void reset() { checkAccess(); @@ -596,39 +597,35 @@ public class LogManager { } /** - * Add a <code>PropertyChangeListener</code>, which will be invoked when + * Add a {@code PropertyChangeListener}, which will be invoked when * the properties are reread. * * @param l - * the <code>PropertyChangeListener</code> to be added + * the {@code PropertyChangeListener} to be added. * @throws SecurityException * if security manager exists and it determines that caller does - * not have the required permissions to perform this action + * not have the required permissions to perform this action. */ -// BEGIN android-removed -// public void addPropertyChangeListener(IPropertyChangeListener l) { -// if(l == null){ -// throw new NullPointerException(); -// } -// checkAccess(); -// listeners.addPropertyChangeListener(l); -// } -// END android-removed + public void addPropertyChangeListener(PropertyChangeListener l) { + if(l == null){ + throw new NullPointerException(); + } + checkAccess(); + listeners.addPropertyChangeListener(l); + } /** - * Remove a <code>PropertyChangeListener</code>, do nothing if the given + * Remove a {@code PropertyChangeListener}, do nothing if the given * listener is not found. * * @param l - * the <code>PropertyChangeListener</code> to be removed + * the {@code PropertyChangeListener} to be removed. * @throws SecurityException * if security manager exists and it determines that caller does - * not have the required permissions to perform this action + * not have the required permissions to perform this action. */ -// BEGIN android-removed -// public void removePropertyChangeListener(IPropertyChangeListener l) { -// checkAccess(); -// listeners.removePropertyChangeListener(l); -// } -// END android-removed + public void removePropertyChangeListener(PropertyChangeListener l) { + checkAccess(); + listeners.removePropertyChangeListener(l); + } } diff --git a/logging/src/main/java/java/util/logging/LogRecord.java b/logging/src/main/java/java/util/logging/LogRecord.java index e133797..b8a98ef 100644 --- a/logging/src/main/java/java/util/logging/LogRecord.java +++ b/logging/src/main/java/java/util/logging/LogRecord.java @@ -27,21 +27,22 @@ import java.util.ResourceBundle; import org.apache.harmony.logging.internal.nls.Messages; /** - * A <code>LogRecord</code> object represents a logging request. It is passed - * between the logging framework and individual logging handlers. Client - * applications should not modify a <code>LogRecord</code> object that has - * been passed into the logging framework. + * A {@code LogRecord} object represents a logging request. It is passed between + * the logging framework and individual logging handlers. Client applications + * should not modify a {@code LogRecord} object that has been passed into the + * logging framework. * <p> - * The <code>LogRecord</code> class will infer the source method name and - * source class name the first time they are accessed if the client application - * didn't specify them explicitly. This automatic inference is based on the - * analysis of the call stack and is not guaranteed to be precise. Client - * applications should force the initialization of these two fields by calling - * <code>getSourceClassName</code> or <code>getSourceMethodName</code> if - * they expect to use them after passing the <code>LogRecord</code> object to - * another thread or transmitting it over RMI. + * The {@code LogRecord} class will infer the source method name and source + * class name the first time they are accessed if the client application didn't + * specify them explicitly. This automatic inference is based on the analysis of + * the call stack and is not guaranteed to be precise. Client applications + * should force the initialization of these two fields by calling + * {@code getSourceClassName} or {@code getSourceMethodName} if they expect to + * use them after passing the {@code LogRecord} object to another thread or + * transmitting it over RMI. * </p> * + * @since Android 1.0 */ public class LogRecord implements Serializable { @@ -112,7 +113,7 @@ public class LogRecord implements Serializable { private long millis; /** - * The associated <code>Throwable</code> object if any. + * The associated {@code Throwable} object if any. * * @serial */ @@ -142,16 +143,19 @@ public class LogRecord implements Serializable { private transient boolean sourceInited; /** - * Constructs a <code>LogRecord</code> object using the supplied the - * logging level and message. The millis property is set to the current - * time. The sequence property is set to a new unique value, allocated in - * increasing order within a VM. The thread ID is set to a unique value for - * the current thread. All other properties are set to <code>null</code>. + * Constructs a {@code LogRecord} object using the supplied the logging + * level and message. The millis property is set to the current time. The + * sequence property is set to a new unique value, allocated in increasing + * order within the virtual machine. The thread ID is set to a unique value + * for the current thread. All other properties are set to {@code null}. * * @param level - * the logging level which may not be null + * the logging level, may not be {@code null}. * @param msg - * the raw message + * the raw message. + * @throws NullPointerException + * if {@code level} is {@code null}. + * @since Android 1.0 */ public LogRecord(Level level, String msg) { if (null == level) { @@ -185,7 +189,8 @@ public class LogRecord implements Serializable { /** * Gets the logging level. * - * @return the logging level + * @return the logging level. + * @since Android 1.0 */ public Level getLevel() { return level; @@ -195,7 +200,10 @@ public class LogRecord implements Serializable { * Sets the logging level. * * @param level - * the level to set + * the level to set. + * @throws NullPointerException + * if {@code level} is {@code null}. + * @since Android 1.0 */ public void setLevel(Level level) { if (null == level) { @@ -208,7 +216,8 @@ public class LogRecord implements Serializable { /** * Gets the name of the logger. * - * @return the logger name + * @return the logger name. + * @since Android 1.0 */ public String getLoggerName() { return loggerName; @@ -218,7 +227,8 @@ public class LogRecord implements Serializable { * Sets the name of the logger. * * @param loggerName - * the logger name to set + * the logger name to set. + * @since Android 1.0 */ public void setLoggerName(String loggerName) { this.loggerName = loggerName; @@ -227,36 +237,42 @@ public class LogRecord implements Serializable { /** * Gets the raw message. * - * @return the raw message + * @return the raw message, may be {@code null}. + * @since Android 1.0 */ public String getMessage() { return message; } /** - * Sets the raw message. + * Sets the raw message. When this record is formatted by a logger that has + * a localization resource bundle that contains an entry for {@code message}, + * then the raw message is replaced with its localized version. * * @param message - * the raw message to set + * the raw message to set, may be {@code null}. + * @since Android 1.0 */ public void setMessage(String message) { this.message = message; } /** - * Gets the time that the event occurred, in milliseconds since 1970. + * Gets the time when this event occurred, in milliseconds since 1970. * - * @return the time that the event occurred, in milliseconds since 1970 + * @return the time when this event occurred, in milliseconds since 1970. + * @since Android 1.0 */ public long getMillis() { return millis; } /** - * Sets the time that the event occurred, in milliseconds since 1970. + * Sets the time when this event occurred, in milliseconds since 1970. * * @param millis - * the time that the event occurred, in milliseconds since 1970 + * the time when this event occurred, in milliseconds since 1970. + * @since Android 1.0 */ public void setMillis(long millis) { this.millis = millis; @@ -265,7 +281,9 @@ public class LogRecord implements Serializable { /** * Gets the parameters. * - * @return the array of parameters + * @return the array of parameters or {@code null} if there are no + * parameters. + * @since Android 1.0 */ public Object[] getParameters() { return parameters; @@ -275,7 +293,8 @@ public class LogRecord implements Serializable { * Sets the parameters. * * @param parameters - * the array of parameters to set + * the array of parameters to set, may be {@code null}. + * @since Android 1.0 */ public void setParameters(Object[] parameters) { this.parameters = parameters; @@ -285,18 +304,20 @@ public class LogRecord implements Serializable { * Gets the resource bundle used to localize the raw message during * formatting. * - * @return the associated resource bundle + * @return the associated resource bundle, {@code null} if none is + * available or the message is not localizable. + * @since Android 1.0 */ public ResourceBundle getResourceBundle() { return resourceBundle; } /** - * Sets the resource bundle used to localize the raw message during - * formatting. + * Sets the resource bundle. * * @param resourceBundle - * the resource bundle to set + * the resource bundle to set, may be {@code null}. + * @since Android 1.0 */ public void setResourceBundle(ResourceBundle resourceBundle) { this.resourceBundle = resourceBundle; @@ -305,7 +326,9 @@ public class LogRecord implements Serializable { /** * Gets the name of the resource bundle. * - * @return the name of the resource bundle + * @return the name of the resource bundle, {@code null} if none is + * available or the message is not localizable. + * @since Android 1.0 */ public String getResourceBundleName() { return resourceBundleName; @@ -315,7 +338,8 @@ public class LogRecord implements Serializable { * Sets the name of the resource bundle. * * @param resourceBundleName - * the name of the resource bundle to set + * the name of the resource bundle to set. + * @since Android 1.0 */ public void setResourceBundleName(String resourceBundleName) { this.resourceBundleName = resourceBundleName; @@ -324,28 +348,32 @@ public class LogRecord implements Serializable { /** * Gets the sequence number. * - * @return the sequence number + * @return the sequence number. + * @since Android 1.0 */ public long getSequenceNumber() { return sequenceNumber; } /** - * Sets the sequence number. It is usually unnecessary to call this method + * Sets the sequence number. It is usually not necessary to call this method * to change the sequence number because the number is allocated when this * instance is constructed. * * @param sequenceNumber - * the sequence number to set + * the sequence number to set. + * @since Android 1.0 */ public void setSequenceNumber(long sequenceNumber) { this.sequenceNumber = sequenceNumber; } /** - * Gets the name of the class that issued the logging call. + * Gets the name of the class that is the source of this log record. This + * information can be changed, may be {@code null} and is untrusted. * - * @return the name of the class that issued the logging call + * @return the name of the source class of this log record (possiblity {@code null}) + * @since Android 1.0 */ public String getSourceClassName() { initSource(); @@ -378,10 +406,12 @@ public class LogRecord implements Serializable { } /** - * Sets the name of the class that issued the logging call. + * Sets the name of the class that is the source of this log record. * * @param sourceClassName - * the name of the class that issued the logging call + * the name of the source class of this log record, may be + * {@code null}. + * @since Android 1.0 */ public void setSourceClassName(String sourceClassName) { sourceInited = true; @@ -389,9 +419,10 @@ public class LogRecord implements Serializable { } /** - * Gets the name of the method that issued the logging call. + * Gets the name of the method that is the source of this log record. * - * @return the name of the method that issued the logging call + * @return the name of the source method of this log record. + * @since Android 1.0 */ public String getSourceMethodName() { initSource(); @@ -399,10 +430,12 @@ public class LogRecord implements Serializable { } /** - * Sets the name of the method that issued the logging call. + * Sets the name of the method that is the source of this log record. * * @param sourceMethodName - * the name of the method that issued the logging call + * the name of the source method of this log record, may be + * {@code null}. + * @since Android 1.0 */ public void setSourceMethodName(String sourceMethodName) { sourceInited = true; @@ -410,40 +443,47 @@ public class LogRecord implements Serializable { } /** - * Gets the ID of the thread originating the message. + * Gets a unique ID of the thread originating the log record. Every thread + * becomes a different ID. + * <p> + * Notice : the ID doesn't necessary map the OS thread ID + * </p> * - * @return the ID of the thread originating the message + * @return the ID of the thread originating this log record. + * @since Android 1.0 */ public int getThreadID() { return threadID; } /** - * Sets the ID of the thread originating the message. + * Sets the ID of the thread originating this log record. * * @param threadID - * the ID of the thread originating the message + * the new ID of the thread originating this log record. + * @since Android 1.0 */ public void setThreadID(int threadID) { this.threadID = threadID; } /** - * Gets the <code>Throwable</code> object associated with this log record. + * Gets the {@code Throwable} object associated with this log record. * - * @return the <code>Throwable</code> object associated with this log - * record + * @return the {@code Throwable} object associated with this log record. + * @since Android 1.0 */ public Throwable getThrown() { return thrown; } /** - * Sets the <code>Throwable</code> object associated with this log record. + * Sets the {@code Throwable} object associated with this log record. * * @param thrown - * the <code>Throwable</code> object associated with this log - * record + * the new {@code Throwable} object to associate with this log + * record. + * @since Android 1.0 */ public void setThrown(Throwable thrown) { this.thrown = thrown; diff --git a/logging/src/main/java/java/util/logging/Logger.java b/logging/src/main/java/java/util/logging/Logger.java index fbe32ed..cd88ca0 100644 --- a/logging/src/main/java/java/util/logging/Logger.java +++ b/logging/src/main/java/java/util/logging/Logger.java @@ -33,22 +33,22 @@ import org.apache.harmony.logging.internal.nls.Messages; * 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>. + * 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> * <p> * When loading a given resource bundle, the logger first tries to use the @@ -59,23 +59,26 @@ import org.apache.harmony.logging.internal.nls.Messages; * <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. + * the calling class and method, but this is not guaranteed to be accurate. * </p> * <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. + * 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> * <p> * All methods of this class are thread-safe. * </p> * * @see LogManager + * @since Android 1.0 */ public class Logger { /** * The global logger is provided as convenience for casual use. + * + * @since Android 1.0 */ public final static Logger global = new Logger("global", null); //$NON-NLS-1$ @@ -116,7 +119,9 @@ public class Logger { private LogManager manager; + // BEGIN android-changed private volatile boolean handlerInited; + // END android-changed /* @@ -126,16 +131,21 @@ public class Logger { */ /** - * 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". + * </p> * * @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. + * @since Android 1.0 */ protected Logger(String name, String resourceBundleName) { // try to load the specified resource bundle first @@ -199,10 +209,10 @@ public class Logger { * 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 @@ -270,14 +280,14 @@ public class Logger { /** * 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. + * 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. * </p> * - * @return a new instance of anonymous logger + * @return a new instance of anonymous logger. + * @since Android 1.0 */ public static Logger getAnonymousLogger() { return getAnonymousLogger(null); @@ -286,18 +296,18 @@ public class Logger { /** * 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. + * The anonymous loggers' parent is set to be the root logger. This way it + * inherits default logging level and handlers from the root logger. * </p> * * @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. + * @since Android 1.0 */ public static Logger getAnonymousLogger(String resourceBundleName) { final Logger l = new Logger(null, resourceBundleName); @@ -365,15 +375,14 @@ public class Logger { } /** - * 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 - * @throws MissingResourceException - * If the specified resource bundle can not be loaded. + * the name of the logger to get, cannot be {@code null}. + * @return a named logger. + * @since Android 1.0 */ public static Logger getLogger(String name) { return getLoggerWithRes(name, null, false); @@ -384,24 +393,32 @@ public class Logger { * 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. + * @since Android 1.0 */ 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. + * @since Android 1.0 */ public void addHandler(Handler handler) { if (null == handler) { @@ -434,7 +451,6 @@ public class Logger { */ LogManager.getLogManager(); // END android-added - if (handlers == null) { handlers = new ArrayList<Handler>(); } @@ -450,8 +466,8 @@ public class Logger { StringTokenizer st = new StringTokenizer(handlerStr, " "); //$NON-NLS-1$ while (st.hasMoreTokens()) { String handlerName = st.nextToken(); - - // BEGIN android-changed: deal with non-existing handler + // BEGIN android-changed + // deal with non-existing handler try { Handler handler = (Handler) LogManager .getInstanceByClass(handlerName); @@ -465,7 +481,6 @@ public class Logger { ex.printStackTrace(); } // END android-changed - } handlerInited = true; } @@ -476,7 +491,8 @@ public class Logger { /** * 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. + * @since Android 1.0 */ public Handler[] getHandlers() { initHandler(); @@ -486,14 +502,15 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void removeHandler(Handler handler) { // Anonymous loggers can always remove handlers @@ -512,7 +529,8 @@ public class Logger { /** * 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}. + * @since Android 1.0 */ public Filter getFilter() { return this.filter; @@ -522,10 +540,11 @@ public class Logger { * 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. + * @since Android 1.0 */ public void setFilter(Filter newFilter) { // Anonymous loggers can always set the filter @@ -536,23 +555,26 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ 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. + * @since Android 1.0 */ public void setLevel(Level newLevel) { // Anonymous loggers can always set the level @@ -565,25 +587,28 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ 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. + * @since Android 1.0 */ public void setUseParentHandlers(boolean notifyParentHandlers) { // Anonymous loggers can always set the useParentHandlers flag @@ -594,9 +619,11 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public Logger getParent() { return parent; @@ -604,11 +631,12 @@ public class Logger { /** * 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. + * @since Android 1.0 */ void internalSetParent(Logger newParent) { //All hierarchy related modifications should get LogManager lock at first @@ -624,14 +652,15 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void setParent(Logger parent) { if (null == parent) { @@ -653,9 +682,10 @@ public class Logger { /** - * 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. + * @since Android 1.0 */ public String getName() { return this.name; @@ -663,9 +693,11 @@ public class Logger { /** * 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. + * @since Android 1.0 */ public ResourceBundle getResourceBundle() { return this.resBundle; @@ -673,19 +705,20 @@ public class Logger { /** * 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. + * @since Android 1.0 */ public String getResourceBundleName() { return this.resBundleName; } /** - * This method is for compatibility. Tests written to the reference - * implementation API imply that the isLoggable() method is not called - * directly. This behavior is important because subclass may override + * This method is for compatibility. Tests written to the reference + * implementation API imply that the isLoggable() method is not called + * directly. This behavior is important because subclass may override * isLoggable() method, so that affect the result of log methods. */ private boolean internalIsLoggable(Level l) { @@ -700,12 +733,13 @@ public class Logger { /** * 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}. + * @since Android 1.0 */ public boolean isLoggable(Level l) { return internalIsLoggable(l); @@ -738,14 +772,15 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void entering(String sourceClass, String sourceMethod) { if (internalIsLoggable(Level.FINER)) { @@ -759,17 +794,18 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void entering(String sourceClass, String sourceMethod, Object param) { if (internalIsLoggable(Level.FINER)) { @@ -784,17 +820,18 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void entering(String sourceClass, String sourceMethod, Object[] params) { @@ -818,14 +855,15 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void exiting(String sourceClass, String sourceMethod) { if (internalIsLoggable(Level.FINER)) { @@ -839,17 +877,17 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void exiting(String sourceClass, String sourceMethod, Object result) { if (internalIsLoggable(Level.FINER)) { @@ -864,17 +902,18 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void throwing(String sourceClass, String sourceMethod, Throwable thrown) { @@ -890,10 +929,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void severe(String msg) { if (internalIsLoggable(Level.SEVERE)) { @@ -905,10 +946,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void warning(String msg) { if (internalIsLoggable(Level.WARNING)) { @@ -920,10 +963,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void info(String msg) { if (internalIsLoggable(Level.INFO)) { @@ -935,10 +980,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void config(String msg) { if (internalIsLoggable(Level.CONFIG)) { @@ -950,10 +997,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void fine(String msg) { if (internalIsLoggable(Level.FINE)) { @@ -965,10 +1014,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void finer(String msg) { if (internalIsLoggable(Level.FINER)) { @@ -980,10 +1031,12 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void finest(String msg) { if (internalIsLoggable(Level.FINEST)) { @@ -995,12 +1048,14 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void log(Level logLevel, String msg) { if (internalIsLoggable(logLevel)) { @@ -1012,14 +1067,16 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void log(Level logLevel, String msg, Object param) { if (internalIsLoggable(logLevel)) { @@ -1033,14 +1090,15 @@ public class Logger { /** * 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. + * @since Android 1.0 */ public void log(Level logLevel, String msg, Object[] params) { if (internalIsLoggable(logLevel)) { @@ -1053,16 +1111,17 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void log(Level logLevel, String msg, Throwable thrown) { if (internalIsLoggable(logLevel)) { @@ -1075,11 +1134,11 @@ public class Logger { } /** - * 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 @@ -1087,7 +1146,8 @@ public class Logger { * </p> * * @param record - * the log record to be logged + * the log record to be logged. + * @since Android 1.0 */ public void log(LogRecord record) { if (internalIsLoggable(record.getLevel())) { @@ -1124,13 +1184,14 @@ public class Logger { * 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. + * @since Android 1.0 */ public void logp(Level logLevel, String sourceClass, String sourceMethod, String msg) { @@ -1145,8 +1206,8 @@ public class Logger { } /** - * 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 @@ -1157,7 +1218,8 @@ public class Logger { * @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. + * @since Android 1.0 */ public void logp(Level logLevel, String sourceClass, String sourceMethod, String msg, Object param) { @@ -1173,20 +1235,20 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void logp(Level logLevel, String sourceClass, String sourceMethod, String msg, Object[] params) { @@ -1202,19 +1264,20 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void logp(Level logLevel, String sourceClass, String sourceMethod, String msg, Throwable thrown) { @@ -1232,18 +1295,20 @@ public class Logger { /** * 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. + * @since Android 1.0 */ public void logrb(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg) { @@ -1265,22 +1330,24 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void logrb(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Object param) { @@ -1303,23 +1370,24 @@ public class Logger { } /** - * 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. + * @since Android 1.0 */ public void logrb(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Object[] params) { @@ -1342,9 +1410,10 @@ public class Logger { } /** - * 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 @@ -1353,11 +1422,12 @@ public class Logger { * @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. + * @since Android 1.0 */ public void logrb(Level logLevel, String sourceClass, String sourceMethod, String bundleName, String msg, Throwable thrown) { diff --git a/logging/src/main/java/java/util/logging/LoggingMXBean.java b/logging/src/main/java/java/util/logging/LoggingMXBean.java index 71ea65d..f6b49a6 100644 --- a/logging/src/main/java/java/util/logging/LoggingMXBean.java +++ b/logging/src/main/java/java/util/logging/LoggingMXBean.java @@ -20,67 +20,66 @@ package java.util.logging; import java.util.List; /** + * {@code LoggingMXBean} is the management interface for the logging sub-system. * <p> - * The management interface for the logging sub-system. + * The ObjectName for identifying the {@code LoggingMXBean} in a bean server is + * {@link LogManager#LOGGING_MXBEAN_NAME}. * </p> * - * <p> - * ObjectName = - * {@link LogManager#LOGGING_MXBEAN_NAME java.util.logging:type=Logging} - * </p> - * - * @since 1.5 + * @since Android 1.0 */ public interface LoggingMXBean { /** - * <p> - * 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. - * </p> + * 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>. + * @param loggerName + * the name of the logger lookup. + * @return a {@code String} if the logger is found, otherwise {@code null}. * @see Level#getName() + * @since Android 1.0 */ String getLoggerLevel(String loggerName); /** - * <p> - * 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()}. - * </p> * - * @return A List of String instances. + * @return a list of logger names. + * @since Android 1.0 */ List<String> getLoggerNames(); /** - * <p> * 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. - * </p> + * 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>. + * @param loggerName + * the name of the logger to lookup. + * @return a {@code String} if the logger was found, otherwise {@code null}. + * @since Android 1.0 */ String getParentLoggerName(String loggerName); /** - * <p> - * Sets the log level of a logger. - * </p> + * 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>. - * @param levelName The level to set on the logger, which may be - * <code>null</code>. - * @throws IllegalArgumentException if <code>loggerName</code> is not a - * registered logger or if <code>levelName</code> is not null and - * an invalid value. - * @throws SecurityException if a security manager exists and the caller - * doesn't have LoggingPermission("control"). + * @param loggerName + * 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}. + * @throws IllegalArgumentException + * 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"). * @see Level#parse(String) + * @since Android 1.0 */ void setLoggerLevel(String loggerName, String levelName); } diff --git a/logging/src/main/java/java/util/logging/LoggingPermission.java b/logging/src/main/java/java/util/logging/LoggingPermission.java index 6962127..fb6d4f8 100644 --- a/logging/src/main/java/java/util/logging/LoggingPermission.java +++ b/logging/src/main/java/java/util/logging/LoggingPermission.java @@ -26,7 +26,7 @@ import org.apache.harmony.logging.internal.nls.Messages; /** * The permission required to control the logging when run with a - * <code>SecurityManager</code>. + * {@code SecurityManager}. * */ public final class LoggingPermission extends BasicPermission implements Guard, @@ -43,14 +43,20 @@ public final class LoggingPermission extends BasicPermission implements Guard, */ /** - * 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); diff --git a/logging/src/main/java/java/util/logging/MemoryHandler.java b/logging/src/main/java/java/util/logging/MemoryHandler.java index ca96dc5..c1e8670 100644 --- a/logging/src/main/java/java/util/logging/MemoryHandler.java +++ b/logging/src/main/java/java/util/logging/MemoryHandler.java @@ -24,46 +24,47 @@ import org.apache.harmony.logging.internal.nls.Messages; /** - * A <code>Handler</code> put the description of log events into a cycled memory + * A {@code Handler} put the description of log events into a cycled memory * buffer. - * <p> - * Mostly this <code>MemoryHandler</code> just puts the given <code>LogRecord</code> - * 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> + * 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> * <p> - * Every <code>MemoryHandler</code> 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. + * 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> * <p> * The push action can be triggered in three ways: * <ul> * <li>The push method is called explicitly</li> - * <li>When a new <code>LogRecord</code> is put into the internal buffer, and it has a level which is not less than the specified push level.</li> - * <li>A subclass extends this <code>MemoryHandler</code> and call push method implicitly according to some criteria.</li> + * <li>When a new {@code LogRecord} is put into the internal buffer, and it has + * a level which is not less than the specified push level.</li> + * <li>A subclass extends this {@code MemoryHandler} and call push method + * implicitly according to some criteria.</li> * </ul> * </p> * <p> - * <code>MemoryHandler</code> will read following <code>LogManager</code> - * properties for initialization, if given properties are not defined or has - * invalid values, default value will be used. + * {@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.level specifies the level for this - * <code>Handler</code>, defaults to <code>Level.ALL</code>.</li> - * <li>java.util.logging.MemoryHandler.filter specifies the <code>Filter</code> - * class name, defaults to no <code>Filter</code>.</li> - * <li>java.util.logging.MemoryHandler.size specifies the buffer size in number - * of <code>LogRecord</code>, defaults to 1000.</li> - * <li>java.util.logging.MemoryHandler.push specifies the push level, defaults + * <li>java.util.logging.MemoryHandler.level specifies the level for this + * {@code Handler}, defaults to {@code Level.ALL}.</li> + * <li>java.util.logging.MemoryHandler.filter specifies the {@code Filter} + * class name, defaults to no {@code Filter}.</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.push specifies the push level, defaults * to level.SEVERE.</li> - * <li>java.util.logging.MemoryHandler.target specifies the class of the target - * <code>Handler</code>, no default value, which means this property must be - * specified either by property setting or by constructor.</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 { @@ -88,8 +89,12 @@ public class MemoryHandler extends Handler { 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(); @@ -139,17 +144,22 @@ public class MemoryHandler extends Handler { } /** - * 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 - * @param size the maximum number of buffered <code>LogRecord</code> + * the given {@code Handler} to output + * @param size + * the maximum number of buffered {@code LogRecord}, greater than + * zero * @param pushLevel - * the push level + * 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) { @@ -166,11 +176,11 @@ public class MemoryHandler extends Handler { } /** - * 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 + * if security manager exists and it determines that caller does + * not have the required permissions to control this handler. */ @Override public void close() { @@ -180,10 +190,8 @@ public class MemoryHandler extends Handler { } /** - * 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() { @@ -191,14 +199,14 @@ public class MemoryHandler extends Handler { } /** - * 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. + * @param record + * the log record */ @Override public synchronized void publish(LogRecord record) { @@ -225,19 +233,22 @@ public class MemoryHandler extends Handler { } /** - * <p>Check if given <code>LogRecord</code> would be put into this - * <code>MemoryHandler</code>'s internal buffer. + * <p> + * Check if given {@code LogRecord} would be put into this + * {@code MemoryHandler}'s internal buffer. * </p> * <p> - * The given <code>LogRecord</code> is loggable if and only if it has - * appropriate level and it pass any associated filter's check. + * The given {@code LogRecord} is loggable if and only if it has appropriate + * level and it pass any associated filter's check. * </p> * <p> - * Note that the push level is not used for this check. + * 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) { @@ -266,15 +277,15 @@ public class MemoryHandler extends Handler { /** * 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. * * @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 + * does not have the required permissions to control this handler. */ public void setPushLevel(Level newLevel) { manager.checkAccess(); diff --git a/logging/src/main/java/java/util/logging/SimpleFormatter.java b/logging/src/main/java/java/util/logging/SimpleFormatter.java index cfccda0..1595796 100644 --- a/logging/src/main/java/java/util/logging/SimpleFormatter.java +++ b/logging/src/main/java/java/util/logging/SimpleFormatter.java @@ -24,19 +24,29 @@ import java.text.MessageFormat; import java.util.Date; /** - * <code>SimpleFormatter</code> can be used to print a summary of the - * information contained in a <code>LogRecord</code> object in a human - * readable format. - * + * {@code SimpleFormatter} can be used to print a summary of the information + * contained in a {@code LogRecord} object in a human readable format. + * @since Android 1.0 */ public class SimpleFormatter extends Formatter { /** - * Constructs a <code>SimpleFormatter</code> object. + * Constructs a new {@code SimpleFormatter}. + * + * @since Android 1.0 */ public SimpleFormatter() { super(); } + /** + * Converts a {@link LogRecord} object into a human readable string + * representation. + * + * @param r + * the log record to be formatted into a string. + * @return the formatted string. + * @since Android 1.0 + */ @Override public String format(LogRecord r) { StringBuilder sb = new StringBuilder(); diff --git a/logging/src/main/java/java/util/logging/SocketHandler.java b/logging/src/main/java/java/util/logging/SocketHandler.java index 3d9ab29..8626007 100644 --- a/logging/src/main/java/java/util/logging/SocketHandler.java +++ b/logging/src/main/java/java/util/logging/SocketHandler.java @@ -31,18 +31,18 @@ import org.apache.harmony.logging.internal.nls.Messages; * initialize itself: * <ul> * <li>java.util.logging.ConsoleHandler.level specifies the logging level, - * defaults to <code>Level.ALL</code> if this property is not found or has an - * invalid value; + * defaults to {@code Level.ALL} if this property is not found or has an invalid + * value. * <li>java.util.logging.SocketHandler.filter specifies the name of the filter - * class to be associated with this handler, defaults to <code>null</code> if - * this property is not found or has an invalid value; + * class to be associated with this handler, defaults to {@code null} if this + * property is not found or has an invalid value. * <li>java.util.logging.SocketHandler.formatter specifies the name of the * formatter class to be associated with this handler, defaults to - * <code>java.util.logging.XMLFormatter</code> if this property is not found - * or has an invalid value; + * {@code java.util.logging.XMLFormatter} if this property is not found or has + * an invalid value. * <li>java.util.logging.SocketHandler.encoding specifies the encoding this - * handler will use to encode log messages, defaults to <code>null</code> if - * this property is not found or has an invalid value. + * handler will use to encode log messages, defaults to {@code null} if this + * property is not found or has an invalid value. * <li>java.util.logging.SocketHandler.host specifies the name of the host that * this handler should connect to. There's no default value for this property. * <li>java.util.logging.SocketHandler.encoding specifies the port number that @@ -56,7 +56,6 @@ import org.apache.harmony.logging.internal.nls.Messages; * <p> * This class is not thread-safe. * </p> - * */ public class SocketHandler extends StreamHandler { // default level @@ -69,15 +68,16 @@ public class SocketHandler extends StreamHandler { private Socket socket; /** - * Constructs a <code>SocketHandler</code> object using the properties - * read by the log manager, including the host name and port number. + * Constructs a {@code SocketHandler} object using the properties read by + * the log manager, including the host name and port number. Default + * formatting uses the XMLFormatter class and level is set to ALL. * * @throws IOException - * If failed to connect to the specified host and port. + * if failed to connect to the specified host and port. * @throws IllegalArgumentException - * If the host name or port number is illegal. + * if the host name or port number is illegal. * @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 to control this handler. */ public SocketHandler() throws IOException { @@ -89,20 +89,20 @@ public class SocketHandler extends StreamHandler { } /** - * Constructs a <code>SocketHandler</code> object using the specified host - * name and port number together with other properties read by the log - * manager. + * Constructs a {@code SocketHandler} object using the specified host name + * and port number together with other properties read by the log manager. + * Default formatting uses the XMLFormatter class and level is set to ALL. * * @param host * the host name * @param port * the port number * @throws IOException - * If failed to connect to the specified host and port. + * if failed to connect to the specified host and port. * @throws IllegalArgumentException - * If the host name or port number is illegal. + * if the host name or port number is illegal. * @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 to control this handler. */ public SocketHandler(String host, int port) throws IOException { @@ -170,7 +170,7 @@ public class SocketHandler extends StreamHandler { * Logs a record if necessary. A flush operation will be done afterwards. * * @param record - * the log record to be logged + * the log record to be logged. */ @Override public void publish(LogRecord record) { diff --git a/logging/src/main/java/java/util/logging/StreamHandler.java b/logging/src/main/java/java/util/logging/StreamHandler.java index fb48c2a..ee12190 100644 --- a/logging/src/main/java/java/util/logging/StreamHandler.java +++ b/logging/src/main/java/java/util/logging/StreamHandler.java @@ -26,31 +26,32 @@ import java.io.Writer; import org.apache.harmony.logging.internal.nls.Messages; /** - * A <code>StreamHandler</code> object writes log messages to an output - * stream, that is, objects of the class <code>java.io.OutputStream</code>. + * A {@code StreamHandler} object writes log messages to an output stream, that + * is, objects of the class {@link java.io.OutputStream}. * <p> - * A <code>StreamHandler</code> object reads the following properties from the - * log manager to initialize itself: + * A {@code StreamHandler} object reads the following properties from the log + * manager to initialize itself: * <ul> * <li>java.util.logging.StreamHandler.level specifies the logging level, - * defaults to <code>Level.INFO</code> if this property is not found or has an - * invalid value; + * defaults to {@code Level.INFO} if this property is not found or has an + * invalid value. * <li>java.util.logging.StreamHandler.filter specifies the name of the filter - * class to be associated with this handler, defaults to <code>null</code> if - * this property is not found or has an invalid value; + * class to be associated with this handler, defaults to {@code null} if this + * property is not found or has an invalid value. * <li>java.util.logging.StreamHandler.formatter specifies the name of the * formatter class to be associated with this handler, defaults to - * <code>java.util.logging.SimpleFormatter</code> if this property is not - * found or has an invalid value; + * {@code java.util.logging.SimpleFormatter} if this property is not found or + * has an invalid value. * <li>java.util.logging.StreamHandler.encoding specifies the encoding this - * handler will use to encode log messages, defaults to <code>null</code> if - * this property is not found or has an invalid value. + * handler will use to encode log messages, defaults to {@code null} if this + * property is not found or has an invalid value. * </ul> * </p> * <p> * This class is not thread-safe. * </p> * + * @since Android 1.0 */ public class StreamHandler extends Handler { // the output stream this handler writes to @@ -63,8 +64,10 @@ public class StreamHandler extends Handler { private boolean writerNotInitialized; /** - * Constructs a <code>StreamHandler</code> object. The new stream handler + * Constructs a {@code StreamHandler} object. The new stream handler * does not have an associated output stream. + * + * @since Android 1.0 */ public StreamHandler() { initProperties("INFO", null, "java.util.logging.SimpleFormatter", //$NON-NLS-1$//$NON-NLS-2$ @@ -75,11 +78,11 @@ public class StreamHandler extends Handler { } /** - * Constructs a <code>StreamHandler</code> object with the supplied output + * Constructs a {@code StreamHandler} object with the supplied output * stream. Default properties are read. * * @param os - * the output stream this handler writes to + * the output stream this handler writes to. */ StreamHandler(OutputStream os) { this(); @@ -87,8 +90,8 @@ public class StreamHandler extends Handler { } /** - * Constructs a <code>StreamHandler</code> object. Specified default - * values will be used if the corresponding properties are found in log + * Constructs a {@code StreamHandler} object. The specified default values + * will be used if the corresponding properties are not found in the log * manager's properties. */ StreamHandler(String defaultLevel, String defaultFilter, @@ -101,13 +104,16 @@ public class StreamHandler extends Handler { } /** - * Constructs a <code>StreamHandler</code> object with the supplied output - * stream and formatter. + * Constructs a {@code StreamHandler} object with the supplied output stream + * and formatter. * * @param os - * the output stream this handler writes to + * the output stream this handler writes to. * @param formatter - * the formatter this handler uses to format the output + * the formatter this handler uses to format the output. + * @throws NullPointerException + * if {@code os} or {@code formatter} is {@code null}. + * @since Android 1.0 */ public StreamHandler(OutputStream os, Formatter formatter) { this(); @@ -166,13 +172,16 @@ public class StreamHandler extends Handler { /** * Sets the output stream this handler writes to. If there's an existing * output stream, the tail string of the associated formatter will be - * written to it. Then it will be flushed and closed. + * written to it. Then it will be flushed, closed and replaced with + * {@code os}. * * @param os - * the new output stream + * the new output stream. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @throws NullPointerException + * if {@code os} is {@code null}. */ protected void setOutputStream(OutputStream os) { if (null == os) { @@ -186,16 +195,17 @@ public class StreamHandler extends Handler { } /** - * Sets the character encoding used by this handler. A <code>null</code> - * value indicates the using of the default encoding. + * Sets the character encoding used by this handler. A {@code null} value + * indicates that the default encoding should be used. * * @param encoding - * the character encoding to set + * the character encoding to set. * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. * @throws UnsupportedEncodingException - * If the specified encoding is not supported by the runtime. + * if the specified encoding is not supported by the runtime. + * @since Android 1.0 */ @Override public void setEncoding(String encoding) throws SecurityException, @@ -222,11 +232,11 @@ public class StreamHandler extends Handler { } /** - * Closes this handler, but the underlying output stream is only closed when - * <code>closeStream</code> is <code>true</code>. Security is not checked. + * Closes this handler, but the underlying output stream is only closed if + * {@code closeStream} is {@code true}. Security is not checked. * * @param closeStream - * whether to close the underlying output stream + * whether to close the underlying output stream. */ void close(boolean closeStream) { if (null != this.os) { @@ -251,13 +261,14 @@ public class StreamHandler extends Handler { /** * Closes this handler. The tail string of the formatter associated with - * this handler will be written out. A flush operation a subsequent close - * operation will then be performed upon the outputstream. Client - * applications should not use a handler after closing it. + * this handler is written out. A flush operation and a subsequent close + * operation is then performed upon the output stream. Client applications + * should not use a handler after closing it. * * @throws SecurityException - * If a security manager determines that the caller does not + * if a security manager determines that the caller does not * have the required permission. + * @since Android 1.0 */ @Override public void close() { @@ -267,6 +278,8 @@ public class StreamHandler extends Handler { /** * Flushes any buffered output. + * + * @since Android 1.0 */ @Override public void flush() { @@ -286,21 +299,20 @@ public class StreamHandler extends Handler { } /** - * Accepts an actual logging request. The log record will be formatted and - * written to the output stream if the following three conditions are met: + * Accepts a logging request. The log record is formatted and written to the + * output stream if the following three conditions are met: * <ul> * <li>the supplied log record has at least the required logging level; * <li>the supplied log record passes the filter associated with this - * handler if any; - * <li>the output stream associated with this handler is not - * <code>null</code>. + * handler, if any; + * <li>the output stream associated with this handler is not {@code null}. * </ul> - * If it is the first time a log record need to be written out, the head - * string of the formatter associated with this handler will be written out - * first. + * If it is the first time a log record is written out, the head string of + * the formatter associated with this handler is written out first. * * @param record - * the log record to be logged + * the log record to be logged. + * @since Android 1.0 */ @Override public synchronized void publish(LogRecord record) { @@ -327,14 +339,19 @@ public class StreamHandler extends Handler { } /** - * Determines whether the supplied log record need to be logged. The logging - * levels will be checked as well as the filter. The output stream of this - * handler is also checked. If it's null, this method returns false. + * Determines whether the supplied log record needs to be logged. The + * logging levels are checked as well as the filter. The output stream of + * this handler is also checked. If it is {@code null}, this method returns + * {@code false}. + * <p> + * Notice : Case of no output stream will return {@code false}. + * </p> * * @param record - * the log record to be checked - * @return <code>true</code> if the supplied log record need to be logged, - * otherwise <code>false</code> + * the log record to be checked. + * @return {@code true} if {@code record} needs to be logged, {@code false} + * otherwise. + * @since Android 1.0 */ @Override public boolean isLoggable(LogRecord record) { diff --git a/logging/src/main/java/java/util/logging/XMLFormatter.java b/logging/src/main/java/java/util/logging/XMLFormatter.java index f3ff280..6279d8c 100644 --- a/logging/src/main/java/java/util/logging/XMLFormatter.java +++ b/logging/src/main/java/java/util/logging/XMLFormatter.java @@ -25,12 +25,13 @@ import java.util.Date; import java.util.ResourceBundle; /** - * Format a given <code>LogRecord</code> into string represents XML. The DTD specified in - * Appendix A to Java Logging APIs specification is used. - * - * <code>XMLFormatter</code> uses given <code>Handler</code>'s encoding if has, otherwise - * uses default platform encoding instead. However, the UTF-8 is recommended encoding. + * Formatter to convert a {@link LogRecord} into an XML string. The DTD + * specified in Appendix A to the Java Logging APIs specification is used. + * {@code XMLFormatter} uses the output handler's encoding if it is specified, + * otherwise the default platform encoding is used instead. UTF-8 is the + * recommended encoding. * + * @since Android 1.0 */ public class XMLFormatter extends Formatter { @@ -40,17 +41,21 @@ public class XMLFormatter extends Formatter { private static final String indent = " "; //$NON-NLS-1$ /** - * Default constructor + * Constructs a new {@code XMLFormatter}. + * + * @since Android 1.0 */ public XMLFormatter() { super(); } /** - * Format a <code>LogRecord</code> into string which represents XML + * Converts a {@code LogRecord} into an XML string. * - * @param r the given LogRecord instance to be formatted - * @return string which represents XML + * @param r + * the log record to be formatted. + * @return the log record formatted as an XML string. + * @since Android 1.0 */ @Override public String format(LogRecord r) { @@ -160,11 +165,14 @@ public class XMLFormatter extends Formatter { } /** - * Return the header string for XML, use given handler's encoding if has, - * other wise use default platform encoding + * Returns the header string for a set of log records formatted as XML + * strings, using the output handler's encoding if it is defined, otherwise + * using the default platform encoding. * - * @param h the given handler - * @return the header string for XML + * @param h + * the output handler, may be {@code null}. + * @return the header string for log records formatted as XML strings. + * @since Android 1.0 */ @Override public String getHead(Handler h) { @@ -184,10 +192,13 @@ public class XMLFormatter extends Formatter { } /** - * Return the tail string for XML + * Returns the tail string for a set of log records formatted as XML + * strings. * - * @param h the given handler - * @return the tail string for XML + * @param h + * the output handler, may be {@code null}. + * @return the tail string for log records formatted as XML strings. + * @since Android 1.0 */ @Override @SuppressWarnings("unused") diff --git a/logging/src/main/java/java/util/logging/package.html b/logging/src/main/java/java/util/logging/package.html index 4cc90c9..c523c7a 100644 --- a/logging/src/main/java/java/util/logging/package.html +++ b/logging/src/main/java/java/util/logging/package.html @@ -3,7 +3,8 @@ <p> This package allows to add logging to any application. It supports different levels of importance of a message that needs to be - logged. Later the output can be filtered by this level. + logged. The output written to the target can be filtered by this level. </p> + @since Android 1.0 </body> </html> diff --git a/logging/src/main/java/org/apache/harmony/logging/internal/nls/Messages.java b/logging/src/main/java/org/apache/harmony/logging/internal/nls/Messages.java index e052773..87535ae 100644 --- a/logging/src/main/java/org/apache/harmony/logging/internal/nls/Messages.java +++ b/logging/src/main/java/org/apache/harmony/logging/internal/nls/Messages.java @@ -21,6 +21,10 @@ * if this tool runs again. Better make changes in the template file. */ +// BEGIN android-note +// Redundant code has been removed and is now called from MsgHelp. +// END android-note + package org.apache.harmony.logging.internal.nls; @@ -30,8 +34,9 @@ import java.util.Locale; import java.util.MissingResourceException; import java.util.ResourceBundle; -import org.apache.harmony.kernel.vm.VM; +// BEGIN android-changed import org.apache.harmony.luni.util.MsgHelp; +// END android-changed /** * This class retrieves strings from a resource bundle and returns them, @@ -48,9 +53,11 @@ import org.apache.harmony.luni.util.MsgHelp; * */ public class Messages { - + + // BEGIN android-changed private static final String sResource = "org.apache.harmony.logging.internal.nls.messages"; //$NON-NLS-1$ + // END android-changed /** * Retrieves a message which has no arguments. @@ -60,7 +67,9 @@ public class Messages { * @return String the message for that key in the system message bundle. */ static public String getString(String msg) { + // BEGIN android-changed return MsgHelp.getString(sResource, msg); + // END android-changed } /** @@ -127,6 +136,12 @@ public class Messages { * @return String the message for that key in the system message bundle. */ static public String getString(String msg, Object[] args) { + // BEGIN android-changed return MsgHelp.getString(sResource, msg, args); + // END android-changed } + + // BEGIN android-note + // Duplicate code was dropped in favor of using MsgHelp. + // END android-note } |