You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by nd...@apache.org on 2009/04/28 02:08:56 UTC
svn commit: r769208 - in
/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging:
SimpleFormatter.java SocketHandler.java StreamHandler.java XMLFormatter.java
Author: ndbeyer
Date: Tue Apr 28 00:08:56 2009
New Revision: 769208
URL: http://svn.apache.org/viewvc?rev=769208&view=rev
Log:
Apply second patch for HARMONY-6176 - Javadocs for java.util.logging.*
Modified:
harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SimpleFormatter.java
harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SocketHandler.java
harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/StreamHandler.java
harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/XMLFormatter.java
Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SimpleFormatter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SimpleFormatter.java?rev=769208&r1=769207&r2=769208&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SimpleFormatter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SimpleFormatter.java Tue Apr 28 00:08:56 2009
@@ -23,18 +23,25 @@
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.
*/
public class SimpleFormatter extends Formatter {
/**
- * Constructs a <code>SimpleFormatter</code> object.
+ * Constructs a new {@code SimpleFormatter}.
*/
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.
+ */
@Override
public String format(LogRecord r) {
StringBuilder sb = new StringBuilder();
Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SocketHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SocketHandler.java?rev=769208&r1=769207&r2=769208&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SocketHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/SocketHandler.java Tue Apr 28 00:08:56 2009
@@ -30,31 +30,28 @@
* 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
* this handler should connect to. There's no default value for this property.
* </ul>
- * </p>
* <p>
* This handler buffers the outgoing messages, but flushes each time a log
* record has been published.
- * </p>
* <p>
* This class is not thread-safe.
- * </p>
*/
public class SocketHandler extends StreamHandler {
@@ -68,15 +65,16 @@
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 {
@@ -88,20 +86,20 @@
}
/**
- * 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 {
@@ -167,7 +165,7 @@
* 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) {
Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/StreamHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/StreamHandler.java?rev=769208&r1=769207&r2=769208&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/StreamHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/StreamHandler.java Tue Apr 28 00:08:56 2009
@@ -25,26 +25,27 @@
import org.apache.harmony.logging.internal.nls.Messages;
/**
- * A <code>StreamHandler</code> object writes log messages to an output
- * stream, that is, an object of type <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> 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. A default value will be used if a property is
+ * not found or has an invalid value.
* <ul>
- * <li>java.util.logging.StreamHandler.encoding - the name of the character set
- * encoding. Default is the encoding used by the current platform.</li>
- * <li>java.util.logging.StreamHandler.filter - the name of the
- * <code>Filter</code> class. No <code>Filter</code> is used by default.</li>
- * <li>java.util.logging.StreamHandler.formatter - the name of the
- * <code>Formatter</code> class. Default is
- * <code>java.util.logging.SimpleFormatter</code>.</li>
- * <li>java.util.logging.StreamHandler.level - the log level for this
- * <code>Handler</code>. Default is <code>Level.INFO</code>.</li>
+ * <li>java.util.logging.StreamHandler.encoding specifies the encoding this
+ * handler will use to encode log messages. Default is the encoding used by the
+ * current platform.
+ * <li>java.util.logging.StreamHandler.filter specifies the name of the filter
+ * class to be associated with this handler. No <code>Filter</code> is used by
+ * default.
+ * <li>java.util.logging.StreamHandler.formatter specifies the name of the
+ * formatter class to be associated with this handler. Default is
+ * {@code java.util.logging.SimpleFormatter}.
+ * <li>java.util.logging.StreamHandler.level specifies the logging level.
+ * Defaults is {@code Level.INFO}.
* </ul>
- * </p>
* <p>
* This class is not thread-safe.
- * </p>
*/
public class StreamHandler extends Handler {
@@ -58,7 +59,7 @@
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.
*/
public StreamHandler() {
@@ -70,11 +71,11 @@
}
/**
- * 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();
@@ -82,8 +83,8 @@
}
/**
- * 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,
@@ -96,13 +97,15 @@
}
/**
- * 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}.
*/
public StreamHandler(OutputStream os, Formatter formatter) {
this();
@@ -160,13 +163,16 @@
/**
* 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) {
@@ -180,16 +186,16 @@
}
/**
- * Sets the character encoding used by this handler. A <code>null</code>
- * value indicates the using of the default encoding.
+ * Sets the character encoding used by this handler. 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.
*/
@Override
public void setEncoding(String encoding) throws SecurityException,
@@ -216,12 +222,11 @@
}
/**
- * 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) {
@@ -246,12 +251,12 @@
/**
* 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.
*/
@Override
@@ -282,21 +287,19 @@
}
/**
- * 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.
*/
@Override
public synchronized void publish(LogRecord record) {
@@ -324,14 +327,17 @@
}
/**
- * 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}.
+ *
* @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.
*/
@Override
public boolean isLoggable(LogRecord record) {
Modified: harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/XMLFormatter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/XMLFormatter.java?rev=769208&r1=769207&r2=769208&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/XMLFormatter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging/XMLFormatter.java Tue Apr 28 00:08:56 2009
@@ -24,11 +24,10 @@
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
+ * 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.
*/
public class XMLFormatter extends Formatter {
@@ -39,18 +38,18 @@
private static final String indent = " "; //$NON-NLS-1$
/**
- * Default constructor
+ * Constructs a new {@code XMLFormatter}.
*/
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
+ * the log record to be formatted.
+ * @return the log record formatted as an XML string.
*/
@SuppressWarnings("nls")
@Override
@@ -164,12 +163,13 @@
}
/**
- * Return the header string for XML, use given handler's encoding if has,
- * otherwise 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
+ * the output handler, may be {@code null}.
+ * @return the header string for log records formatted as XML strings.
*/
@SuppressWarnings("nls")
@Override
@@ -190,11 +190,12 @@
}
/**
- * 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
+ * the output handler, may be {@code null}.
+ * @return the tail string for log records formatted as XML strings.
*/
@Override
@SuppressWarnings("unused")