From dd828f42a5c83b4270d4fbf6fce2da1878f1e84a Mon Sep 17 00:00:00 2001 From: The Android Open Source Project Date: Wed, 17 Dec 2008 18:03:55 -0800 Subject: Code drop from //branches/cupcake/...@124589 --- .../java/java/util/logging/ConsoleHandler.java | 33 +- .../main/java/java/util/logging/ErrorManager.java | 38 +- .../main/java/java/util/logging/FileHandler.java | 275 ++-- .../src/main/java/java/util/logging/Filter.java | 16 +- .../src/main/java/java/util/logging/Formatter.java | 58 +- .../src/main/java/java/util/logging/Handler.java | 131 +- logging/src/main/java/java/util/logging/Level.java | 161 ++- .../main/java/java/util/logging/LogManager.java | 253 ++-- .../src/main/java/java/util/logging/LogRecord.java | 160 ++- .../src/main/java/java/util/logging/Logger.java | 518 ++++---- .../main/java/java/util/logging/LoggingMXBean.java | 69 +- .../java/java/util/logging/LoggingPermission.java | 18 +- .../main/java/java/util/logging/MemoryHandler.java | 127 +- .../java/java/util/logging/SimpleFormatter.java | 20 +- .../main/java/java/util/logging/SocketHandler.java | 42 +- .../main/java/java/util/logging/StreamHandler.java | 119 +- .../main/java/java/util/logging/XMLFormatter.java | 43 +- .../src/main/java/java/util/logging/package.html | 3 +- .../harmony/logging/internal/nls/Messages.java | 19 +- .../java/java/util/logging/LoggerExtension.java | 31 - .../logging/tests/java/util/logging/AllTests.java | 4 +- .../java/util/logging/ConsoleHandlerTest.java | 163 ++- .../tests/java/util/logging/ErrorManagerTest.java | 75 +- .../tests/java/util/logging/FileHandlerTest.java | 329 ++++- .../tests/java/util/logging/FilterTest.java | 30 +- .../tests/java/util/logging/FormatterTest.java | 94 +- .../tests/java/util/logging/HandlerTest.java | 305 ++++- .../logging/tests/java/util/logging/LevelTest.java | 284 +++- .../tests/java/util/logging/LevelTestResource.java | 4 + .../tests/java/util/logging/LogManagerTest.java | 453 ++++++- .../tests/java/util/logging/LogRecordTest.java | 184 ++- .../tests/java/util/logging/LoggerExtension.java | 33 - .../tests/java/util/logging/LoggerTest.java | 1388 +++++++++++++++++--- .../tests/java/util/logging/LoggingMXBeanTest.java | 137 ++ .../java/util/logging/LoggingPermissionTest.java | 36 + .../tests/java/util/logging/MemoryHandlerTest.java | 150 ++- .../tests/java/util/logging/MessagesTest.java | 134 ++ .../java/util/logging/SimpleFormatterTest.java | 59 +- .../tests/java/util/logging/SocketHandlerTest.java | 226 +++- .../tests/java/util/logging/StreamHandlerTest.java | 403 +++++- .../tests/java/util/logging/XMLFormatterTest.java | 73 +- 41 files changed, 5415 insertions(+), 1283 deletions(-) delete mode 100644 logging/src/test/java/java/util/logging/LoggerExtension.java delete mode 100644 logging/src/test/java/org/apache/harmony/logging/tests/java/util/logging/LoggerExtension.java create mode 100644 logging/src/test/java/org/apache/harmony/logging/tests/java/util/logging/LoggingMXBeanTest.java create mode 100644 logging/src/test/java/org/apache/harmony/logging/tests/java/util/logging/MessagesTest.java (limited to 'logging/src') 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 - * System.err. + * {@code System.err}. *

* This handler reads the following properties from the log manager to * initialize itself: *

*

*

* This class is not thread-safe. *

* + * @since Android 1.0 */ public class ConsoleHandler extends StreamHandler { /** - * Constructs a ConsoleHandler object. + * Constructs a {@code ConsoleHandler} object. + * + * @since Android 1.0 */ public ConsoleHandler() { super(System.err); } /** - * Closes this handler. The System.err 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; /** - *

* An error reporting facility for {@link Handler} implementations to record any - * error that may happen during logging. Handlers should report - * errors to an ErrorManager, instead of throwing exceptions, - * which would interfere with the log issuer's execution. - *

+ * 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 ErrorManager. + * Constructs an instance of {@code ErrorManager}. + * + * @since Android 1.0 */ public ErrorManager() { super(); @@ -87,13 +101,15 @@ public class ErrorManager { *

* * @param message - * The error message, which may be null. + * the error message, which may be {@code null}. * @param exception - * The exception associated with the error, which may be - * null. + * 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 Handler 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. *

- * 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. *

*

- * 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. *

*

- * XMLFormatter is default formatter for FileHandler. + * {@code XMLFormatter} is the default formatter for {@code FileHandler}. *

*

- * MemoryHandler will read following LogManager - * 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. *

*

*

- * 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: + *

* - *

- * Normally, the generation numbers are not larger than given file count and + *

+ * 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. *

*

- * The "%u" unique field is used to avoid conflicts and set to 0 at first. If - * one 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 + * 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. *

- * + * @since Android 1.0 */ public class FileHandler extends StreamHandler { @@ -148,17 +148,18 @@ public class FileHandler extends StreamHandler { int uniqueID = -1; /** - * Construct a FileHandler using LogManager - * 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 - * LogPermission("control") and other permission - * like FilePermission("write"), 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 FileHandler, 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 LogManager - * 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 - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if the pattern is null. + * 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 FileHandler, 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 - * append becomes the new instance's append mode. Other - * configuration is done using LogManager 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 - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if the pattern is null. + * 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 FileHandler, 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 - * LogManager 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 - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if pattern is null. + * 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 FileHandler, 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 LogManager - * 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 - * LogPermission("control") and other permission - * like FilePermission("write"), etc. - * @throws NullPointerException - * if pattern is null. + * 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 - * LogPermission("control") and other permission - * like FilePermission("write"), 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 LogRecord + * 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; /** - *

A Filter provides a mechanism for exercising fine-grained control over - * what records get logged.

+ * A {@code Filter} provides a mechanism for exercising fine-grained control + * over which records get logged. + * + * @since Android 1.0 */ public interface Filter { /** - *

Checks the {@link LogRecord} to determine if it should be logged.

+ * Checks {@code record} to determine if it should be logged. * - * @param record The {@link LogRecord} to be checked. - * @return true if the supplied log record needs to be - * logged, otherwise false + * @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; /** - * Formatter objects are used to format LogRecord - * objects into a string representation. Head and tail strings are sometime used - * to wrap a set of records. The getHead and getTail - * 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 Formatter object. + * Constructs a {@code Formatter} object. + * + * @since Android 1.0 */ protected Formatter() { super(); @@ -50,29 +53,34 @@ public abstract class Formatter { */ /** - * Formats a LogRecord object into a string representation. - * The resulted string is usually localized and includes the message field - * of the supplied LogRecord 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 LogRecord object into a localized string - * representation. This method can be regarded as a convenience for - * subclasses of Formatter to use. + * Formats a {@code LogRecord} object into a localized string + * representation. This is a convenience method for subclasses of {@code + * Formatter}. + *

+ * The message string is firstly localized using the {@code ResourceBundle} + * object associated with the supplied {@code LogRecord}. + *

*

- * The message string is firstly localized using the - * ResourceBundle object associated with the supplied - * LogRecord. + * Notice : if message contains "{0", then java.text.MessageFormat is used. + * Otherwise no formatting is performed. *

* * @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 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 Level.OFF. + * 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 Handler object with a default error manager, - * the default encoding, and the default logging level - * Level.ALL. 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 true if the supplied log record need to be logged, - * otherwise false + * 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 null - * 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 null - * 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 /** - * 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. + * {@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. *

* 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. *

- * + * @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 Level object. + * Parses a level name into a {@code Level} object. * * @param name - * the name of the desired level, which cannot be null - * @return a Level 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 name is null. + * if {@code name} is {@code null}. * @throws IllegalArgumentException - * if name 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 Level 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 name is null. + * @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 Level 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 name is null. + * @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 Level. + * Gets the name of this level. * - * @return the name of this Level + * @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 - * Level. + * Gets the name of the resource bundle associated with this level. * - * @return the name of the resource bundle associated with this - * Level + * @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 Level. + * Gets the integer value indicating this level. * - * @return the integer value indicating this Level + * @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. *

* - * @return The resolved instance. + * @return the resolved instance. */ private Object readResolve() { synchronized (levels) { @@ -280,10 +315,14 @@ public class Level implements Serializable { } /** - *

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. + * 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 Level, 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 Level 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 true if this object equals to the supplied object, - * otherwise false + * @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 Level object. + * Returns the hash code of this {@code Level} object. * - * @return the hash code of this Level 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 Level 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 Level 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; /** - * LogManager 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 - * Logger objects. + * {@code Logger} objects. *

- * There is only one global LogManager instance in the + * + * There is only one global {@code LogManager} instance in the * application, which can be get by calling static method - * LogManager.getLogManager(). This instance is created and + * {@link #getLogManager()}. This instance is created and * initialized during class initialization and cannot be changed. *

*

- * The LogManager 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 java.util.logging.LogManager will + * invalid, the default class {@link java.util.logging.LogManager} will * be used. *

*

- * When initialization, LogManager 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. *

*

* However, two optional system properties can be used to customize the initial - * configuration process of LogManager. + * configuration process of {@code LogManager}. *