harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [1/6] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Date Wed, 06 May 2009 08:33:22 GMT
Author: tellison
Date: Wed May  6 08:33:17 2009
New Revision: 772095

URL: http://svn.apache.org/viewvc?rev=772095&view=rev
Log:
Apply patch for HARMONY-6196 (Javadocs for java.net.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Authenticator.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/BindException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheRequest.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheResponse.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ConnectException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandler.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandlerFactory.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CookieHandler.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramPacket.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocket.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetSocketAddress.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/JarURLConnection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MalformedURLException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/MulticastSocket.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegCacheElement.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NegativeCache.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetPermission.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NetworkInterface.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/NoRouteToHostException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PasswordAuthentication.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/PortUnreachableException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProtocolException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Proxy.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelector.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ProxySelectorImpl.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ResponseCache.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SecureCacheResponse.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ServerSocket.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Socket.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketAddress.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImpl.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketImplFactory.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketOptions.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermission.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermissionCollection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketTimeoutException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URI.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URIEncoderDecoder.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URISyntaxException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URL.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLClassLoader.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLConnection.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLDecoder.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLEncoder.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandler.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandlerFactory.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownHostException.java
    harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownServiceException.java

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Authenticator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Authenticator.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Authenticator.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Authenticator.java Wed May  6 08:33:17 2009
@@ -18,16 +18,15 @@
 package java.net;
 
 /**
- * This class is able to obtain authentication info for a connection, usually
- * from user. First the application has to set the default authenticator which
- * extends <code>Authenticator</code> by
- * <code>setDefault(Authenticator a)</code>.
- * <p>
- * It should override <code>getPasswordAuthentication()</code> which dictates
- * how the authentication info should be obtained.
+ * An implementation of this class is able to obtain authentication information
+ * for a connection in several ways. For this purpose it has to set the default
+ * authenticator which extends {@code Authenticator} by {@code
+ * setDefault(Authenticator a)}. Then it should override {@code
+ * getPasswordAuthentication()} which dictates how the authentication info is
+ * obtained. Usually, it prompts the user for the required input.
  * 
- * @see Authenticator#setDefault(Authenticator)
- * @see Authenticator#getPasswordAuthentication()
+ * @see #setDefault
+ * @see #getPasswordAuthentication
  */
 public abstract class Authenticator {
 
@@ -58,62 +57,61 @@
     private RequestorType rt;
 
     /**
-     * This method is responsible for retrieving the username and password for
-     * the sender. The implementation varies. The subclass has to overwrite
-     * this.
+     * Returns the collected username and password for authorization. The
+     * subclass has to override this method to return a value different to the
+     * default which is {@code null}.
      * <p>
-     * It answers null by default.
-     * 
-     * @return java.net.PasswordAuthentication The password authentication that
-     *         it obtains
+     * Returns {@code null} by default.
+     *
+     * @return collected password authentication data.
      */
     protected PasswordAuthentication getPasswordAuthentication() {
         return null;
     }
 
     /**
-     * Answers the port of the connection that requests authorization.
+     * Returns the port of the connection that requests authorization.
      * 
-     * @return int the port of the connection
+     * @return port of the connection.
      */
     protected final int getRequestingPort() {
         return this.port;
     }
 
     /**
-     * Answers the address of the connection that requests authorization or null
-     * if unknown.
+     * Returns the address of the connection that requests authorization or
+     * {@code null} if unknown.
      * 
-     * @return InetAddress the address of the connection
+     * @return address of the connection.
      */
     protected final InetAddress getRequestingSite() {
         return this.addr;
     }
 
     /**
-     * Answers the realm (prompt string) of the connection that requires
+     * Returns the realm (prompt string) of the connection that requests
      * authorization.
      * 
-     * @return java.lang.String the prompt string of the connection
+     * @return prompt string of the connection.
      */
     protected final String getRequestingPrompt() {
         return this.prompt;
     }
 
     /**
-     * Answers the protocol of the connection that requests authorization.
+     * Returns the protocol of the connection that requests authorization.
      * 
-     * @return java.lang.String the protocol of connection
+     * @return protocol of the connection.
      */
     protected final String getRequestingProtocol() {
         return this.protocol;
     }
 
     /**
-     * Answers the scheme of the connection that requires authorization. Eg.
-     * Basic
+     * Returns the scheme of the connection that requests authorization, for
+     * example HTTP Basic Authentication.
      * 
-     * @return java.lang.String the scheme of the connection
+     * @return scheme of the connection.
      */
     protected final String getRequestingScheme() {
         return this.scheme;
@@ -124,24 +122,21 @@
      * security exception, this method invokes the methods of the registered
      * authenticator to get the authentication info.
      * 
-     * @return java.net.PasswordAuthentication the authentication info
-     * 
+     * @return password authentication info or {@code null} if no authenticator
+     *         exists.
      * @param rAddr
-     *            java.net.InetAddress the address of the connection that
-     *            requests authentication
+     *            address of the connection that requests authentication.
      * @param rPort
-     *            int the port of the connection that requests authentication
+     *            port of the connection that requests authentication.
      * @param rProtocol
-     *            java.lang.String the protocol of the connection that requests
-     *            authentication
+     *            protocol of the connection that requests authentication.
      * @param rPrompt
-     *            java.lang.String the realm of the connection that requests
-     *            authentication
+     *            realm of the connection that requests authentication.
      * @param rScheme
-     *            java.lang.String the scheme of the connection that requests
-     *            authentication
+     *            scheme of the connection that requests authentication.
      * @throws SecurityException
-     *             if requestPasswordAuthenticationPermission is denied
+     *             if a security manager denies the password authentication
+     *             permission.
      */
     public static synchronized PasswordAuthentication requestPasswordAuthentication(
             InetAddress rAddr, int rPort, String rProtocol, String rPrompt,
@@ -168,15 +163,16 @@
     }
 
     /**
-     * This method sets <code>a</code> to be the default authenticator. It
-     * will be called whenever the realm that the URL is pointing to requires
-     * authorization. If there is a security manager set then the caller must
-     * have the NetPermission "setDefaultAuthenticator".
+     * Sets {@code a} as the default authenticator. It will be called whenever
+     * the realm that the URL is pointing to requires authorization. If there is
+     * a security manager set then the caller must have the appropriate {@code
+     * NetPermission}.
      * 
      * @param a
-     *            java.net.Authenticator The authenticator to be set.
+     *            authenticator which has to be set as default.
      * @throws SecurityException
-     *             if requestPasswordAuthenticationPermission is denied
+     *             if a security manager denies the password authentication
+     *             permission.
      */
     public static void setDefault(Authenticator a) {
         SecurityManager sm = System.getSecurityManager();
@@ -191,27 +187,23 @@
      * security exception, this method invokes the methods of the registered
      * authenticator to get the authentication info.
      * 
-     * @return java.net.PasswordAuthentication the authentication info
-     * 
+     * @return password authentication info or {@code null} if no authenticator
+     *         exists.
      * @param rHost
-     *            java.lang.String the host name of the connection that requests
-     *            authentication
+     *            host name of the connection that requests authentication.
      * @param rAddr
-     *            java.net.InetAddress the address of the connection that
-     *            requests authentication
+     *            address of the connection that requests authentication.
      * @param rPort
-     *            int the port of the connection that requests authentication
+     *            port of the connection that requests authentication.
      * @param rProtocol
-     *            java.lang.String the protocol of the connection that requests
-     *            authentication
+     *            protocol of the connection that requests authentication.
      * @param rPrompt
-     *            java.lang.String the realm of the connection that requests
-     *            authentication
+     *            realm of the connection that requests authentication.
      * @param rScheme
-     *            java.lang.String the scheme of the connection that requests
-     *            authentication
+     *            scheme of the connection that requests authentication.
      * @throws SecurityException
-     *             if requestPasswordAuthenticationPermission is denied
+     *             if a security manager denies the password authentication
+     *             permission.
      */
     public static synchronized PasswordAuthentication requestPasswordAuthentication(
             String rHost, InetAddress rAddr, int rPort, String rProtocol,
@@ -239,8 +231,10 @@
     }
 
     /**
-     * Return the host name of the connection that requests authentication, or
-     * null if unknown.
+     * Returns the host name of the connection that requests authentication or
+     * {@code null} if unknown.
+     *
+     * @return name of the requesting host or {@code null}.
      */
     protected final String getRequestingHost() {
         return host;
@@ -251,33 +245,27 @@
      * security exception, this method invokes the methods of the registered
      * authenticator to get the authentication info.
      * 
-     * @return java.net.PasswordAuthentication the authentication info
-     * 
+     * @return password authentication info or {@code null} if no authenticator
+     *         exists.
      * @param rHost
-     *            java.lang.String the host name of the connection that requests
-     *            authentication
+     *            host name of the connection that requests authentication.
      * @param rAddr
-     *            java.net.InetAddress the address of the connection that
-     *            requests authentication
+     *            address of the connection that requests authentication.
      * @param rPort
-     *            int the port of the connection that requests authentication
+     *            port of the connection that requests authentication.
      * @param rProtocol
-     *            java.lang.String the protocol of the connection that requests
-     *            authentication
+     *            protocol of the connection that requests authentication.
      * @param rPrompt
-     *            java.lang.String the realm of the connection that requests
-     *            authentication
+     *            realm of the connection that requests authentication.
      * @param rScheme
-     *            java.lang.String the scheme of the connection that requests
-     *            authentication
+     *            scheme of the connection that requests authentication.
      * @param rURL
-     *            java.net.URL the url of the connection that requests
-     *            authentication
+     *            url of the connection that requests authentication.
      * @param reqType
-     *            java.net.Authenticator.RequestorType the RequestorType of the
-     *            connection that requests authentication
+     *            requestor type of the connection that requests authentication.
      * @throws SecurityException
-     *             if requestPasswordAuthenticationPermission is denied
+     *             if a security manager denies the password authentication
+     *             permission.
      */
     public static PasswordAuthentication requestPasswordAuthentication(
             String rHost, InetAddress rAddr, int rPort, String rProtocol,
@@ -308,35 +296,35 @@
     }
 
     /**
-     * returns the URL of the authentication resulted in this request.
+     * Returns the URL of the authentication request.
      * 
-     * @return the url of request
+     * @return authentication request url.
      */
     protected URL getRequestingURL() {
         return url;
     }
 
     /**
-     * returns the type of this request, it can be proxy or server
+     * Returns the type of this request, it can be {@code PROXY} or {@code SERVER}.
      * 
-     * @return RequestorType of request
+     * @return RequestorType of the authentication request.
      */
     protected Authenticator.RequestorType getRequestorType() {
         return rt;
     }
 
     /**
-     * an enum class of requestor type
+     * Enumeration class for the origin of the authentication request.
      */
     public enum RequestorType {
 
         /**
-         * type of proxy server
+         * Type of proxy server
          */
         PROXY,
 
         /**
-         * type of origin server
+         * Type of origin server
          */
         SERVER
     }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/BindException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/BindException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/BindException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/BindException.java Wed May  6 08:33:17 2009
@@ -18,26 +18,25 @@
 package java.net;
 
 /**
- * A BindException is thrown when a process cannot bind a local address/port,
- * either because it is already bound or reserved by the OS.
+ * A {@code BindException} is thrown when a process cannot bind a local
+ * address/port, either because it is already bound or reserved by the OS.
  */
 public class BindException extends SocketException {
 
     private static final long serialVersionUID = -5945005768251722951L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new instance with its walkback filled in.
      */
     public BindException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new instance with its walkback and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            detail message of the exception.
      */
     public BindException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheRequest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheRequest.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheRequest.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheRequest.java Wed May  6 08:33:17 2009
@@ -20,38 +20,36 @@
 import java.io.OutputStream;
 
 /**
- * CacheRequest provides channels for storing resource data in the
- * <code>ResponseCache</code>. Protocol handler calls the
- * <code>OutputStream</code> which is supplied by CachedRequest object, to
- * store the resource data into the cache. It also allows the user to interrupt
- * and abort the current store operation by calling method <code>abort</code>.
- * If IOException occurs while reading the response or writing data to the
- * cache, the current cache store operation will be abandoned.
+ * {@code CacheRequest} is a kind of channel for storing resource data in the
+ * {@code ResponseCache}. A protocol handler calls the {@code OutputStream}
+ * which is provided by the {@code CacheRequest} object, to store the resource
+ * data into the cache. It also allows the user to interrupt and abort the
+ * current store operation by calling the method {@code abort}. If an {@code
+ * IOException} occurs while reading the response or writing data to the cache,
+ * the current cache store operation is abandoned.
+ * 
+ * @see ResponseCache
  */
 public abstract class CacheRequest {
 
     /**
-     * Constructor method.
+     * This implementation does nothing.
      */
     public CacheRequest() {
         super();
     }
 
     /**
-     * Aborts the current cache operation. If an IOException occurs while
-     * reading the response or writing resource data to the cache, the current
-     * cache store operation will be aborted.
+     * Aborts the current cache operation. If an {@code IOException} occurs
+     * while reading the response or writing resource data to the cache, the
+     * current cache store operation is aborted.
      */
     public abstract void abort();
 
     /**
-     * <p>
-     * Returns an <code>OutputStream</code>, which is used to write the
-     * response body.
-     * </p>
+     * Returns an {@code OutputStream} which is used to write the response body.
      * 
-     * @return an <code>OutputStream</code> which is used to write the
-     *         response body.
+     * @return an {@code OutputStream} which is used to write the response body.
      * @throws IOException
      *             if an I/O error is encountered during writing response body
      *             operation.

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheResponse.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheResponse.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheResponse.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CacheResponse.java Wed May  6 08:33:17 2009
@@ -22,42 +22,41 @@
 import java.util.Map;
 
 /**
- * CacheResponse is used for getting resource from the ResponseCache. An
- * CacheResponse object provides an <code>InputStream</code> to access the
- * response body, and also a method <code>getHeaders()</code> to fetch the
- * response headers.
+ * {@code CacheResponse} is used for getting resource data from the installed
+ * {@code ResponseCache}. A {@code CacheResponse} object provides an {@code
+ * InputStream} to access the response body and also a method {@code
+ * getHeaders()} to fetch the response headers.
+ * 
+ * @see ResponseCache
  */
 public abstract class CacheResponse {
     /**
-     * Constructor method
+     * This implementation does nothing.
      */
     public CacheResponse() {
         super();
     }
 
     /**
-     * Returns an <code>InputStream</code> for the respsonse body access.
+     * Returns an {@code InputStream} to access the response body.
      * 
-     * @return an <code>InputStream</code>, which can be used to fetch the
-     *         response body.
+     * @return an {@code InputStream} which can be used to fetch the response
+     *         body.
      * @throws IOException
-     *             if an I/O error is encounted while retrieving the response
+     *             if an I/O error is encountered while retrieving the response
      *             body.
      */
     public abstract InputStream getBody() throws IOException;
 
     /**
-     * Returns an immutable <code>Map</code>, which contains the response
-     * headers information.
+     * Returns an immutable {@code Map} which contains the response headers
+     * information.
      * 
-     * @return an immutable <code>Map</code>, which contains the response
-     *         headers. The map is from response header field names to lists of
-     *         field values. Field name is a <code>String</code>, and the
-     *         field values list is a <code>List</code> of <code>String</code>.The
-     *         status line as its field name has null as its list of field
-     *         values.
+     * @return an immutable {@code Map} which contains the response headers. The
+     *         generic map contains response header fields as the key and a list
+     *         of strings as values.
      * @throws IOException
-     *             if an I/O error is encounted while retrieving the response
+     *             if an I/O error is encountered while retrieving the response
      *             headers.
      */
     public abstract Map<String, List<String>> getHeaders() throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ConnectException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ConnectException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ConnectException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ConnectException.java Wed May  6 08:33:17 2009
@@ -18,26 +18,25 @@
 package java.net;
 
 /**
- * This ConnectException is thrown when a connection cannot be established to a
- * remote host/port, because for instance a server was not listening.
+ * A {@code ConnectException} is thrown if a connection cannot be established to
+ * a remote host on a specific port.
  */
 public class ConnectException extends SocketException {
 
     private static final long serialVersionUID = 3831404271622369215L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * This implementation does nothing.
      */
     public ConnectException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * This implementation does nothing.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            detail message of the exception.
      */
     public ConnectException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandler.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandler.java Wed May  6 08:33:17 2009
@@ -20,43 +20,37 @@
 import java.io.IOException;
 
 /**
- * This class converts the content of a certain format into a Java type Object.
- * It is implemented differently for each content type in each platform. It is
- * created by <code>ContentHandlerFactory</code>
+ * This class converts the content of a certain format (i.e. a MIME type) into a
+ * Java type object. It is created by {@code ContentHandlerFactory}. The data
+ * values should be accessed via {@code URL} or {@code URLConnection}.
  * 
  * @see ContentHandlerFactory
- * @see URL
+ * @see URL#getContent()
  * @see URLConnection#getContent()
  */
 public abstract class ContentHandler {
     /**
-     * Answers the object pointed by the specified URL Connection
-     * <code>uConn</code>.
+     * Returns the object pointed by the specified URL connection {@code uConn}.
      * 
-     * @return java.lang.Object the object referred by <code>uConn</code>
      * @param uConn
-     *            URLConnection the URL connection that points to the desired
-     *            object
+     *            URL connection that points to the desired object.
+     * @return object referred by {@code uConn}.
      * @throws IOException
-     *             thrown if an IO error occurs during the retrieval of the
-     *             object
+     *             if an IO error occurs during the retrieval of the object
      */
     public abstract Object getContent(URLConnection uConn) throws IOException;
 
     /**
-     * Answers the object pointed by the specified URL Connection
-     * <code>uConn</code>.
+     * Returns the object pointed by the specified URL connection {@code uConn}.
      * 
      * @param uConn
-     *            java.net.URLConnection the URL connection that points to the
-     *            desired object
+     *            URL connection that points to the desired object.
      * @param types
-     *            The list of acceptable content types
-     * @return Object The object of the resource pointed by this URL, or null if
-     *         the content does not match a specified content type.
-     * 
+     *            list of acceptable content types.
+     * @return resource object pointed by this URL or {@code null} if the
+     *         content doesn't match one of the specified content types.
      * @throws IOException
-     *             If an error occurred obtaining the content.
+     *             if an error occurred while obtaining the content.
      */
     // Class arg not generified in the spec.
     @SuppressWarnings("unchecked")

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandlerFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandlerFactory.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandlerFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/ContentHandlerFactory.java Wed May  6 08:33:17 2009
@@ -18,15 +18,18 @@
 package java.net;
 
 /**
- * Defines a factory which is reponsible for creating a ContentHandler
+ * Defines a factory which is responsible for creating a {@code ContentHandler}.
+ * 
+ * @see ContentHandler
  */
 public interface ContentHandlerFactory {
     /**
-     * Creates a content handler to handle <code>contentType</code>
+     * Creates a content handler to handle {@code contentType}.
      * 
-     * @return java.net.ContentHandler
      * @param contentType
-     *            java.lang.String
+     *            specifies the content type which is handled by the returned
+     *            {@code ContentHandler}.
+     * @return content handler object for a specific content type.
      */
     ContentHandler createContentHandler(String contentType);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CookieHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CookieHandler.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CookieHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/CookieHandler.java Wed May  6 08:33:17 2009
@@ -21,7 +21,7 @@
 import java.util.Map;
 
 /**
- * This class is ready for managing a stateful cookie with HTTP protocol
+ * This class provides a way to manage cookies with a HTTP protocol handler.
  */
 public abstract class CookieHandler {
 
@@ -34,9 +34,9 @@
             "setCookieHandler"); //$NON-NLS-1$
 
     /**
-     * Returns a system-wide cookie handler, or null if not set
+     * Returns the system-wide cookie handler or {@code null} if not set.
      * 
-     * @return a cookie handler
+     * @return the system-wide cookie handler.
      */
     public static CookieHandler getDefault() {
         SecurityManager sm = System.getSecurityManager();
@@ -47,10 +47,10 @@
     }
 
     /**
-     * sets a system-wide cookie handler
+     * Sets the system-wide cookie handler.
      * 
      * @param cHandler
-     *            the cookie handler to set
+     *            a cookie handler to set as the system-wide default handler.
      */
     public static void setDefault(CookieHandler cHandler) {
         SecurityManager sm = System.getSecurityManager();
@@ -61,29 +61,29 @@
     }
 
     /**
-     * Searchs and gets all cookies in the cache by the specified uri in the
-     * request header.
+     * Gets all cookies for a specific URI from the cookie cache.
      * 
      * @param uri
-     *            the specified uri to search for
+     *            a URI to search for applicable cookies.
      * @param requestHeaders
-     *            a list of request headers
-     * @return a map that record all such cookies, the map is unchangeable
+     *            a list of request headers.
+     * @return an unchangeable map of all appropriate cookies.
      * @throws IOException
-     *             if some error of I/O operation occurs
+     *             if an error occurs during the I/O operation.
      */
     public abstract Map<String, List<String>> get(URI uri,
             Map<String, List<String>> requestHeaders) throws IOException;
 
     /**
-     * Sets cookies according to uri and responseHeaders
+     * Sets all cookies of a specific URI in the {@code responseHeaders} into
+     * the cookie cache.
      * 
      * @param uri
-     *            the specified uri
+     *            the origin URI of the cookies.
      * @param responseHeaders
-     *            a list of request headers
+     *            a list of request headers.
      * @throws IOException
-     *             if some error of I/O operation occurs
+     *             if an error occurs during the I/O operation.
      */
     public abstract void put(URI uri, Map<String, List<String>> responseHeaders)
             throws IOException;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramPacket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramPacket.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramPacket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramPacket.java Wed May  6 08:33:17 2009
@@ -20,10 +20,9 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class models a datagram packet to be sent or received. The
- * DatagramPacket(byte[], int, InetAddress, int) constructor is used for packets
- * to be sent, while the DatagramPacket(byte[], int) constructor is used for
- * received packets.
+ * This class represents a datagram packet which contains data either to be sent
+ * or received through a {@code DatagramSocket}. It holds additional information
+ * such as its source or destination host.
  * 
  * @see DatagramSocket
  */
@@ -51,29 +50,28 @@
 
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for receiving
-     * datagram packets of length up to <code>length</code>.
+     * Constructs a new {@code DatagramPacket} object to receive data up to
+     * {@code length} bytes.
      * 
      * @param data
-     *            byte array to store the read characters
+     *            a byte array to store the read characters.
      * @param length
-     *            length of the data buffer
+     *            the length of the data buffer.
      */
     public DatagramPacket(byte[] data, int length) {
         this(data, 0, length);
     }
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for receiving
-     * datagram packets of length up to <code>length</code>, with an offset
-     * into the buffer <code>offset</code>.
+     * Constructs a new {@code DatagramPacket} object to receive data up to
+     * {@code length} bytes with a specified buffer offset.
      * 
      * @param data
-     *            byte array to store the read characters
+     *            a byte array to store the read characters.
      * @param offset
-     *            the offset into the byte array
+     *            the offset of the byte array where the bytes is written.
      * @param length
-     *            length of the data buffer
+     *            the length of the data.
      */
     public DatagramPacket(byte[] data, int offset, int length) {
         super();
@@ -81,22 +79,22 @@
     }
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for sending
-     * packets to the nominated host/port. The <code>length</code> must be
-     * less than or equal to the size of <code>data</code>.
-     * 
+     * Constructs a new {@code DatagramPacket} object to send data to the port
+     * {@code aPort} of the address {@code host}. The {@code length} must be
+     * lesser than or equal to the size of {@code data}. The first {@code
+     * length} bytes from the byte array position {@code offset} are sent.
+     *
      * @param data
-     *            byte array to store the read characters
+     *            a byte array which stores the characters to be sent.
      * @param offset
-     *            the offset in to read/write from
+     *            the offset of {@code data} where to read from.
      * @param length
-     *            length of the data buffer
+     *            the length of data.
      * @param host
-     *            address of the target host
+     *            the address of the target host.
      * @param aPort
-     *            target host port
+     *            the port of the target host.
      */
-
     public DatagramPacket(byte[] data, int offset, int length,
             InetAddress host, int aPort) {
         this(data, offset, length);
@@ -105,89 +103,91 @@
     }
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for sending
-     * packets to the nominated host/port. The <code>length</code> must be
-     * less than or equal to the size of <code>data</code>.
-     * 
+     * Constructs a new {@code DatagramPacket} object to send data to the port
+     * {@code aPort} of the address {@code host}. The {@code length} must be
+     * lesser than or equal to the size of {@code data}. The first {@code
+     * length} bytes are sent.
+     *
      * @param data
-     *            byte array to store the read characters
+     *            a byte array which stores the characters to be sent.
      * @param length
-     *            length of the data buffer
+     *            the length of data.
      * @param host
-     *            address of the target host
+     *            the address of the target host.
      * @param port
-     *            target host port
+     *            the port of the target host.
      */
     public DatagramPacket(byte[] data, int length, InetAddress host, int port) {
         this(data, 0, length, host, port);
     }
 
     /**
-     * Answer the IP address of the machine that is the target or sender of this
-     * datagram.
+     * Gets the sender or destination IP address of this datagram packet.
      * 
-     * @return InetAddress the target host address
+     * @return the address from where the datagram was received or to which it
+     *         is sent.
      */
     public synchronized InetAddress getAddress() {
         return address;
     }
 
     /**
-     * Answer the data sent or received in this datagram.
+     * Gets the data of this datagram packet.
      * 
-     * @return byte[] the data sent/received
+     * @return the received data or the data to be sent.
      */
     public synchronized byte[] getData() {
         return data;
     }
 
     /**
-     * Answer the length of the data sent or received in this datagram.
+     * Gets the length of the data stored in this datagram packet.
      * 
-     * @return int the length of the sent/received data
+     * @return the length of the received data or the data to be sent.
      */
     public synchronized int getLength() {
         return length;
     }
 
     /**
-     * Answer the offset of the data sent or received in this datagram buffer.
+     * Gets the offset of the data stored in this datagram packet.
      * 
-     * @return int the offset of the start of the sent/received data
+     * @return the position of the received data or the data to be sent.
      */
     public synchronized int getOffset() {
         return offset;
     }
 
     /**
-     * Answer the port number of the target or sender machine of this datagram.
-     * 
-     * @return int for received packets, the sender address and for sent
-     *         packets, the target host
+     * Gets the port number of the target or sender host of this datagram
+     * packet.
+     *
+     * @return the port number of the origin or target host.
      */
     public synchronized int getPort() {
         return port;
     }
 
     /**
-     * Set the IP address of the machine that is the target of this datagram.
+     * Sets the IP address of the target host.
      * 
      * @param addr
-     *            the target host address
+     *            the target host address.
      */
     public synchronized void setAddress(InetAddress addr) {
         address = addr;
     }
 
     /**
-     * Set the data buffer for this datagram.
+     * Sets the data buffer for this datagram packet.
      * 
      * @param buf
-     *            the data to be sent
+     *            the buffer to store the data.
      * @param anOffset
-     *            the offset into the data
+     *            the buffer offset where the data is stored.
      * @param aLength
-     *            the length of the data to be sent
+     *            the length of the data to be sent or the length of buffer to
+     *            store the received data.
      */
     public synchronized void setData(byte[] buf, int anOffset, int aLength) {
         if (0 > anOffset || anOffset > buf.length || 0 > aLength
@@ -201,10 +201,11 @@
     }
 
     /**
-     * Set the data sent in this datagram.
+     * Sets the data buffer for this datagram packet. The length of the datagram
+     * packet is set to the buffer length.
      * 
      * @param buf
-     *            the data to be sent
+     *            the buffer to store the data.
      */
     public synchronized void setData(byte[] buf) {
         length = buf.length; // This will check for null
@@ -214,10 +215,11 @@
     }
 
     /**
-     * Set the length of the data sent in this datagram.
+     * Sets the length of the datagram packet. This length plus the offset must
+     * be lesser than or equal to the buffer size.
      * 
      * @param len
-     *            the length of the data to be sent
+     *            the length of this datagram packet.
      */
     public synchronized void setLength(int len) {
         if (0 > len || offset + len > data.length) {
@@ -228,10 +230,10 @@
     }
 
     /**
-     * Set the port number of the target machine of this datagram.
+     * Sets the port number of the target host of this datagram packet.
      * 
      * @param aPort
-     *            the target host port
+     *            the target host port number.
      */
     public synchronized void setPort(int aPort) {
         if (aPort < 0 || aPort > 65535) {
@@ -241,16 +243,19 @@
     }
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for sending
-     * packets to the nominated host/port. The <code>length</code> must be
-     * less than or equal to the size of <code>data</code>.
+     * Constructs a new {@code DatagramPacket} object to send data to the
+     * address {@code sockAddr}. The {@code length} must be lesser than or equal
+     * to the size of {@code data}. The first {@code length} bytes of the data
+     * are sent.
      * 
      * @param data
-     *            byte array to store the read characters
+     *            the byte array to store the data.
      * @param length
-     *            length of the data buffer
+     *            the length of the data.
      * @param sockAddr
-     *            the machine address and port
+     *            the target host address and port.
+     * @throws SocketException
+     *             if an error in the underlying protocol occurs.
      */
     public DatagramPacket(byte[] data, int length, SocketAddress sockAddr)
             throws SocketException {
@@ -259,18 +264,21 @@
     }
 
     /**
-     * Constructs a new <code>DatagramPacket</code> suitable for sending
-     * packets to the nominated host/port. The <code>length</code> must be
-     * less than or equal to the size of <code>data</code>.
+     * Constructs a new {@code DatagramPacket} object to send data to the
+     * address {@code sockAddr}. The {@code length} must be lesser than or equal
+     * to the size of {@code data}. The first {@code length} bytes of the data
+     * are sent.
      * 
      * @param data
-     *            byte array to store the read characters
+     *            the byte array to store the data.
      * @param offset
-     *            the offset in to read/write from
+     *            the offset of the data.
      * @param length
-     *            length of the data buffer
+     *            the length of the data.
      * @param sockAddr
-     *            the machine address and port
+     *            the target host address and port.
+     * @throws SocketException
+     *             if an error in the underlying protocol occurs.
      */
     public DatagramPacket(byte[] data, int offset, int length,
             SocketAddress sockAddr) throws SocketException {
@@ -279,17 +287,20 @@
     }
 
     /**
-     * Answer the SocketAddress for this packet.
+     * Gets the host address and the port to which this datagram packet is sent
+     * as a {@code SocketAddress} object.
+     *
+     * @return the SocketAddress of the target host.
      */
     public synchronized SocketAddress getSocketAddress() {
         return new InetSocketAddress(getAddress(), getPort());
     }
 
     /**
-     * Set the SocketAddress for this packet.
+     * Sets the {@code SocketAddress} for this datagram packet.
      * 
      * @param sockAddr
-     *            the machine address and port
+     *            the SocketAddress of the target host.
      */
     public synchronized void setSocketAddress(SocketAddress sockAddr) {
         if (!(sockAddr instanceof InetSocketAddress)) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocket.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocket.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocket.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocket.java Wed May  6 08:33:17 2009
@@ -25,9 +25,12 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class models a socket for sending & receiving datagram packets.
+ * This class implements a UDP socket for sending and receiving {@code
+ * DatagramPacket}. A {@code DatagramSocket} object can be used for both
+ * endpoints of a connection for a packet delivery service.
  * 
  * @see DatagramPacket
+ * @see DatagramSocketImplFactory
  */
 public class DatagramSocket {
 
@@ -55,24 +58,25 @@
     private Object lock = new Lock();
 
     /**
-     * Constructs a datagram socket, bound to any available port on the
-     * localhost.
+     * Constructs a UDP datagram socket which is bound to any available port on
+     * the localhost.
      * 
      * @throws SocketException
-     *             if a problem occurs creating or binding the socket
+     *             if an error occurs while creating or binding the socket.
      */
     public DatagramSocket() throws SocketException {
         this(0);
     }
 
     /**
-     * Answers a datagram socket, bound to the nominated port on the localhost.
+     * Constructs a UDP datagram socket which is bound to the specific port
+     * {@code aPort} on the localhost. Valid values for {@code aPort} are
+     * between 0 and 65535 inclusive.
      * 
      * @param aPort
-     *            the port to bind on the localhost
-     * 
+     *            the port to bind on the localhost.
      * @throws SocketException
-     *             if a problem occurs creating or binding the socket
+     *             if an error occurs while creating or binding the socket.
      */
     public DatagramSocket(int aPort) throws SocketException {
         super();
@@ -81,15 +85,16 @@
     }
 
     /**
-     * Constructs a datagram socket, bound to the nominated localhost/port.
+     * Constructs a UDP datagram socket which is bound to the specific local
+     * address {@code addr} on port {@code aPort}. Valid values for {@code
+     * aPort} are between 0 and 65535 inclusive.
      * 
      * @param aPort
-     *            the port on the localhost to bind
+     *            the port to bind on the localhost.
      * @param addr
-     *            the address on the multihomed localhost to bind
-     * 
+     *            the address to bind on the localhost.
      * @throws SocketException
-     *             if a problem occurs creating or binding the socket
+     *             if an error occurs while creating or binding the socket.
      */
     public DatagramSocket(int aPort, InetAddress addr) throws SocketException {
         super();
@@ -98,12 +103,12 @@
     }
 
     /**
-     * Sent prior to attempting to bind the socket, check that the port is
-     * within the valid port range and verify with the security manager that the
-     * port may be bound by the current context.
+     * Sends prior to attempting to bind the socket, checks whether the port is
+     * within the valid port range and verifies with the security manager that
+     * the port may be bound by the current context.
      * 
      * @param aPort
-     *            the port on the localhost that is to be bound
+     *            the port on the localhost that is to be bound.
      */
     void checkListen(int aPort) {
         if (aPort < 0 || aPort > 65535) {
@@ -116,7 +121,7 @@
     }
 
     /**
-     * Close the socket.
+     * Closes this UDP datagram socket and all possibly associated channels.
      */
     // In the documentation jdk1.1.7a/guide/net/miscNet.html, this method is
     // noted as not being synchronized.
@@ -126,14 +131,16 @@
     }
 
     /**
-     * Connect the datagram socket to a remote host and port. The host and port
-     * are validated, thereafter the only validation on send() and receive() is
-     * that the packet address/port matches the connected target.
+     * Connects this UDP datagram socket to the specific target host with the
+     * address {@code anAdress} on port {@code aPort}. The host and port are
+     * validated, thereafter the only validation on {@code send()} and {@code
+     * receive()} is to check whether the packet address/port matches the
+     * connected target.
      * 
      * @param anAddress
-     *            the target address
+     *            the target address of this socket.
      * @param aPort
-     *            the target port
+     *            the target port of this socket.
      */
     public void connect(InetAddress anAddress, int aPort) {
         if (anAddress == null || aPort < 0 || aPort > 65535) {
@@ -171,8 +178,8 @@
     }
 
     /**
-     * 'Disconnect' the datagram socket from a remote host and port. This method
-     * may be called on an unconnected socket.
+     * Disconnects this UDP datagram socket from the remote host. This method
+     * called on an unconnected socket does nothing.
      */
     public void disconnect() {
         if (isClosed() || !isConnected()) {
@@ -199,21 +206,22 @@
     }
 
     /**
-     * Returns an {@link InetAddress} instance representing the address this
-     * socket has connected to.
+     * Gets the {@code InetAddress} instance representing the remote address to
+     * which this UDP datagram socket is connected.
      * 
-     * @return if this socket is connected, the address it is connected to. A
-     *         <code>null</code> return signifies no connection has been made.
+     * @return the remote address this socket is connected to or {@code null} if
+     *         this socket is not connected.
      */
     public InetAddress getInetAddress() {
         return address;
     }
 
     /**
-     * Returns an {@link InetAddress} instance representing the <i>local</i>
-     * address this socket is bound to.
+     * Gets the {@code InetAddress} instance representing the bound local
+     * address of this UDP datagram socket.
      * 
-     * @return the local address to which the socket is bound
+     * @return the local address to which this socket is bound to or {@code
+     *         null} if this socket is closed.
      */
     public InetAddress getLocalAddress() {
         if (isClosed()) {
@@ -235,9 +243,10 @@
     }
 
     /**
-     * Answer the local port to which the socket is bound.
+     * Gets the local port which this socket is bound to.
      * 
-     * @return int local port to which the socket is bound
+     * @return the local port of this socket or {@code -1} if this socket is
+     *         closed and {@code 0} if it is unbound.
      */
     public int getLocalPort() {
         if (isClosed()) {
@@ -250,23 +259,30 @@
     }
 
     /**
-     * Returns the number of the remote port this socket is connected to.
+     * Gets the remote port which this socket is connected to.
      * 
-     * @return int the remote port number that this socket has connected to. A
-     *         return of <code>-1</code> indicates that there is no connection
-     *         in place.
+     * @return the remote port of this socket. The return value {@code -1}
+     *         indicates that this socket is not connected.
      */
     public int getPort() {
         return port;
     }
 
     /**
-     * Answer the socket receive buffer size (SO_RCVBUF).
+     * Indicates whether this socket is multicast or not.
      * 
-     * @return int socket receive buffer size
+     * @return the return value is always {@code false}.
+     */
+    boolean isMulticastSocket() {
+        return false;
+    }
+
+    /**
+     * Gets the socket receive buffer size. ( {@code SocketOptions.SO_RCVBUF} )
      * 
-     * @exception SocketException
-     *                when an error occurs
+     * @return the input buffer size.
+     * @throws SocketException
+     *                if an error occurs while getting the option value.
      */
     public synchronized int getReceiveBufferSize() throws SocketException {
         checkClosedAndBind(false);
@@ -274,12 +290,11 @@
     }
 
     /**
-     * Answer the socket send buffer size (SO_SNDBUF).
-     * 
-     * @return int socket send buffer size
+     * Gets the socket send buffer size. ( {@code SocketOptions.SO_SNDBUF} )
      * 
-     * @exception SocketException
-     *                when an error occurs
+     * @return the output buffer size.
+     * @throws SocketException
+     *                if an error occurs while getting the option value.
      */
     public synchronized int getSendBufferSize() throws SocketException {
         checkClosedAndBind(false);
@@ -287,13 +302,13 @@
     }
 
     /**
-     * Answer the socket receive timeout (SO_RCVTIMEOUT), in milliseconds. Zero
-     * implies the timeout is disabled.
-     * 
-     * @return int socket receive timeout
+     * Gets the socket receive timeout in milliseconds. The return value {@code
+     * 0} implies the timeout is disabled/infinitive. ( {@code
+     * SocketOptions.SO_TIMEOUT} )
      * 
-     * @exception SocketException
-     *                when an error occurs
+     * @return the socket receive timeout.
+     * @throws SocketException
+     *                if an error occurs while getting the option value.
      */
     public synchronized int getSoTimeout() throws SocketException {
         checkClosedAndBind(false);
@@ -301,20 +316,18 @@
     }
 
     /**
-     * Receive on this socket into the packet argument. This method blocks until
-     * a packet is received or, if a timeout has been defined, the timeout
-     * period expires. If this is a connected socket, the packet host/port are
-     * compared to the connection host/port otherwise the security manager if
-     * present is queried whether the packet host/port is acceptable. Any
-     * packets from unacceptable origins will be silently discarded. The packet
-     * fields are set according to the data received. If the received data is
-     * longer than the packet buffer, it is truncated.
+     * Receives a packet from this socket and stores it in the argument {@code
+     * pack}. All fields of {@code pack} must be set according to the data
+     * received. If the received data is longer than the packet buffer size it
+     * is truncated. This method blocks until a packet is received or a timeout
+     * has expired. If a security manager exists, its {@code checkAccept} method
+     * determines whether or not a packet is discarded. Any packets from
+     * unacceptable origins are silently discarded.
      * 
      * @param pack
-     *            the DatagramPacket to receive data into
-     * 
-     * @exception java.io.IOException
-     *                If a receive error occurs.
+     *            the {@code DatagramPacket} to store the received data.
+     * @throws IOException
+     *                if an error occurs while receiving the packet.
      */
     public synchronized void receive(DatagramPacket pack) throws IOException {
         checkClosedAndBind(true);
@@ -403,14 +416,15 @@
     }
 
     /**
-     * Send the packet on this socket. The packet must satisfy the security
-     * policy before it may be sent.
+     * Sends a packet over this socket. The packet must satisfy the security
+     * policy before it may be sent. If a security manager is installed, this
+     * method checks whether it is allowed to send this packet to the specified
+     * address.
      * 
      * @param pack
-     *            the DatagramPacket to send
-     * 
-     * @exception java.io.IOException
-     *                If a send error occurs.
+     *            the {@code DatagramPacket} which has to be sent.
+     * @throws IOException
+     *                if an error occurs while sending the packet.
      */
     public void send(DatagramPacket pack) throws IOException {
         checkClosedAndBind(true);
@@ -448,14 +462,15 @@
     }
 
     /**
-     * Set the socket send buffer size.
+     * Sets the socket send buffer size. This buffer size determines which the
+     * maximum packet size is that can be sent over this socket. It depends on
+     * the network implementation what will happen if the packet is bigger than
+     * the buffer size. ( {@code SocketOptions.SO_SNDBUF} )
      * 
      * @param size
-     *            the buffer size, in bytes. Must be at least one byte.
-     * 
-     * @exception java.net.SocketException
-     *                If an error occurs while setting the size or the size is
-     *                invalid.
+     *            the buffer size in bytes. The size must be at least one byte.
+     * @throws SocketException
+     *                if an error occurs while setting the option.
      */
     public synchronized void setSendBufferSize(int size) throws SocketException {
         if (size < 1) {
@@ -466,14 +481,15 @@
     }
 
     /**
-     * Set the socket receive buffer size.
+     * Sets the socket receive buffer size. This buffer size determines which
+     * the maximum packet size is that can be received over this socket. It
+     * depends on the network implementation what will happen if the packet is
+     * bigger than the buffer size. ( {@code SocketOptions.SO_RCVBUF} )
      * 
      * @param size
-     *            the buffer size, in bytes. Must be at least one byte.
-     * 
-     * @exception java.net.SocketException
-     *                If an error occurs while setting the size or the size is
-     *                invalid.
+     *            the buffer size in bytes. The size must be at least one byte.
+     * @throws SocketException
+     *                if an error occurs while setting the option.
      */
     public synchronized void setReceiveBufferSize(int size)
             throws SocketException {
@@ -485,16 +501,17 @@
     }
 
     /**
-     * Set the SO_RCVTIMEOUT to <code>timeout</code>, in milliseconds. The
-     * receive timeout defines the period a socket will block waiting to receive
-     * data, before throwing an InterruptedIOException.
+     * Sets the timeout period in milliseconds for the {@code receive()} method.
+     * This receive timeout defines the period the socket will block waiting to
+     * receive data before throwing an {@code InterruptedIOException}. The value
+     * {@code 0} (default) is used to set an infinite timeout. To have effect
+     * this option must be set before the blocking method was called. ( {@code
+     * SocketOptions.SO_TIMEOUT} )
      * 
      * @param timeout
-     *            the timeout period, in milliseconds
-     * 
-     * @exception java.net.SocketException
-     *                If an error occurs while setting the timeout or the period
-     *                is invalid.
+     *            the timeout period in milliseconds or {@code 0} for infinite.
+     * @throws SocketException
+     *                if an error occurs while setting the option.
      */
     public synchronized void setSoTimeout(int timeout) throws SocketException {
         if (timeout < 0) {
@@ -505,13 +522,18 @@
     }
 
     /**
-     * Specifies the application's socket implementation factory. This may only
-     * be invoked once over the lifetime of the application.
+     * Sets the socket implementation factory. This may only be invoked once
+     * over the lifetime of the application. This factory is used to create
+     * a new datagram socket implementation. If a security manager is set its
+     * method {@code checkSetFactory()} is called to check if the operation is
+     * allowed. A {@code SecurityException} is thrown if the operation is not
+     * allowed.
      * 
      * @param fac
-     *            the socket factory to set
-     * @exception IOException
-     *                thrown if the factory has already been set
+     *            the socket factory to use.
+     * @throws IOException
+     *                if the factory has already been set.
+     * @see DatagramSocketImplFactory
      */
     public static synchronized void setDatagramSocketImplFactory(
             DatagramSocketImplFactory fac) throws IOException {
@@ -526,11 +548,12 @@
     }
 
     /**
-     * Constructs a DatagramSocket using the specified DatagramSocketImpl. The
-     * DatagramSocket is not bound.
+     * Constructs a new {@code DatagramSocket} using the specific datagram
+     * socket implementation {@code socketImpl}. The created {@code
+     * DatagramSocket} will not be bound.
      * 
      * @param socketImpl
-     *            the DatagramSocketImpl to use
+     *            the DatagramSocketImpl to use.
      */
     protected DatagramSocket(DatagramSocketImpl socketImpl) {
         if (socketImpl == null) {
@@ -540,16 +563,16 @@
     }
 
     /**
-     * Constructs a DatagramSocket bound to the host/port specified by the
-     * SocketAddress, or an unbound DatagramSocket if the SocketAddress is null.
+     * Constructs a new {@code DatagramSocket} bound to the host/port specified
+     * by the {@code SocketAddress} {@code localAddr} 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
      * @throws SocketException
-     *             if a problem occurs creating or binding the socket
+     *             if a problem occurs creating or binding the socket.
      */
     public DatagramSocket(SocketAddress localAddr) throws SocketException {
         if (localAddr != null) {
@@ -586,16 +609,17 @@
     }
 
     /**
-     * Bind the DatagramSocket to the nominated local host/port.
+     * Binds this socket to the local address and port specified by {@code
+     * localAddr}. If this value is {@code null} any free port on a valid local
+     * address is used.
      * 
      * @param localAddr
-     *            the local machine address and port to bind on
-     * 
+     *            the local machine address and port to bind on.
      * @throws IllegalArgumentException
      *             if the SocketAddress is not supported
      * @throws SocketException
-     *             if the socket is already bound, or a problem occurs during
-     *             the bind
+     *             if the socket is already bound or a problem occurs during
+     *             binding.
      */
     public void bind(SocketAddress localAddr) throws SocketException {
         checkClosedAndBind(false);
@@ -620,15 +644,15 @@
     }
 
     /**
-     * Connect the datagram socket to a remote host and port. The host and port
-     * are validated, thereafter the only validation on send() and receive() is
-     * that the packet address/port matches the connected target.
+     * Connects this datagram socket to the remote host and port specified by
+     * {@code remoteAddr}. The host and port are validated, thereafter the only
+     * validation on {@code send()} and {@code receive()} is that the packet
+     * address/port matches the connected target.
      * 
      * @param remoteAddr
-     *            the target address and port
-     * 
-     * @exception SocketException
-     *                if a problem occurs during the connect
+     *            the address and port of the target host.
+     * @throws SocketException
+     *                if an error occurs during connecting.
      */
     public void connect(SocketAddress remoteAddr) throws SocketException {
         if (remoteAddr == null) {
@@ -677,30 +701,28 @@
     }
 
     /**
-     * Return if the socket is bound to a local address and port.
+     * Determines whether the socket is bound to an address or not.
      * 
-     * @return <code>true</code> if the socket is bound to a local address,
-     *         <code>false</code> otherwise.
+     * @return {@code true} if the socket is bound, {@code false} otherwise.
      */
     public boolean isBound() {
         return isBound;
     }
 
     /**
-     * Return if the socket is connected.
+     * Determines whether the socket is connected to a target host.
      * 
-     * @return <code>true</code> if the socket is connected,
-     *         <code>false</code> otherwise.
+     * @return {@code true} if the socket is connected, {@code false} otherwise.
      */
     public boolean isConnected() {
         return isConnected;
     }
 
     /**
-     * Answer the remote SocketAddress for this socket, or null if the socket is
-     * not connected.
+     * Gets the address and port of the connected remote host. If this socket is
+     * not connected yet, {@code null} is returned.
      * 
-     * @return the remote socket address
+     * @return the remote socket address.
      */
     public SocketAddress getRemoteSocketAddress() {
         if (!isConnected()) {
@@ -710,12 +732,10 @@
     }
 
     /**
-     * Answer the local SocketAddress for this socket, or null if the socket is
-     * not bound.
-     * <p>
-     * This is useful on multihomed hosts.
+     * Gets the bound local address and port of this socket. If the socket is
+     * unbound, {@code null} is returned.
      * 
-     * @return the local socket address
+     * @return the local socket address.
      */
     public SocketAddress getLocalSocketAddress() {
         if (!isBound()) {
@@ -725,13 +745,17 @@
     }
 
     /**
-     * Set the SO_REUSEADDR socket option.
+     * Sets the socket option {@code SocketOptions.SO_REUSEADDR}. This option
+     * has to be enabled if more than one UDP socket wants to be bound to the
+     * same address. That could be needed for receiving multicast packets.
+     * <p>
+     * There is an undefined behavior if this option is set after the socket is
+     * already bound.
      * 
      * @param reuse
-     *            the socket SO_REUSEADDR option setting
-     * 
+     *            the socket option value to enable or disable this option.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if the socket is closed or the option could not be set.
      */
     public void setReuseAddress(boolean reuse) throws SocketException {
         checkClosedAndBind(false);
@@ -740,11 +764,9 @@
     }
 
     /**
-     * Get the state of the SO_REUSEADDR socket option.
-     * 
-     * @return <code>true</code> if the SO_REUSEADDR is enabled,
-     *         <code>false</code> otherwise.
+     * Gets the state of the socket option {@code SocketOptions.SO_REUSEADDR}.
      * 
+     * @return {@code true} if the option is enabled, {@code false} otherwise.
      * @throws SocketException
      *             if the socket is closed or the option is invalid.
      */
@@ -755,13 +777,13 @@
     }
 
     /**
-     * Set the SO_BROADCAST socket option.
+     * Sets the socket option {@code SocketOptions.SO_BROADCAST}. This option
+     * must be enabled to send broadcast messages.
      * 
      * @param broadcast
-     *            the socket SO_BROADCAST option setting
-     * 
+     *            the socket option value to enable or disable this option.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if the socket is closed or the option could not be set.
      */
     public void setBroadcast(boolean broadcast) throws SocketException {
         checkClosedAndBind(false);
@@ -770,11 +792,9 @@
     }
 
     /**
-     * Get the state of the SO_BROADCAST socket option.
-     * 
-     * @return <code>true</code> if the SO_BROADCAST is enabled,
-     *         <code>false</code> otherwise.
+     * Gets the state of the socket option {@code SocketOptions.SO_BROADCAST}.
      * 
+     * @return {@code true} if the option is enabled, {@code false} otherwise.
      * @throws SocketException
      *             if the socket is closed or the option is invalid.
      */
@@ -785,13 +805,18 @@
     }
 
     /**
-     * Set the IP_TOS socket option.
-     * 
+     * Sets the socket option {@code SocketOptions.IP_TOS}. This option defines
+     * the value of the type-of-service field of the IP-header for every packet
+     * sent by this socket. The value could be ignored by the underlying network
+     * implementation.
+     * <p>
+     * Values between {@code 0} and {@code 255} inclusive are valid for this
+     * option.
+     *
      * @param value
-     *            the socket IP_TOS setting
-     * 
+     *            the socket option value to be set as type-of-service.
      * @throws SocketException
-     *             if the socket is closed or the option is invalid.
+     *             if the socket is closed or the option could not be set.
      */
     public void setTrafficClass(int value) throws SocketException {
         checkClosedAndBind(false);
@@ -802,12 +827,12 @@
     }
 
     /**
-     * Get the IP_TOS socket option.
-     * 
-     * @return the IP_TOS socket option value
+     * Gets the value of the type-of-service socket option {@code
+     * SocketOptions.IP_TOS}.
      * 
+     * @return the type-of-service socket option value.
      * @throws SocketException
-     *             if the option is invalid
+     *             if the socket is closed or the option is invalid.
      */
     public int getTrafficClass() throws SocketException {
         checkClosedAndBind(false);
@@ -815,20 +840,20 @@
     }
 
     /**
-     * Return if the socket is closed.
+     * Gets the state of this socket.
      * 
-     * @return <code>true</code> if the socket is closed, <code>false</code>
-     *         otherwise.
+     * @return {@code true} if the socket is closed, {@code false} otherwise.
      */
     public boolean isClosed() {
         return isClosed;
     }
 
     /**
-     * if DatagramSocket is created by a DatagramChannel, returns the related
-     * DatagramChannel
+     * Gets the related DatagramChannel of this socket. This implementation
+     * returns always {@code null}.
      * 
-     * @return the related DatagramChannel if any
+     * @return the related DatagramChannel or {@code null} if this socket was
+     *         not created by a {@code DatagramChannel} object.
      */
     public DatagramChannel getChannel() {
         return null;



Mime
View raw message