harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [3/6] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Date Wed, 06 May 2009 08:33:22 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetSocketAddress.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetSocketAddress.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetSocketAddress.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetSocketAddress.java Wed May  6 08:33:17 2009
@@ -20,6 +20,10 @@
 import java.io.IOException;
 import java.io.ObjectInputStream;
 
+/**
+ * This class represents a socket endpoint described by a IP address and a port
+ * number. It is a concrete implementation of {@code SocketAddress} for IP.
+ */
 public class InetSocketAddress extends SocketAddress {
 
     private static final long serialVersionUID = 5076001401234631237L;
@@ -30,10 +34,29 @@
 
     private int port;
 
+    /**
+     * Creates a socket endpoint with the given port number {@code port} and the
+     * wildcard address {@code InetAddress.ANY}. The range for valid port numbers
+     * is between 0 and 65535 inclusive.
+     * 
+     * @param port
+     *            the specified port number to which this socket is bound.
+     */
     public InetSocketAddress(int port) {
         this((InetAddress) null, port);
     }
 
+    /**
+     * Creates a socket endpoint with the given port number {@code port} and
+     * {@code address}. The range for valid port numbers is between 0 and 65535
+     * inclusive. If {@code address} is {@code null} this socket is bound to the
+     * wildcard address {@code InetAddress.ANY}.
+     * 
+     * @param port
+     *            the specified port number to which this socket is bound.
+     * @param address
+     *            the specified address to which this socket is bound.
+     */
     public InetSocketAddress(InetAddress address, int port) {
         if (port < 0 || port > 65535) {
             throw new IllegalArgumentException();
@@ -47,12 +70,27 @@
         this.port = port;
     }
 
+    /**
+     * Creates a socket endpoint with the given port number {@code port} and the
+     * hostname {@code host}. The hostname is tried to be resolved and cannot be
+     * {@code null}. The range for valid port numbers is between 0 and 65535
+     * inclusive.
+     * 
+     * @param port
+     *            the specified port number to which this socket is bound.
+     * @param host
+     *            the specified hostname to which this socket is bound.
+     * @throws SecurityException
+     *             if a {@link SecurityManager} is installed and its {@code
+     *             checkConnect()} method does not allow the resolving of the
+     *             host name.
+     */
     public InetSocketAddress(String host, int port) {
         this(host, port, true);
     }
 
     /*
-     * Internal constructor for InetSocketAddress(String, int) and
+     * Internal contructor for InetSocketAddress(String, int) and
      * createUnresolved(String, int);
      */
     InetSocketAddress(String host, int port, boolean needResolved) {
@@ -74,36 +112,66 @@
     }
 
     /**
-     * Creats an <code>InetSocketAddress</code> without trying to resolve
-     * hostname into an InetAddress. The address field is marked as unresolved.
+     * Creates an {@code InetSocketAddress} without trying to resolve the
+     * hostname into an {@code InetAddress}. The address field is marked as
+     * unresolved.
      * 
      * @param host
+     *            the specified hostname to which this socket is bound.
      * @param port
-     * @return an <code>InetSocketAddress</code> instance.
+     *            the specified port number to which this socket is bound.
+     * @return the created InetSocketAddress instance.
      * @throws IllegalArgumentException
-     *             if host is null or the port is not in the range between 0 and
-     *             65535.
+     *             if the hostname {@code host} is {@code null} or the port is
+     *             not in the range between 0 and 65535.
      */
     public static InetSocketAddress createUnresolved(String host, int port) {
         return new InetSocketAddress(host, port, false);
     }
 
+    /**
+     * Gets the port number of this socket.
+     * 
+     * @return the socket endpoint port number.
+     */
     public final int getPort() {
         return port;
     }
 
+    /**
+     * Gets the address of this socket.
+     * 
+     * @return the socket endpoint address.
+     */
     public final InetAddress getAddress() {
         return addr;
     }
 
+    /**
+     * Gets the hostname of this socket.
+     * 
+     * @return the socket endpoint hostname.
+     */
     public final String getHostName() {
         return (null != addr) ? addr.getHostName() : hostname;
     }
 
+    /**
+     * Returns whether this socket address is unresolved or not.
+     * 
+     * @return {@code true} if this socket address is unresolved, {@code false}
+     *         otherwise.
+     */
     public final boolean isUnresolved() {
         return addr == null;
     }
 
+    /**
+     * Gets a string representation of this socket included the address and the
+     * port number.
+     * 
+     * @return the address and port number as a textual representation.
+     */
     @Override
     public String toString() {
         String host;
@@ -115,6 +183,16 @@
         return host + ":" + port; //$NON-NLS-1$
     }
 
+    /**
+     * Compares two socket endpoints and returns true if they are equal. Two
+     * socket endpoints are equal if the IP address or the hostname of both are
+     * equal and they are bound to the same port.
+     * 
+     * @param socketAddr
+     *            the object to be tested for equality.
+     * @return {@code true} if this socket and the given socket object {@code
+     *         socketAddr} are equal, {@code false} otherwise.
+     */
     @Override
     public final boolean equals(Object socketAddr) {
         if (this == socketAddr) {
@@ -145,6 +223,11 @@
         return addr.equals(iSockAddr.addr);
     }
 
+    /**
+     * Gets the hashcode of this socket.
+     * 
+     * @return the appropriate hashcode.
+     */
     @Override
     public final int hashCode() {
         if (addr == null) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/JarURLConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/JarURLConnection.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/JarURLConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/JarURLConnection.java Wed May  6 08:33:17 2009
@@ -25,13 +25,25 @@
 import java.util.jar.Manifest;
 
 /**
- * This class establishes a connection to a URL using the jar protocol. Jar URLs
- * are specified as follows: <center><code>jar:<url>!/{entry}</code></center>
- * where "!/" is called a seperator.
+ * This class establishes a connection to a {@code jar:} URL using the {@code
+ * JAR} protocol. A {@code JarURLConnection} instance can refer to either a JAR
+ * archive file or to an entry of such a file. {@code jar:} URLs are specified
+ * as follows: <i>jar:{archive-url}!/{entry}</i> where "!/" is called a
+ * separator. This separator is important to determine if an archive or an entry
+ * of an archive is referred.
+ * <p>
+ * Examples:
+ * <li>Archive: {@code jar:http://www.example.com/applets/archive.jar!/}</li>
+ * <li>File Entry: {@code
+ * jar:http://www.example.com/applets/archive.jar!/test.class}</li>
+ * <li>Directory Entry: {@code
+ * jar:http://www.example.com/applets/archive.jar!/applets/}</li>
  */
 public abstract class JarURLConnection extends URLConnection {
 
-    // the location of the separator
+    /**
+     * The location part of the represented URL.
+     */
     protected URLConnection jarFileURLConnection;
 
     private String entryName;
@@ -42,10 +54,13 @@
     private String file;
 
     /**
-     * Constructs an instance of <code>JarURLConnection</code>.
+     * Constructs an instance of {@code JarURLConnection} that refers to the
+     * specified URL.
      * 
      * @param url
-     *            java.net.URL the URL that contains the location to connect to
+     *            the URL that contains the location to connect to.
+     * @throws MalformedURLException
+     *             if an invalid URL has been entered.
      */
     protected JarURLConnection(URL url) throws MalformedURLException {
         super(url);
@@ -66,13 +81,13 @@
     }
 
     /**
-     * Answers the attributes of the JarEntry referenced by this
-     * <code>JarURLConnection</code>.
+     * Returns all attributes of the {@code JarEntry} referenced by this {@code
+     * JarURLConnection}.
      * 
-     * @return java.util.jar.Attributes the attributes of the the JarEntry
-     * @exception java.io.IOException
-     *                thrown if an IO exception occurs while retrieving the
-     *                JarEntry
+     * @return the attributes of the referenced {@code JarEntry}.
+     * @throws IOException
+     *                if an I/O exception occurs while retrieving the
+     *                JAR-entries.
      */
     public Attributes getAttributes() throws java.io.IOException {
         JarEntry jEntry = getJarEntry();
@@ -80,14 +95,14 @@
     }
 
     /**
-     * Answers the Certificates of the JarEntry referenced by this
-     * <code>URLConnection</code>. This method will return null until the
-     * InputStream has been completely verified
-     * 
-     * @return Certificate[] the Certificates of the JarEntry.
-     * @exception java.io.IOException
-     *                thrown if there is an IO exception occurs while getting
-     *                the JarEntry.
+     * Returns all certificates of the {@code JarEntry} referenced by this
+     * {@code JarURLConnection} instance. This method will return {@code null}
+     * until the {@code InputStream} has been completely verified.
+     * 
+     * @return the certificates of the {@code JarEntry} as an array.
+     * @throws IOException
+     *                if there is an I/O exception occurs while getting the
+     *                {@code JarEntry}.
      */
     public Certificate[] getCertificates() throws java.io.IOException {
         JarEntry jEntry = getJarEntry();
@@ -99,20 +114,24 @@
     }
 
     /**
-     * Answers the JarEntry name of the entry referenced by this
-     * <code>URLConnection</code>.
+     * Gets the name of the entry referenced by this {@code JarURLConnection}.
+     * The return value will be {@code null} if this instance refers to a JAR
+     * file rather than an JAR file entry.
      * 
-     * @return java.lang.String the JarEntry name
+     * @return the {@code JarEntry} name this instance refers to.
      */
     public String getEntryName() {
         return entryName;
     }
 
     /**
-     * Answers the JarEntry of the entry referenced by this
-     * <code>URLConnection</code>.
-     * 
-     * @return java.util.jar.JarEntry the JarEntry referenced
+     * Gets the {@code JarEntry} object of the entry referenced by this {@code
+     * JarURLConnection}.
+     *
+     * @return the referenced {@code JarEntry} object or {@code null} if no
+     *         entry name is specified.
+     * @throws IOException
+     *             if an error occurs while getting the file or file-entry.
      */
     public JarEntry getJarEntry() throws IOException {
         if (!connected) {
@@ -126,42 +145,45 @@
     }
 
     /**
-     * Answers the Manifest associated with the Jar URL
+     * Gets the manifest file associated with this JAR-URL.
      * 
-     * @return java.util.jar.Manifest The JarFile's Manifest
+     * @return the manifest of the referenced JAR-file.
+     * @throws IOException
+     *             if an error occurs while getting the manifest file.
      */
     public Manifest getManifest() throws java.io.IOException {
         return (Manifest)getJarFile().getManifest().clone();
     }
 
     /**
-     * Answers the the JarFile referenced by this <code>URLConnection</code>.
+     * Gets the {@code JarFile} object referenced by this {@code
+     * JarURLConnection}.
      * 
-     * @return java.util.jar.JarFile the JarFile
-     * @exception java.io.IOException
-     *                thrown if an IO exception occurs while retrieving the Jar
-     *                file
+     * @return the referenced JarFile object.
+     * @throws IOException
+     *                if an I/O exception occurs while retrieving the JAR-file.
      */
     public abstract JarFile getJarFile() throws java.io.IOException;
 
     /**
-     * Answers the URL of the JarFile referenced by this
-     * <code>URLConnection</code>.
+     * Gets the URL to the JAR-file referenced by this {@code JarURLConnection}.
      * 
-     * @return java.net.URL the URL of the JarFile.
+     * @return the URL to the JAR-file or {@code null} if there was an error
+     *         retrieving the URL.
      */
     public URL getJarFileURL() {
         return fileURL;
     }
 
     /**
-     * Answers the main Attributes of the JarFile referenced by this
-     * <code>URLConnection</code>.
-     * 
-     * @return java.util.jar.Attributes the Attributes of the the JarFile
-     * @exception java.io.IOException
-     *                thrown if an IO exception occurs while retrieving the
-     *                JarFile
+     * Gets all attributes of the manifest file referenced by this {@code
+     * JarURLConnection}. If this instance refers to a JAR-file rather than a
+     * JAR-file entry, {@code null} will be returned.
+     * 
+     * @return the attributes of the manifest file or {@code null}.
+     * @throws IOException
+     *                if an I/O exception occurs while retrieving the {@code
+     *                JarFile}.
      */
     public Attributes getMainAttributes() throws java.io.IOException {
         Manifest m = getJarFile().getManifest();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MalformedURLException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MalformedURLException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MalformedURLException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MalformedURLException.java Wed May  6 08:33:17 2009
@@ -41,7 +41,7 @@
      * filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception instance.
      */
     public MalformedURLException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MulticastSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MulticastSocket.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MulticastSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MulticastSocket.java Wed May  6 08:33:17 2009
@@ -24,9 +24,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class models a multicast socket for sending & receiving datagram packets
- * to a multicast group.
- * 
+ * This class implements a multicast socket for sending and receiving IP
+ * multicast datagram packets.
+ *
  * @see DatagramSocket
  */
 public class MulticastSocket extends DatagramSocket {
@@ -40,7 +40,7 @@
      * localhost.
      * 
      * @throws IOException
-     *             if a problem occurs creating or binding the socket
+     *             if an error occurs creating or binding the socket.
      */
     public MulticastSocket() throws IOException {
         super();
@@ -48,13 +48,13 @@
     }
 
     /**
-     * Answers a multicast socket, bound to the nominated port on the localhost.
+     * Constructs a multicast socket, bound to the specified port on the
+     * localhost.
      * 
      * @param aPort
-     *            the port to bind on the localhost
-     * 
+     *            the port to bind on the localhost.
      * @throws IOException
-     *             if a problem occurs creating or binding the socket
+     *             if an error occurs creating or binding the socket.
      */
     public MulticastSocket(int aPort) throws IOException {
         super(aPort);
@@ -62,12 +62,13 @@
     }
 
     /**
-     * Answer the network address used by the socket. This is useful on
-     * multi-homed machines.
+     * Gets the network address used by this socket. This is useful on
+     * multihomed machines.
      * 
-     * @return java.net.InetAddress the network address
-     * @exception java.net.SocketException
-     *                The exception thrown while getting the address
+     * @return the address of the network interface through which the datagram
+     *         packets are sent or received.
+     * @throws SocketException
+     *                if an error occurs while getting the interface address.
      */
     public InetAddress getInterface() throws SocketException {
         checkClosedAndBind(false);
@@ -97,13 +98,13 @@
     }
 
     /**
-     * Answer the network interface used by the socket. This is useful on
-     * multi-homed machines.
-     * 
-     * @return java.net.NetworkInterface the network address
-     * @exception java.net.SocketException
-     *                The exception thrown while getting the address
+     * Gets the network interface used by this socket. This is useful on
+     * multihomed machines.
      * 
+     * @return the network interface used by this socket or {@code null} if no
+     *         interface is set.
+     * @throws SocketException
+     *                if an error occurs while getting the interface.
      * @since 1.4
      */
     public NetworkInterface getNetworkInterface() throws SocketException {
@@ -156,11 +157,11 @@
     }
 
     /**
-     * Answer the time-to-live (TTL) for multicast packets sent on this socket.
+     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
      * 
-     * @return java.net.InetAddress
-     * @exception IOException
-     *                The exception description.
+     * @return the default value for the time-to-life field.
+     * @throws IOException
+     *                if an error occurs reading the default value.
      */
     public int getTimeToLive() throws IOException {
         checkClosedAndBind(false);
@@ -168,12 +169,12 @@
     }
 
     /**
-     * Answer the time-to-live (TTL) for multicast packets sent on this socket.
+     * Gets the time-to-live (TTL) for multicast packets sent on this socket.
      * 
-     * @return java.net.InetAddress
-     * @exception IOException
-     *                The exception description.
-     * @deprecated Replaced by getTimeToLive
+     * @return the default value for the time-to-life field.
+     * @throws IOException
+     *                if an error occurs reading the default value.
+     * @deprecated Replaced by {@link #getTimeToLive}
      * @see #getTimeToLive()
      */
     @Deprecated
@@ -183,14 +184,14 @@
     }
 
     /**
-     * Add this socket to the multicast group. A socket must joint a group
-     * before data may be received. A socket may be a member of multiple groups
-     * but may join any group once.
+     * Adds this socket to the specified multicast group. A socket must join a
+     * group before data may be received. A socket may be a member of multiple
+     * groups but may join any group only once.
      * 
      * @param groupAddr
-     *            the multicast group to be joined
-     * @exception IOException
-     *                may be thrown while joining a group
+     *            the multicast group to be joined.
+     * @throws IOException
+     *                if an error occurs while joining a group.
      */
     public void joinGroup(InetAddress groupAddr) throws IOException {
         checkClosedAndBind(false);
@@ -205,21 +206,21 @@
     }
 
     /**
-     * Add this socket to the multicast group. A socket must join a group before
-     * data may be received. A socket may be a member of multiple groups but may
-     * join any group once.
+     * Adds this socket to the specified multicast group. A socket must join a
+     * group before data may be received. A socket may be a member of multiple
+     * groups but may join any group only once.
      * 
      * @param groupAddress
-     *            the multicast group to be joined
+     *            the multicast group to be joined.
      * @param netInterface
-     *            the network interface on which the addresses should be dropped
-     * @exception IOException
-     *                will be thrown if address is not a multicast address
-     * @exception java.lang.SecurityException
-     *                will be thrown if caller is not authorized to join group
-     * @exception java.lang.IllegalArgumentException
-     *                will be through if groupAddr is null
-     * 
+     *            the network interface on which the datagram packets will be
+     *            received.
+     * @throws IOException
+     *                if the specified address is not a multicast address.
+     * @throws SecurityException
+     *                if the caller is not authorized to join the group.
+     * @throws IllegalArgumentException
+     *                if no multicast group is specified.
      * @since 1.4
      */
     public void joinGroup(SocketAddress groupAddress,
@@ -257,16 +258,16 @@
     }
 
     /**
-     * Remove the socket from the multicast group.
+     * Removes this socket from the specified multicast group.
      * 
      * @param groupAddr
-     *            the multicast group to be left
-     * @exception IOException
-     *                will be thrown if address is not a multicast address
-     * @exception java.lang.SecurityException
-     *                will be thrown if caller is not authorized to join group
-     * @exception java.lang.IllegalArgumentException
-     *                will be through if groupAddr is null
+     *            the multicast group to be left.
+     * @throws NullPointerException
+     *                if {@code groupAddr} is {@code null}.
+     * @throws IOException
+     *                if the specified group address is not a multicast address.
+     * @throws SecurityException
+     *                if the caller is not authorized to leave the group.
      */
     public void leaveGroup(InetAddress groupAddr) throws IOException {
         checkClosedAndBind(false);
@@ -281,19 +282,19 @@
     }
 
     /**
-     * Remove the socket from the multicast group.
+     * Removes this socket from the specified multicast group.
      * 
      * @param groupAddress
-     *            the multicast group to be left
+     *            the multicast group to be left.
      * @param netInterface
-     *            the network interface on which the addresses should be dropped
-     * @exception IOException
-     *                will be thrown if address is not a multicast address
-     * @exception java.lang.SecurityException
-     *                will be thrown if caller is not authorized to join group
-     * @exception java.lang.IllegalArgumentException
-     *                will be through if groupAddr is null
-     * 
+     *            the network interface on which the addresses should be
+     *            dropped.
+     * @throws IOException
+     *                if the specified group address is not a multicast address.
+     * @throws SecurityException
+     *                if the caller is not authorized to leave the group.
+     * @throws IllegalArgumentException
+     *                if {@code groupAddress} is {@code null}.
      * @since 1.4
      */
     public void leaveGroup(SocketAddress groupAddress,
@@ -334,15 +335,13 @@
      * policy before it may be sent.
      * 
      * @param pack
-     *            the DatagramPacket to send
+     *            the {@code DatagramPacket} to send
      * @param ttl
      *            the TTL setting for this transmission, overriding the socket
      *            default
-     * 
-     * @exception IOException
-     *                If a send error occurs.
-     * 
-     * @deprecated use MulticastSocket#setTimeToLive
+     * @throws IOException
+     *                if an error occurs while sending data or setting options.
+     * @deprecated use {@link #setTimeToLive}.
      */
     @Deprecated
     public void send(DatagramPacket pack, byte ttl) throws IOException {
@@ -370,13 +369,15 @@
     }
 
     /**
-     * Set the network address used by the socket. This is useful on multi-homed
-     * machines.
+     * Sets the interface address used by this socket. This allows to send
+     * multicast packets on a different interface than the default interface of
+     * the local system. This is useful on multihomed machines.
      * 
      * @param addr
-     *            java.net.InetAddress the interface network address
-     * @exception java.net.SocketException
-     *                the exception may be thrown while setting the address
+     *            the multicast interface network address to set.
+     * @throws SocketException
+     *                if an error occurs while setting the network interface
+     *                address option.
      */
     public void setInterface(InetAddress addr) throws SocketException {
         checkClosedAndBind(false);
@@ -419,14 +420,14 @@
     }
 
     /**
-     * Set the network interface used by the socket. This is useful on
-     * multi-homed machines.
+     * Sets the network interface used by this socket. This is useful for
+     * multihomed machines.
      * 
      * @param netInterface
-     *            NetworkInterface the interface to be used
-     * @exception java.net.SocketException
-     *                the exception may be thrown while setting the address
-     * 
+     *            the multicast network interface to set.
+     * @throws SocketException
+     *                if an error occurs while setting the network interface
+     *                option.
      * @since 1.4
      */
     public void setNetworkInterface(NetworkInterface netInterface)
@@ -513,12 +514,14 @@
     }
 
     /**
-     * Set the time-to-live (TTL) for multicast packets sent on this socket.
-     * 
+     * Sets the time-to-live (TTL) for multicast packets sent on this socket.
+     * Valid TTL values are between 0 and 255 inclusive.
+     *
      * @param ttl
-     *            the time-to-live, 0<=ttl<= 255
-     * @exception IOException
-     *                The exception thrown while setting the TTL
+     *            the default time-to-live field value for packets sent on this
+     *            socket. {@code 0 <= ttl <= 255}.
+     * @throws IOException
+     *                if an error occurs while setting the TTL option value.
      */
     public void setTimeToLive(int ttl) throws IOException {
         checkClosedAndBind(false);
@@ -529,13 +532,15 @@
     }
 
     /**
-     * Set the time-to-live (TTL) for multicast packets sent on this socket.
-     * 
+     * Sets the time-to-live (TTL) for multicast packets sent on this socket.
+     * Valid TTL values are between 0 and 255 inclusive.
+     *
      * @param ttl
-     *            the time-to-live, 0<ttl<= 255
-     * @exception IOException
-     *                The exception thrown while setting the TTL
-     * @deprecated Replaced by setTimeToLive
+     *            the default time-to-live field value for packets sent on this
+     *            socket: {@code 0 <= ttl <= 255}.
+     * @throws IOException
+     *                if an error occurs while setting the TTL option value.
+     * @deprecated Replaced by {@link #setTimeToLive}
      * @see #setTimeToLive(int)
      */
     @Deprecated
@@ -561,17 +566,16 @@
     }
 
     /**
-     * Constructs a MulticastSocket bound to the host/port specified by the
-     * SocketAddress, or an unbound DatagramSocket if the SocketAddress is null.
+     * Constructs a {@code MulticastSocket} bound to the host/port specified by
+     * the {@code SocketAddress}, or an unbound {@code DatagramSocket} if the
+     * {@code SocketAddress} is {@code null}.
      * 
      * @param localAddr
-     *            the local machine address and port to bind to
-     * 
+     *            the local machine address and port to bind to.
      * @throws IllegalArgumentException
-     *             if the SocketAddress is not supported
+     *             if the {@code SocketAddress} is not supported.
      * @throws IOException
-     *             if a problem occurs creating or binding the socket
-     * 
+     *             if an error occurs creating or binding the socket.
      * @since 1.4
      */
     public MulticastSocket(SocketAddress localAddr) throws IOException {
@@ -580,14 +584,12 @@
     }
 
     /**
-     * Get the state of the IP_MULTICAST_LOOP socket option.
-     * 
-     * @return <code>true</code> if the IP_MULTICAST_LOOP is enabled,
-     *         <code>false</code> otherwise.
+     * Gets the state of the {@code SocketOptions.IP_MULTICAST_LOOP}.
      * 
+     * @return {@code true} if the IP multicast loop is enabled, {@code false}
+     *         otherwise.
      * @throws SocketException
      *             if the socket is closed or the option is invalid.
-     * 
      * @since 1.4
      */
     public boolean getLoopbackMode() throws SocketException {
@@ -597,14 +599,13 @@
     }
 
     /**
-     * Set the IP_MULTICAST_LOOP socket option.
+     * Sets the {@code SocketOptions.IP_MULTICAST_LOOP}.
      * 
      * @param loop
-     *            the socket IP_MULTICAST_LOOP option setting
-     * 
+     *            the value for the socket option socket {@code
+     *            SocketOptions.IP_MULTICAST_LOOP}.
      * @throws SocketException
      *             if the socket is closed or the option is invalid.
-     * 
      * @since 1.4
      */
     public void setLoopbackMode(boolean loop) throws SocketException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegCacheElement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegCacheElement.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegCacheElement.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegCacheElement.java Wed May  6 08:33:17 2009
@@ -17,7 +17,9 @@
 package java.net;
 
 /**
- * This class is used to hold information about failed name lookups
+ * This class is used to hold information about failed host name lookups.
+ *
+ * @see NegativeCache
  */
 class NegCacheElement {
 
@@ -28,10 +30,11 @@
     final String hostName;
 
     /**
-     * Constructor used to set the hostname for the failed entry
+     * Constructor used to set the hostname for the entry for which the lookup
+     * failed.
      * 
      * @param hostName
-     *            name of the host on which the lookup failed
+     *            name of the host for which the lookup failed.
      */
     NegCacheElement(String hostName) {
         this.hostName = hostName;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegativeCache.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegativeCache.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegativeCache.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegativeCache.java Wed May  6 08:33:17 2009
@@ -23,7 +23,10 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * This class is used to manage the negative name lookup cache.
+ * This class is used to maintain the negative name lookup cache, which caches
+ * host names which could not be resolved, as a security feature.
+ *
+ * @see NegCacheElement
  */
 class NegativeCache<K, V> extends LinkedHashMap<K, V> {
 
@@ -38,22 +41,22 @@
     private static final float LOADING = 0.75F;
 
     /**
-     * Answers the hostname for the cache element
+     * Returns the hostname for the cache element.
      * 
-     * @return hostName name of the host on which the lookup failed
+     * @return hostName name of the host for which the lookup failed.
      */
     NegativeCache(int initialCapacity, float loadFactor, boolean accessOrder) {
         super(initialCapacity, loadFactor, accessOrder);
     }
 
     /**
-     * Answers if we should remove the Eldest entry. We remove the eldest entry
-     * if the size has grown beyond the maximum size allowed for the cache. We
-     * create the LinkedHashMap such that this deletes the least recently used
-     * entry
+     * Returns whether the eldest entry should be removed. It is removed if the
+     * size has grown beyond the maximum size allowed for the cache. A {@code
+     * LinkedHashMap} is created such that the least recently used entry is
+     * deleted.
      * 
      * @param eldest
-     *            the map entry which will be deleted if we return true
+     *            the map entry which will be deleted if we return {@code true}.
      */
     @Override
     protected boolean removeEldestEntry(Map.Entry<K, V> eldest) {
@@ -62,12 +65,12 @@
 
     /**
      * Adds the host name and the corresponding name lookup fail message to the
-     * cache
+     * cache.
      * 
      * @param hostName
-     *            the name of the host for which the lookup failed
+     *            the name of the host for which the lookup failed.
      * @param failedMessage
-     *            the message returned when we failed the lookup
+     *            the message returned when the lookup fails.
      */
     static synchronized void put(String hostName, String failedMessage) {
         checkCacheExists();
@@ -75,13 +78,13 @@
     }
 
     /**
-     * Answers the message that occurred when we failed to lookup the host if
-     * such a failure is within the cache and the entry has not yet expired
+     * Returns the message of the negative cache if the entry has not yet
+     * expired.
      * 
      * @param hostName
-     *            the name of the host for which we are looking for an entry
-     * @return the message which was returned when the host failed to be looked
-     *         up if there is still a valid entry within the cache
+     *            the name of the host for which we look up the entry.
+     * @return the message which was returned when the host lookup failed if the
+     *         entry has not yet expired.
      */
     static synchronized String getFailedMessage(String hostName) {
         checkCacheExists();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetPermission.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetPermission.java Wed May  6 08:33:17 2009
@@ -18,7 +18,8 @@
 package java.net;
 
 /**
- * This class represents permission to access network resources.
+ * This class represents permissions to configure the access to network
+ * resources.
  * <p>
  * There are three valid target names:
  * <dl>
@@ -42,20 +43,20 @@
      * Creates an instance of this class with the given name.
      * 
      * @param name
-     *            String the name of the new permission.
+     *            the name of the new NetPermission instance.
      */
     public NetPermission(String name) {
         super(name);
     }
 
     /**
-     * Creates an instance of this class with the given name and action list.
-     * The action list is ignored.
+     * Creates an instance of this class with the given name and an action list.
+     * The action list is ignored and should be {@code null}.
      * 
      * @param name
-     *            String the name of the new permission.
+     *            the name of the new {@code NetPermission} instance.
      * @param actions
-     *            String ignored.
+     *            the ignored action string.
      */
     public NetPermission(String name, String actions) {
         super(name, actions);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetworkInterface.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetworkInterface.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetworkInterface.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetworkInterface.java Wed May  6 08:33:17 2009
@@ -24,8 +24,10 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class provides an methods that are used to get information about the
- * network interfaces supported by the system
+ * This class is used to represent a network interface of the local device. An
+ * interface is defined by its address and a platform dependent name. The class
+ * provides methods to get all information about the available interfaces of the
+ * system or to identify the local interface of a joined multicast group.
  */
 public final class NetworkInterface extends Object {
 
@@ -49,12 +51,12 @@
     private int hashCode;
 
     /**
-     * This native answers the list of network interfaces supported by the
-     * system. An array is returned which is easier to generate and which can
-     * easily be converted into the required enumeration on the java side
-     * 
-     * @return an array of zero or more NetworkInterface objects
+     * This {@code native} method returns the list of network interfaces
+     * supported by the system. An array is returned which is easier to generate
+     * and which can easily be converted into the required enumeration on the
+     * java side.
      * 
+     * @return an array of zero or more {@code NetworkInterface} objects
      * @throws SocketException
      *             if an error occurs when getting network interface information
      */
@@ -63,17 +65,17 @@
 
     /**
      * This constructor is used by the native method in order to construct the
-     * NetworkInterface objects in the array that it returns
+     * NetworkInterface objects in the array that it returns.
      * 
      * @param name
-     *            internal name associated with the interface
+     *            internal name associated with the interface.
      * @param displayName
-     *            a user interpretable name for the interface
+     *            a user interpretable name for the interface.
      * @param addresses
-     *            the Internet addresses associated with the interface
+     *            the Internet addresses associated with the interface.
      * @param interfaceIndex
      *            an index for the interface. Only set for platforms that
-     *            support IPV6
+     *            support IPV6.
      */
     NetworkInterface(String name, String displayName, InetAddress addresses[],
             int interfaceIndex) {
@@ -84,7 +86,7 @@
     }
 
     /**
-     * Answers the index for the network interface. Unless the system supports
+     * Returns the index for the network interface. Unless the system supports
      * IPV6 this will be 0.
      * 
      * @return the index
@@ -94,7 +96,7 @@
     }
 
     /**
-     * Answers the first address for the network interface. This is used in the
+     * Returns the first address for the network interface. This is used in the
      * natives when we need one of the addresses for the interface and any one
      * will do
      * 
@@ -108,18 +110,18 @@
     }
 
     /**
-     * Answers the name associated with the network interface
+     * Gets the name associated with this network interface.
      * 
-     * @return name associated with the network interface
+     * @return the name of this {@code NetworkInterface} instance.
      */
     public String getName() {
         return name;
     }
 
     /**
-     * Answers the list of internet addresses bound to the interface
+     * Gets a list of addresses bound to this network interface.
      * 
-     * @return list of internet addresses bound to the interface
+     * @return the address list of the represented network interface.
      */
     public Enumeration<InetAddress> getInetAddresses() {
         /*
@@ -182,10 +184,10 @@
     }
 
     /**
-     * Answers the user readable name associated with the network interface
+     * Gets the human-readable name associated with this network interface.
      * 
-     * @return display name associated with the network interface or null if one
-     *         is not available
+     * @return the display name of this network interface or the name if the
+     *         display name is not available.
      */
     public String getDisplayName() {
         /*
@@ -199,14 +201,17 @@
     }
 
     /**
-     * Answers the network interface with the specified name, if one exists
-     * 
-     * @return network interface for name specified if it exists, otherwise null
+     * Gets the specific network interface according to a given name.
      * 
+     * @param interfaceName
+     *            the name to identify the searched network interface.
+     * @return the network interface with the specified name if one exists or
+     *         {@code null} otherwise.
      * @throws SocketException
-     *             if an error occurs when getting network interface information
+     *             if an error occurs while getting the network interface
+     *             information.
      * @throws NullPointerException
-     *             if the interface name passed in is null
+     *             if the given interface's name is {@code null}.
      */
     public static NetworkInterface getByName(String interfaceName)
             throws SocketException {
@@ -232,18 +237,17 @@
     }
 
     /**
-     * Answers the network interface which has the specified internet address
-     * bound to it, if one exists.
-     * 
+     * Gets the specific network interface according to the given address.
+     *
      * @param address
-     *            address of interest
-     * @return network interface for internet address specified if it exists,
-     *         otherwise null
-     * 
+     *            the address to identify the searched network interface.
+     * @return the network interface with the specified address if one exists or
+     *         {@code null} otherwise.
      * @throws SocketException
-     *             if an error occurs when getting network interface information
+     *             if an error occurs while getting the network interface
+     *             information.
      * @throws NullPointerException
-     *             if the address passed in is null
+     *             if the given interface address is invalid.
      */
     public static NetworkInterface getByInetAddress(InetAddress address)
             throws SocketException {
@@ -283,14 +287,14 @@
     }
 
     /**
-     * Answers the list of network interfaces supported by the system or null if
-     * no interfaces are supported by the system
-     * 
-     * @return Enumeration containing one NetworkInterface object for each
-     *         interface supported by the system
+     * Gets a list of all network interfaces available on the local system or
+     * {@code null} if no interface is available.
      * 
+     * @return the list of {@code NetworkInterface} instances representing the
+     *         available interfaces.
      * @throws SocketException
-     *             if an error occurs when getting network interface information
+     *             if an error occurs while getting the network interface
+     *             information.
      */
     public static Enumeration<NetworkInterface> getNetworkInterfaces()
             throws SocketException {
@@ -321,15 +325,15 @@
     }
 
     /**
-     * Compares the specified object to this NetworkInterface and answer if they
-     * are equal. The object must be an instance of NetworkInterface with the
-     * same name, displayName and list of network interfaces to be the same
+     * Compares the specified object to this {@code NetworkInterface} and
+     * returns whether they are equal or not. The object must be an instance of
+     * {@code NetworkInterface} with the same name, {@code displayName} and list
+     * of network interfaces to be equal.
      * 
      * @param obj
-     *            the object to compare
-     * @return true if the specified object is equal to this NetworkInterfcae,
-     *         false otherwise
-     * 
+     *            the object to compare with this instance.
+     * @return {@code true} if the specified object is equal to this {@code
+     *         NetworkInterface}, {@code false} otherwise.
      * @see #hashCode
      */
     @Override
@@ -394,11 +398,11 @@
     }
 
     /**
-     * Answers a hash code for this NetworkInterface object. Since the name
-     * should be unique for each network interface the hash code is generated
-     * using this name
+     * Gets the hashcode for this {@code NetworkInterface} instance. Since the
+     * name should be unique for each network interface the hashcode is
+     * generated using this name.
      * 
-     * @return the hashcode for hashtable indexing
+     * @return the hashcode value for this {@code NetworkInterface} instance.
      */
     @Override
     public int hashCode() {
@@ -409,10 +413,10 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * network interface
+     * Gets a string containing a concise, human-readable description of this
+     * network interface.
      * 
-     * @return a printable representation for the network interface
+     * @return the textual representation for this network interface.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NoRouteToHostException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NoRouteToHostException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NoRouteToHostException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NoRouteToHostException.java Wed May  6 08:33:17 2009
@@ -18,27 +18,27 @@
 package java.net;
 
 /**
- * The NoRouteToHostException may be thrown when attempting to connect to a
- * remote machine and because of network fault or firewall, no route can be
- * established.
+ * The {@code NoRouteToHostException} will be thrown while attempting to connect
+ * to a remote host but the host cannot be reached for instance because of a
+ * badly configured router or a blocking firewall.
  */
 public class NoRouteToHostException extends SocketException {
 
     private static final long serialVersionUID = -1897550894873493790L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new instance of this exception with its walkback filled in.
      */
     public NoRouteToHostException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
+     * Constructs a new instance of this exception with its walkback and message
      * filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public NoRouteToHostException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PasswordAuthentication.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PasswordAuthentication.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PasswordAuthentication.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PasswordAuthentication.java Wed May  6 08:33:17 2009
@@ -18,7 +18,10 @@
 package java.net;
 
 /**
- * This class is a data structure that contains the username and password.
+ * This immutable class is a data structure that encapsulates username and
+ * password which is used by the {@code Authenticator} class.
+ *
+ * @see Authenticator
  */
 public final class PasswordAuthentication {
 
@@ -27,13 +30,13 @@
     private char[] password;
 
     /**
-     * Creates an instance of a password authentication with a username and
-     * password.
+     * Creates an instance of a password authentication with a specified
+     * username and password.
      * 
      * @param userName
-     *            java.lang.String the username
+     *            the username to store.
      * @param password
-     *            char[] the password
+     *            the associated password to store.
      */
     public PasswordAuthentication(String userName, char[] password) {
         this.userName = userName;
@@ -41,18 +44,20 @@
     }
 
     /**
-     * Answers the reference of the password of this class.
+     * Gets a clone of the password stored by this instance. The user is
+     * responsible to finalize the returned array if the password clone is no
+     * longer needed.
      * 
-     * @return char[] the reference of the password
+     * @return the copied password.
      */
     public char[] getPassword() {
         return password.clone();
     }
 
     /**
-     * Answers the username of this class.
+     * Gets the username stored by this instance.
      * 
-     * @return java.lang.String the username of this class
+     * @return the stored username.
      */
     public String getUserName() {
         return userName;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PortUnreachableException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PortUnreachableException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PortUnreachableException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PortUnreachableException.java Wed May  6 08:33:17 2009
@@ -17,6 +17,10 @@
 
 package java.net;
 
+/**
+ * This {@code PortUnreachableException} will be thrown if an {@code
+ * ICMP_Port_Unreachable} message has been received.
+ */
 public class PortUnreachableException extends SocketException {
 
     private static final long serialVersionUID = 8462541992376507323L;
@@ -32,7 +36,7 @@
      * filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public PortUnreachableException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProtocolException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProtocolException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProtocolException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProtocolException.java Wed May  6 08:33:17 2009
@@ -18,11 +18,9 @@
 package java.net;
 
 /**
- * An attempt to connect to a socket of the wrong type (stream or nonstream)
- * will trigger this exception. An invalid operation applied on the protocol
- * that doesn't support it will also throw this exception.
- * 
- * @see URL
+ * Signals that either a connection attempt to a socket of the wrong type, the
+ * application of an unsupported operation or that a general error in the
+ * underlying protocol has occurred.
  */
 public class ProtocolException extends java.io.IOException {
 
@@ -40,7 +38,7 @@
      * filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public ProtocolException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Proxy.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Proxy.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Proxy.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Proxy.java Wed May  6 08:33:17 2009
@@ -18,20 +18,20 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class is about proxy setting. A proxy contains <code>type</code>,
- * proxy host address information. There are three types of <code>Proxy</code>:
- * <li>Direct type proxy</li>
- * <li>HTTP type proxy</li>
- * <li>SOCKS type proxy</li>
- * 
- * A <code>Proxy</code> instance is immutable.
- * 
+ * This class represents proxy server settings. A created instance of {@code
+ * Proxy} stores a type and an address and is immutable. There are three types
+ * of proxies:
+ * <ul>
+ * <li>DIRECT</li>
+ * <li>HTTP</li>
+ * <li>SOCKS</li></ul
  */
 public class Proxy {
 
     /**
-     * Represents <code>Proxy.Type.DIRECT</code> type proxy setting. It tells
-     * protocol handlers not to use any proxy.
+     * Represents the proxy type setting {@code Proxy.Type.DIRECT}. It tells
+     * protocol handlers that there is no proxy to be used. The address is set
+     * to {@code null}.
      */
     public static final Proxy NO_PROXY = new Proxy();
 
@@ -40,19 +40,20 @@
     private SocketAddress address;
 
     /**
-     * New a <code>Proxy</code> instance. SocketAddress must NOT be null when
-     * <code>type</code> is either <code>Proxy.Type.HTTP</code> or
-     * <code>Proxy.Type.SOCKS</code>. For <code>Proxy.Type.DIRECT</code>
-     * type proxy, use <code>Proxy.NO_PROXY</code> directly instead of
-     * constructing it.
+     * Creates a new {@code Proxy} instance. {@code SocketAddress} must NOT be
+     * {@code null} when {@code type} is either {@code Proxy.Type.HTTP} or
+     * {@code Proxy.Type.SOCKS}. To create a {@code Proxy} instance representing
+     * the proxy type {@code Proxy.Type.DIRECT}, use {@code Proxy.NO_PROXY}
+     * instead of this constructor.
      * 
      * @param type
-     *            proxy type
+     *            the proxy type of this instance.
      * @param sa
-     *            proxy address
+     *            the proxy address of this instance.
      * @throws IllegalArgumentException
-     *             when <code>type</code> is <code>Proxy.Type.DIRECT</code>
-     *             or SocketAddress is null.
+     *             if the parameter {@code type} is set to {@code
+     *             Proxy.Type.DIRECT} or the value for {@code SocketAddress} is
+     *             {@code null}.
      */
     public Proxy(Proxy.Type type, SocketAddress sa) {
         /*
@@ -77,33 +78,30 @@
     }
 
     /**
-     * Gets the proxy type.
+     * Gets the type of this {@code Proxy} instance.
      * 
-     * @return the proxy type.
+     * @return the stored proxy type.
      */
     public Proxy.Type type() {
         return type;
     }
 
     /**
-     * Gets the proxy address.
+     * Gets the address of this {@code Proxy} instance.
      * 
-     * @return the proxy address for <code>HTTP</code> and <code>SOCKS</code>
-     *         type proxy. Returns null for <code>DIRECT</code> type proxy.
+     * @return the stored proxy address or {@code null} if the proxy type is
+     *         {@code DIRECT}.
      */
     public SocketAddress address() {
         return address;
     }
 
     /**
-     * <p>
-     * Representing string of the proxy. The string consists of
-     * <code>type.toString()</code> and <code>address.toString()</code> if
-     * <code>type</code> and <code>address</code> are not null.
-     * </p>
-     * 
-     * @see java.lang.Object#equals(java.lang.Object)
-     * @return representing string of the proxy.
+     * Gets a textual representation of this {@code Proxy} instance. The string
+     * includes the two parts {@code type.toString()} and {@code
+     * address.toString()} if {@code address} is not {@code null}.
+     *
+     * @return the representing string of this proxy.
      */
     @Override
     public String toString() {
@@ -115,16 +113,16 @@
     }
 
     /**
-     * <p>
-     * Compare <code>obj</code> with current proxy. Returns false if the
-     * <code>obj</code> is not a <code>Proxy</code> object. Returns true if
-     * and only if the <code>obj</code> has the same <code>address</code>
-     * and <code>type</code> value as current proxy.
-     * </p>
-     * 
-     * @see java.lang.Object#equals(java.lang.Object)
-     * @return true if <code>obj</code> represents the same proxy. Otherwise,
-     *         returns false.
+     * Compares the specified {@code obj} to this {@code Proxy} instance and
+     * returns whether they are equal or not. The given object must be an
+     * instance of {@code Proxy} with the same address and the same type value
+     * to be equal.
+     * 
+     * @param obj
+     *            the object to compare with this instance.
+     * @return {@code true} if the given object represents the same {@code
+     *         Proxy} as this instance, {@code false} otherwise.
+     * @see #hashCode
      */
     @Override
     public final boolean equals(Object obj) {
@@ -140,10 +138,9 @@
     }
 
     /**
-     * gets the hash code of <code>Proxy</code>.
+     * Gets the hashcode for this {@code Proxy} instance.
      * 
-     * @see java.lang.Object#hashCode()
-     * @return the hash code of <code>Proxy</code>.
+     * @return the hashcode value for this Proxy instance.
      */
     @Override
     public final int hashCode() {
@@ -156,8 +153,8 @@
     }
 
     /**
-     * The proxy type, includes <code>DIRECT</code>, <code>HTTP</code> and
-     * <code>SOCKS</code>.
+     * {@code Enum} class for the proxy type. Possible options are {@code
+     * DIRECT}, {@code HTTP} and {@code SOCKS}.
      */
     public enum Type {
         /**

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelector.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelector.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelector.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelector.java Wed May  6 08:33:17 2009
@@ -19,20 +19,11 @@
 import java.util.List;
 
 /**
- * <p>
- * Selects applicable proxies when connecting to network resouce represented by
- * a <code>URI</code>. An implementation of <code>ProxySelector</code>
- * should be a concrete subclass of <code>ProxySelector</code>. Method
- * <code>select</code> returns a list of proxies according to the
- * <code>uri</code>. If a connection can't be established, the caller should
- * notify proxy selector by invoking <code>connectFailed</code> method.
- * </p>
- * <p>
- * A proxy selector can be registered/unregistered by calling
- * <code>setDefault</code> method and retrieved by calling
- * <code>getDefault</code> method.
- * </p>
- * 
+ * Selects an applicable proxy server when connecting to a resource specified by
+ * a URL. Proxy selectors are concrete subclasses of {@code ProxySelector} and
+ * can be set as default by calling the {@code setDefault()} method. If a
+ * connection can't be established, the caller should notify the proxy selector
+ * by invoking the {@code connectFailed()} method.
  */
 public abstract class ProxySelector {
 
@@ -53,19 +44,19 @@
             "setProxySelector"); //$NON-NLS-1$
 
     /**
-     * Constructor method.
+     * Creates a new {@code ProxySelector} instance.
      */
     public ProxySelector() {
         super();
     }
 
     /**
-     * Gets system default <code>ProxySelector</code>.
+     * Gets the default {@code ProxySelector} of the system.
      * 
-     * @return system default <code>ProxySelector</code>.
-     * @throws SecurtiyException
-     *             If a security manager is installed and it doesn't have
-     *             <code>NetPermission("getProxySelector")</code>.
+     * @return the currently set default {@code ProxySelector}.
+     * @throws SecurityException
+     *             if a security manager is installed but it doesn't have the
+     *             NetPermission("getProxySelector").
      */
     public static ProxySelector getDefault() {
         SecurityManager sm = System.getSecurityManager();
@@ -76,12 +67,17 @@
     }
 
     /**
-     * Sets system default <code>ProxySelector</code>. Unsets system default
-     * <code>ProxySelector</code> if <code>selector</code> is null.
+     * Sets the default {@code ProxySelector} of the system. Removes the system
+     * default {@code ProxySelector} if the parameter {@code selector} is set to
+     * {@code null}.
      * 
-     * @throws SecurtiyException
-     *             If a security manager is installed and it doesn't have
-     *             <code>NetPermission("setProxySelector")</code>.
+     * @param selector
+     *            the {@code ProxySelector} instance to set as default or
+     *            {@code null} to remove the current default {@code
+     *            ProxySelector}.
+     * @throws SecurityException
+     *             if a security manager is installed but it doesn't have the
+     *             NetPermission("setProxySelector").
      */
     public static void setDefault(ProxySelector selector) {
         SecurityManager sm = System.getSecurityManager();
@@ -92,38 +88,40 @@
     }
 
     /**
-     * Gets applicable proxies based on the accessing protocol of
-     * <code>uri</code>. The format of URI is defined as below:
+     * Gets all applicable proxies based on the accessing protocol of {@code
+     * uri}. The format of URI is defined as below:
+     * <p>
      * <li>http URI stands for http connection.</li>
      * <li>https URI stands for https connection.</li>
      * <li>ftp URI stands for ftp connection.</li>
      * <li>socket:://ip:port URI stands for tcp client sockets connection.</li>
-     * 
+     *
      * @param uri
-     *            the destination <code>URI</code> object.
-     * @return a list contains all applicable proxies. If no proxy is available,
-     *         returns a list only contains one element
-     *         <code>Proxy.NO_PROXY</code>.
+     *            the target URI object.
+     * @return a list containing all applicable proxies. If no proxy is
+     *         available, the list contains only the {@code Proxy.NO_PROXY}
+     *         element.
      * @throws IllegalArgumentException
-     *             If any argument is null.
+     *             if {@code uri} is {@code null}.
      */
     public abstract List<Proxy> select(URI uri);
 
     /**
-     * If the connection can not be established to the proxy server, this method
-     * will be called. An implementation may adjust proxy the sequence of
-     * proxies returned by <code>select(String, String)</code>.
+     * Notifies the {@code ProxySelector} that a connection to the proxy server
+     * could not be established. A concrete implementation should upon this
+     * notification maintain the list of available proxies, since an updated
+     * version should be provided by {@code select()}.
      * 
      * @param uri
-     *            the <code>URI</code> that the connection fails to connect
-     *            to.
+     *            the URI to which the connection could not be established.
      * @param sa
-     *            <code>SocketAddress</code> of the proxy.
+     *            the address of the proxy.
      * @param ioe
-     *            The <code>IOException</code> which is thrown during
-     *            connection establishment.
+     *            the exception which was thrown during connection
+     *            establishment.
      * @throws IllegalArgumentException
-     *             If any argument is null.
+     *             if any argument is {@code null}.
+     * @see #select(URI)
      */
     public abstract void connectFailed(URI uri, SocketAddress sa,
             IOException ioe);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelectorImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelectorImpl.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelectorImpl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelectorImpl.java Wed May  6 08:33:17 2009
@@ -29,7 +29,7 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * Default implementation for ProxySelector
+ * Default implementation for {@code ProxySelector}.
  */
 @SuppressWarnings("unchecked")
 class ProxySelectorImpl extends ProxySelector {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ResponseCache.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ResponseCache.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ResponseCache.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ResponseCache.java Wed May  6 08:33:17 2009
@@ -20,15 +20,28 @@
 import java.util.Map;
 
 /**
- * ResponseCache implements URLConnection caches. System default cache can be
- * registered by invoking ResponseCache.<code>setDefault</code>(ResponseCache),
- * and can be retrieved by invoking ResponseCache.<code>getDefault</code>.
- * If URLConnection#useCaches is set, <code>URLConnection</code> class will
- * use <code>ResponseCache</code> to store and get resources. Whether the
- * resource is cached depends on <code>ResponseCache</code> implementation. If
- * a request resource is cached, protocol handler will fecth it from the cache.
- * If the protocol handler fails to get resource from the cache, it turns to get
- * the resource from its original location.
+ * This class is an implementation of {@code URLConnection} caches intended
+ * primarily for the according stream handler implementations.
+ * <p>
+ * The system's default cache can be registered by invoking the method {@code
+ * setDefault(ResponseCache)} and be retrieved by invoking the method {@code
+ * getDefault()}. If {@code URLConnection#useCaches} is set, {@code
+ * URLConnection} class will use {@code ResponseCache} to store and get
+ * resources.
+ * <p>
+ * Whether the resource is cached depends on the implementation of {@code
+ * ResponseCache}. If so, a {@code CacheResponse} is returned from which the
+ * stream handler reads. If the stream handler fails to get a resource from the
+ * cache, it must get the resource from its original location.
+ * <p>
+ * To write to the cache, the protocol handlers call {@code put()}, upon which a
+ * {@code CacheRequest} is supplied to which the resources are written.
+ *
+ * @see #put(URI, URLConnection)
+ * @see CacheRequest
+ * @see CacheResponse
+ * @see URLConnection
+ * @see URLStreamHandler
  */
 public abstract class ResponseCache {
 
@@ -74,19 +87,19 @@
     }
 
     /**
-     * Constructor method.
+     * Creates a new instance of this class.
      */
     public ResponseCache() {
         super();
     }
 
     /**
-     * Gets system default response cache.
+     * Gets the default response cache of the system.
      * 
-     * @return default <code>ResponseCache</code>.
+     * @return the default {@code ResponseCache}.
      * @throws SecurityException
-     *             If a security manager is installed and it doesn't have
-     *             <code>NetPermission</code>("getResponseCache").
+     *             if a security manager is installed but it doesn't have the
+     *             {@code NetPermission("getResponseCache")}.
      */
     public static ResponseCache getDefault() {
         checkGetResponseCachePermission();
@@ -94,16 +107,18 @@
     }
 
     /**
-     * Sets the system default response cache when responseCache is not null.
-     * Otherwise, the method unsets the system default response cache. This
-     * setting may be ignored by some non-standard protocols.
+     * Sets the default response cache of the system. Removes the system's
+     * default {@code ResponseCache} if the parameter {@code responseCache} is
+     * set to {@code null}. This setting may be ignored by some non-standard
+     * protocols.
      * 
      * @param responseCache
-     *            Set default <code>ResponseCache</code>. If responseCache is
-     *            null, it unsets the cache.
+     *            the {@code ResponseCache} instance to set as default or
+     *            {@code null} to remove the current default {@code
+     *            ResponseCache}.
      * @throws SecurityException
-     *             If a security manager is installed and it doesn't have
-     *             <code>NetPermission</code>("setResponseCache").
+     *             if a security manager is installed but it doesn't have the
+     *             {@code NetPermission("setResponseCache")}.
      */
     public static void setDefault(ResponseCache responseCache) {
         checkSetResponseCachePermission();
@@ -111,43 +126,42 @@
     }
 
     /**
-     * Gets the cached response according to requesting uri,method and headers.
+     * Gets the cached response according to the requesting URI, method and
+     * headers.
      * 
      * @param uri
-     *            A <code>URL</code> represents requesting uri.
+     *            the requesting URI.
      * @param rqstMethod
-     *            A <code>String</code> represents requesting method.
+     *            the requesting method.
      * @param rqstHeaders
-     *            A <code>Map</code> from request header field names to lists
-     *            of field values represents requesting headers.
-     * @return A <code>CacheResponse</code> object if the request is available
-     *         in the cache. Otherwise, this method returns null.
+     *            a map of requesting headers.
+     * @return the {@code CacheResponse} object if the request is available in the cache
+     *         or {@code null} otherwise.
      * @throws IOException
-     *             If an I/O error is encountered.
+     *             if an I/O error occurs while getting the cached data.
      * @throws IllegalArgumentException
-     *             If any one of the parameters is null
+     *             if any one of the parameters is set to {@code null}.
      */
     public abstract CacheResponse get(URI uri, String rqstMethod,
             Map<String, List<String>> rqstHeaders) throws IOException;
 
     /**
-     * Protocol handler calls this method after retrieving resources. The
-     * <code>ResponseCache</code> decides whether the resource should be
-     * cached. If the resource needs to be cached, this method will return a
-     * <code>CacheRequest</code> with a <code>WriteableByteChannel</code>,
-     * and then, protocol handler will use this channel to write the resource
-     * data into the cache. Otherwise, if the resource doesn't need to be
-     * cached, it returns null.
+     * Allows the protocol handler to cache data after retrieving resources. The
+     * {@code ResponseCache} decides whether the resource data should be cached
+     * or not. If so, this method returns a {@code CacheRequest} with a {@code
+     * WriteableByteChannel} to put the resource data down. Otherwise, this
+     * method returns {@code null}.
      * 
      * @param uri
+     *            the reference to the requested resource.
      * @param conn
-     * @return a <code>CacheRequest</code> which contains
-     *         <code>WriteableByteChannel</code> if the resource is cached.
-     *         Otherwise, it returns null.
+     *            the connection to fetch the response.
+     * @return a CacheRequest object with a WriteableByteChannel if the resource
+     *         has to be cached, {@code null} otherwise.
      * @throws IOException
-     *             If an I/O error is encountered.
+     *             if an I/O error occurs while adding the resource.
      * @throws IllegalArgumentException
-     *             If any one of the parameters is null.
+     *             if any one of the parameters is set to {@code null}.
      */
     public abstract CacheRequest put(URI uri, URLConnection conn)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SecureCacheResponse.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SecureCacheResponse.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SecureCacheResponse.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SecureCacheResponse.java Wed May  6 08:33:17 2009
@@ -22,11 +22,16 @@
 import javax.net.ssl.SSLPeerUnverifiedException;
 
 /**
- * A secure cache response, which is originally retrieved through secure ways.
+ * A secure cache response represents data which is originally retrieved over a
+ * secure connection. Such a connection can be secured by using a cryptographic
+ * protocol like TLS or SSL.
+ * 
+ * @see ResponseCache
  */
 public abstract class SecureCacheResponse extends CacheResponse {
+
     /**
-     * Constructor method
+     * Creates a new instance of this class.
      */
     public SecureCacheResponse() {
         super();
@@ -36,60 +41,55 @@
      * Gets the cipher suite string on the connection which is originally used
      * to retrieve the network resource.
      * 
-     * @return the cipher suite string
+     * @return the cipher suite string.
      */
     public abstract String getCipherSuite();
 
     /**
-     * Gets local certificate chain. When the original connection retrieved the
-     * resource data, certificate chain was sent to the server during
+     * Gets the local certificate chain. When the original connection retrieved
+     * the resource data, this certificate chain was sent to the server during
      * handshaking process. This method only takes effect when certificate-based
      * cipher suite is enabled.
      * 
-     * @return the certificate chain that was sent to the server. The
-     *         certificate chain is represented as a <code>List</code> of
-     *         <code>Certificate</code>. If no certificate chain was sent,
-     *         the method returns null.
+     * @return the certificate chain that was sent to the server. If no
+     *         certificate chain was sent, the method returns {@code null}.
      */
     public abstract List<Certificate> getLocalCertificateChain();
 
     /**
-     * Gets server's certificate chain from cache. As part of defining the
+     * Gets the cached server's certificate chain. As part of defining the
      * session, the certificate chain was established when the original
      * connection retrieved network resource. This method can only be invoked
-     * when certificated-based cypher suites is enable. Otherwise, it throws an
-     * <code>SSLPeerUnverifiedException</code>.
+     * when certificated-based cipher suite is enabled. Otherwise, it throws an
+     * {@code SSLPeerUnverifiedException}.
      * 
-     * @return The server's certificate chain, which is represented as a
-     *         <code>List</code> of <code>Certificate</code>.
+     * @return the server's certificate chain.
      * @throws SSLPeerUnverifiedException
-     *             If the peer is unverified.
+     *             if the peer is unverified.
      */
     public abstract List<Certificate> getServerCertificateChain()
             throws SSLPeerUnverifiedException;
 
     /**
-     * Gets the server's <code>Principle</code>. When the original connection
-     * retrieved network resource, the principle was established when defining
-     * the session.
+     * Gets the server's principle. When the original connection retrieved
+     * network resource, the principle was established when defining the
+     * session.
      * 
-     * @return an <code>Principal</code> represents the server's principal.
+     * @return a principal object representing the server's principal.
      * @throws SSLPeerUnverifiedException
-     *             If the peer is unverified.
+     *             if the peer is unverified.
      */
     public abstract Principal getPeerPrincipal()
             throws SSLPeerUnverifiedException;
 
     /**
-     * Gets the <code>Principle</code> that the original connection sent to
-     * the server. When the original connection fetched the network resource,
-     * the <code>Principle</code> was sent to the server during handshaking
-     * process.
-     * 
-     * 
-     * @return the <code>principal</code> sent to the server. Returns an
-     *         <code>X500Principal</code> for X509-based cipher suites. If no
-     *         principal was sent, it returns null.
+     * Gets the local principle that the original connection sent to the server.
+     * When the original connection fetched the network resource, the principle
+     * was sent to the server during handshaking process.
+     * 
+     * @return the local principal object being sent to the server. Returns an
+     *         {@code X500Principal} object for X509-based cipher suites. If no
+     *         principal was sent, it returns {@code null}.
      */
     public abstract Principal getLocalPrincipal();
 }



Mime
View raw message