Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 86742 invoked from network); 6 May 2009 08:33:58 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 6 May 2009 08:33:58 -0000 Received: (qmail 17304 invoked by uid 500); 6 May 2009 08:33:58 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 17241 invoked by uid 500); 6 May 2009 08:33:58 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 17232 invoked by uid 99); 6 May 2009 08:33:58 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 May 2009 08:33:58 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 May 2009 08:33:45 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id E96882388B9A; Wed, 6 May 2009 08:33:24 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit 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 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090506083324.E96882388B9A@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 InetSocketAddress 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 InetSocketAddress 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:
jar:!/{entry}
- * 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: jar:{archive-url}!/{entry} where "!/" is called a + * separator. This separator is important to determine if an archive or an entry + * of an archive is referred. + *

+ * Examples: + *

  • Archive: {@code jar:http://www.example.com/applets/archive.jar!/}
    • + *
  • File Entry: {@code + * jar:http://www.example.com/applets/archive.jar!/test.class}
    • + *
  • Directory Entry: {@code + * jar:http://www.example.com/applets/archive.jar!/applets/}
    • */ 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 JarURLConnection. + * 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 - * JarURLConnection. + * 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 - * URLConnection. 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 - * URLConnection. + * 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 - * URLConnection. - * - * @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 URLConnection. + * 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 - * URLConnection. + * 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 - * URLConnection. - * - * @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, 0true if the IP_MULTICAST_LOOP is enabled, - * false 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 extends LinkedHashMap { @@ -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 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. *

    * There are three valid target names: *

    @@ -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 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 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 type, - * proxy host address information. There are three types of Proxy: - *
  • Direct type proxy
    • - *
  • HTTP type proxy
    • - *
  • SOCKS type proxy
    • - * - * A Proxy 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: + *
      + *
    • DIRECT
      • + *
    • HTTP
      • + *
    • SOCKS
    Proxy.Type.DIRECT 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 Proxy instance. SocketAddress must NOT be null when - * type is either Proxy.Type.HTTP or - * Proxy.Type.SOCKS. For Proxy.Type.DIRECT - * type proxy, use Proxy.NO_PROXY 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 type is Proxy.Type.DIRECT - * 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 HTTP and SOCKS - * type proxy. Returns null for DIRECT type proxy. + * @return the stored proxy address or {@code null} if the proxy type is + * {@code DIRECT}. */ public SocketAddress address() { return address; } /** - *

    - * Representing string of the proxy. The string consists of - * type.toString() and address.toString() if - * type and address are not null. - *

    - * - * @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 @@ } /** - *

    - * Compare obj with current proxy. Returns false if the - * obj is not a Proxy object. Returns true if - * and only if the obj has the same address - * and type value as current proxy. - *

    - * - * @see java.lang.Object#equals(java.lang.Object) - * @return true if obj 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 Proxy. + * Gets the hashcode for this {@code Proxy} instance. * - * @see java.lang.Object#hashCode() - * @return the hash code of Proxy. + * @return the hashcode value for this Proxy instance. */ @Override public final int hashCode() { @@ -156,8 +153,8 @@ } /** - * The proxy type, includes DIRECT, HTTP and - * SOCKS. + * {@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; /** - *

    - * Selects applicable proxies when connecting to network resouce represented by - * a URI. An implementation of ProxySelector - * should be a concrete subclass of ProxySelector. Method - * select returns a list of proxies according to the - * uri. If a connection can't be established, the caller should - * notify proxy selector by invoking connectFailed method. - *

    - *

    - * A proxy selector can be registered/unregistered by calling - * setDefault method and retrieved by calling - * getDefault method. - *

    - * + * 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 ProxySelector. + * Gets the default {@code ProxySelector} of the system. * - * @return system default ProxySelector. - * @throws SecurtiyException - * If a security manager is installed and it doesn't have - * NetPermission("getProxySelector"). + * @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 ProxySelector. Unsets system default - * ProxySelector if selector 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 - * NetPermission("setProxySelector"). + * @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 - * uri. 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: + *

    *

  • http URI stands for http connection.
    • *
  • https URI stands for https connection.
    • *
  • ftp URI stands for ftp connection.
    • *
  • socket:://ip:port URI stands for tcp client sockets connection.
    • - * + * * @param uri - * the destination URI object. - * @return a list contains all applicable proxies. If no proxy is available, - * returns a list only contains one element - * Proxy.NO_PROXY. + * 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 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 select(String, String). + * 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 URI that the connection fails to connect - * to. + * the URI to which the connection could not be established. * @param sa - * SocketAddress of the proxy. + * the address of the proxy. * @param ioe - * The IOException 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.setDefault(ResponseCache), - * and can be retrieved by invoking ResponseCache.getDefault. - * If URLConnection#useCaches is set, URLConnection class will - * use ResponseCache to store and get resources. Whether the - * resource is cached depends on ResponseCache 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. + *

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

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

    + * 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 ResponseCache. + * @return the default {@code ResponseCache}. * @throws SecurityException - * If a security manager is installed and it doesn't have - * NetPermission("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 ResponseCache. 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 - * NetPermission("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 URL represents requesting uri. + * the requesting URI. * @param rqstMethod - * A String represents requesting method. + * the requesting method. * @param rqstHeaders - * A Map from request header field names to lists - * of field values represents requesting headers. - * @return A CacheResponse 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> rqstHeaders) throws IOException; /** - * Protocol handler calls this method after retrieving resources. The - * ResponseCache decides whether the resource should be - * cached. If the resource needs to be cached, this method will return a - * CacheRequest with a WriteableByteChannel, - * 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 CacheRequest which contains - * WriteableByteChannel 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 List of - * Certificate. 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 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 - * SSLPeerUnverifiedException. + * when certificated-based cipher suite is enabled. Otherwise, it throws an + * {@code SSLPeerUnverifiedException}. * - * @return The server's certificate chain, which is represented as a - * List of Certificate. + * @return the server's certificate chain. * @throws SSLPeerUnverifiedException - * If the peer is unverified. + * if the peer is unverified. */ public abstract List getServerCertificateChain() throws SSLPeerUnverifiedException; /** - * Gets the server's Principle. 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 Principal 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 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 principal sent to the server. Returns an - * X500Principal 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(); }