Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 86781 invoked from network); 6 May 2009 08:34:01 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 6 May 2009 08:34:01 -0000 Received: (qmail 17528 invoked by uid 500); 6 May 2009 08:34:01 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 17480 invoked by uid 500); 6 May 2009 08:34:00 -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 17443 invoked by uid 99); 6 May 2009 08:34:00 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 06 May 2009 08:34:00 +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:46 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id D4EC32388A66; 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 [1/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.D4EC32388A66@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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 Authenticator by - * setDefault(Authenticator a). - *

- * It should override getPasswordAuthentication() 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}. *

- * 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 a 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 - * ResponseCache. Protocol handler calls the - * OutputStream 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 abort. - * 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(); /** - *

- * Returns an OutputStream, which is used to write the - * response body. - *

+ * Returns an {@code OutputStream} which is used to write the response body. * - * @return an OutputStream 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 InputStream to access the - * response body, and also a method getHeaders() 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 InputStream for the respsonse body access. + * Returns an {@code InputStream} to access the response body. * - * @return an InputStream, 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 Map, which contains the response - * headers information. + * Returns an immutable {@code Map} which contains the response headers + * information. * - * @return an immutable Map, which contains the response - * headers. The map is from response header field names to lists of - * field values. Field name is a String, and the - * field values list is a List of String.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> 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 ContentHandlerFactory + * 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 - * uConn. + * Returns the object pointed by the specified URL connection {@code uConn}. * - * @return java.lang.Object the object referred by uConn * @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 - * uConn. + * 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 contentType + * 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> get(URI uri, Map> 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> 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 DatagramPacket suitable for receiving - * datagram packets of length up to length. + * 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 DatagramPacket suitable for receiving - * datagram packets of length up to length, with an offset - * into the buffer offset. + * 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 DatagramPacket suitable for sending - * packets to the nominated host/port. The length must be - * less than or equal to the size of data. - * + * 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 DatagramPacket suitable for sending - * packets to the nominated host/port. The length must be - * less than or equal to the size of data. - * + * 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 DatagramPacket suitable for sending - * packets to the nominated host/port. The length must be - * less than or equal to the size of data. + * 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 DatagramPacket suitable for sending - * packets to the nominated host/port. The length must be - * less than or equal to the size of data. + * 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 - * null 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 local - * 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 -1 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 timeout, 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 true if the socket is bound to a local address, - * false 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 true if the socket is connected, - * false 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. - *

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

+ * 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 true if the SO_REUSEADDR is enabled, - * false 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 true if the SO_BROADCAST is enabled, - * false 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. + *

+ * 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 true if the socket is closed, false - * 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;