harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ndbe...@apache.org
Subject svn commit: r769208 - in /harmony/enhanced/classlib/trunk/modules/logging/src/main/java/java/util/logging: SimpleFormatter.java SocketHandler.java StreamHandler.java XMLFormatter.java
Date Tue, 28 Apr 2009 00:08:56 GMT
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")



Mime
View raw message