You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/06 10:33:22 UTC
svn commit: r772095 [2/6] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImpl.java Wed May 6 08:33:17 2009
@@ -24,12 +24,18 @@
import org.apache.harmony.luni.platform.Platform;
/**
- * The abstract superclass of datagram & multicast socket implementations.
+ * The abstract superclass for datagram and multicast socket implementations.
*/
public abstract class DatagramSocketImpl implements SocketOptions {
+ /**
+ * File descriptor that is used to address this socket.
+ */
protected FileDescriptor fd;
+ /**
+ * The number of the local port to which this socket is bound.
+ */
protected int localPort;
/**
@@ -40,46 +46,48 @@
}
/**
- * Bind the datagram socket to the nominated localhost/port. Sockets must be
+ * Binds the datagram socket to the given localhost/port. Sockets must be
* bound prior to attempting to send or receive data.
*
* @param port
- * the port on the localhost to bind
+ * the port on the localhost to bind.
* @param addr
- * the address on the multihomed localhost to bind
- *
- * @exception SocketException
- * if an error occurred during bind, such as if the port was
- * already bound
+ * the address on the multihomed localhost to bind.
+ * @throws SocketException
+ * if an error occurs while binding, for example, if the port
+ * has been already bound.
*/
protected abstract void bind(int port, InetAddress addr)
throws SocketException;
/**
- * Close the socket.
+ * Closes this socket.
*/
protected abstract void close();
/**
* This method allocates the socket descriptor in the underlying operating
* system.
+ *
+ * @throws SocketException
+ * if an error occurs while creating the socket.
*/
protected abstract void create() throws SocketException;
/**
- * Answer the FileDescriptor, which will be invalid if the socket is closed
- * or not bound.
+ * Gets the {@code FileDescriptor} of this datagram socket, which is invalid
+ * if the socket is closed or not bound.
*
- * @return FileDescriptor the socket file descriptor
+ * @return the current file descriptor of this socket.
*/
protected FileDescriptor getFileDescriptor() {
return fd;
}
/**
- * Answer the local address to which the socket is bound.
+ * Gets the local address to which the socket is bound.
*
- * @return InetAddress the local address to which the socket is bound.
+ * @return the local address to which the socket is bound.
*/
InetAddress getLocalAddress() {
return Platform.getNetworkSystem().getSocketLocalAddress(fd,
@@ -87,174 +95,192 @@
}
/**
- * Answer the local port. If the socket was bound to any available port, as
- * flagged by a <code>localPort</code> value of -1, query the IP stack.
+ * Gets the local port of this socket.
*
- * @return int the local port to which the socket is bound.
+ * @return the local port to which this socket is bound.
*/
protected int getLocalPort() {
return localPort;
}
/**
- * Answer the nominated socket option.
+ * Gets the value for the specified socket option.
*
* @param optID
- * the socket option to retrieve
- * @return Object the option value
- * @exception SocketException
- * thrown if an error occurs while accessing the option
+ * the ID of the socket option to be retrieved.
+ * @return the requested option value.
+ * @throws SocketException
+ * if an error occurs while accessing the option.
*/
public abstract Object getOption(int optID) throws SocketException;
/**
- * Answer the time-to-live (TTL) for multicast packets sent on this socket.
+ * Gets the time-to-live (TTL) for multicast packets sent on this socket.
*
- * @return java.net.InetAddress
+ * @return the time-to-live option as a byte value.
* @throws IOException
- * The exception description.
- * @deprecated Replaced by getTimeToLive
+ * if an error occurs while getting the time-to-live option
+ * value.
+ * @deprecated Replaced by {@link #getTimeToLive}
* @see #getTimeToLive()
*/
@Deprecated
protected abstract byte getTTL() throws IOException;
/**
- * Answer the time-to-live (TTL) for multicast packets sent on this socket.
- *
- * @return int
+ * Gets the time-to-live (TTL) for multicast packets sent on this socket.
+ * The TTL option defines how many routers a packet may be pass before it is
+ * discarded.
+ *
+ * @return the time-to-live option as an integer value.
* @throws IOException
- * The exception description.
+ * if an error occurs while getting the time-to-live option
+ * value.
*/
protected abstract int getTimeToLive() throws IOException;
/**
- * Add this socket to the multicast group. A socket must join a group before
- * data may be received. A socket may be a member of multiple groups but may
- * join any group once.
+ * Adds this socket to the multicast group {@code addr}. A socket must join
+ * a group before being able to receive data. Further, a socket may be a
+ * member of multiple groups but may join any group only once.
*
* @param addr
- * the multicast group to be joined
+ * the multicast group to which this socket has to be joined.
* @throws IOException
- * may be thrown while joining a group
+ * if an error occurs while joining the specified multicast
+ * group.
*/
protected abstract void join(InetAddress addr) throws IOException;
/**
- * Add this socket to the multicast group. A socket must join a group before
- * data may be received. A socket may be a member of multiple groups but may
- * join any group once.
+ * Adds this socket to the multicast group {@code addr}. A socket must join
+ * a group before being able to receive data. Further, a socket may be a
+ * member of multiple groups but may join any group only once.
*
* @param addr
- * the multicast group to be joined
+ * the multicast group to which this socket has to be joined.
* @param netInterface
- * the network interface on which the addresses should be dropped
+ * the local network interface which will receive the multicast
+ * datagram packets.
* @throws IOException
- * may be thrown while joining a group
+ * if an error occurs while joining the specified multicast
+ * group.
*/
protected abstract void joinGroup(SocketAddress addr,
NetworkInterface netInterface) throws IOException;
/**
- * Remove the socket from the multicast group.
+ * Removes this socket from the multicast group {@code addr}.
*
* @param addr
- * the multicast group to be left
+ * the multicast group to be left.
* @throws IOException
- * May be thrown while leaving the group
+ * if an error occurs while leaving the group or no multicast
+ * address was assigned.
*/
protected abstract void leave(InetAddress addr) throws IOException;
/**
- * Remove the socket from the multicast group.
+ * Removes this socket from the multicast group {@code addr}.
*
* @param addr
- * the multicast group to be left
+ * the multicast group to be left.
* @param netInterface
- * the network interface on which the addresses should be dropped
+ * the local network interface on which this socket has to be
+ * removed.
* @throws IOException
- * May be thrown while leaving the group
+ * if an error occurs while leaving the group.
*/
protected abstract void leaveGroup(SocketAddress addr,
NetworkInterface netInterface) throws IOException;
/**
- * Peek at the incoming packet to this socket and answer the sender's
- * address into <code>sender</code>. The method will block until a packet
- * is received or timeout expires and returns the sender's port.
- *
- * @exception IOException
- * if a read error or timeout occurs
+ * Peeks at the incoming packet to this socket and returns the address of
+ * the {@code sender}. The method will block until a packet is received or
+ * timeout expires.
+ *
+ * @param sender
+ * the origin address of a packet.
+ * @return the address of {@code sender} as an integer value.
+ * @throws IOException
+ * if an error or a timeout occurs while reading the address.
*/
protected abstract int peek(InetAddress sender) throws IOException;
/**
- * Receive data into the supplied datagram packet. This call will block
- * until either data is received or, if a timeout is set, the timeout
- * expires. If the timeout expires, the InterruptedIOException is thrown.
+ * Receives data and stores it in the supplied datagram packet {@code pack}.
+ * This call will block until either data has been received or, if a timeout
+ * is set, the timeout has expired. If the timeout expires an {@code
+ * InterruptedIOException} is thrown.
*
- * @exception IOException
- * if a read error or timeout occurs
+ * @param pack
+ * the datagram packet container to fill in the received data.
+ * @throws IOException
+ * if an error or timeout occurs while receiving data.
*/
protected abstract void receive(DatagramPacket pack) throws IOException;
/**
- * Sends the supplied datagram packet. The packet contains the destination
- * host & port.
+ * Sends the given datagram packet {@code pack}. The packet contains the
+ * data and the address and port information of the target host as well.
*
* @param pack
- * DatagramPacket to send
- *
- * @exception IOException
- * if a write error occurs
+ * the datagram packet to be sent.
+ * @throws IOException
+ * if an error occurs while sending the packet.
*/
protected abstract void send(DatagramPacket pack) throws IOException;
/**
- * Set the nominated socket option.
+ * Sets the value for the specified socket option.
*
* @param optID
- * the socket option to set
+ * the ID of the socket option to be set.
* @param val
- * the option value
- * @exception SocketException
- * thrown if an error occurs while setting the option
+ * the value of the option.
+ * @throws SocketException
+ * if an error occurs while setting the option.
*/
public abstract void setOption(int optID, Object val)
throws SocketException;
/**
- * Set the time-to-live (TTL) for multicast packets sent on this socket.
+ * Sets the time-to-live (TTL) option for multicast packets sent on this
+ * socket.
*
* @param ttl
- * the time-to-live, 0<ttl<= 255
- * @throws IOException The exception thrown while setting the TTL
+ * the time-to-live option value. Valid values are 0 < ttl
+ * <= 255.
+ * @throws IOException
+ * if an error occurs while setting the option.
*/
protected abstract void setTimeToLive(int ttl) throws IOException;
/**
- * Set the time-to-live (TTL) for multicast packets sent on this socket.
+ * Sets the time-to-live (TTL) option for multicast packets sent on this
+ * socket.
*
* @param ttl
- * the time-to-live, 0<ttl<= 255
- * @throws IOException The exception thrown while setting the TTL
- * @deprecated Replaced by setTimeToLive
+ * the time-to-live option value. Valid values are 0 < ttl
+ * <= 255.
+ * @throws IOException
+ * if an error occurs while setting the option.
+ * @deprecated Replaced by {@link #setTimeToLive}
* @see #setTimeToLive(int)
*/
@Deprecated
protected abstract void setTTL(byte ttl) throws IOException;
/**
- * Connect the socket to the specified remote address and port.
+ * Connects this socket to the specified remote address and port.
*
* @param inetAddr
- * the remote address
+ * the address of the target host which has to be connected.
* @param port
- * the remote port
- *
- * @exception SocketException
- * possibly thrown, if the datagram socket cannot be
- * connected to the specified remote address and port
+ * the port on the target host which has to be connected.
+ * @throws SocketException
+ * if the datagram socket cannot be connected to the
+ * specified remote address and port.
*/
protected void connect(InetAddress inetAddr, int port)
throws SocketException {
@@ -262,26 +288,24 @@
}
/**
- * Disconnect the socket from the remote address and port.
+ * Disconnects this socket from the remote host.
*/
protected void disconnect() {
// do nothing
}
/**
- * Receive data into the supplied datagram packet by peeking. The data is
- * not removed and will be received by another peekData() or receive() call.
- *
- * This call will block until either data is received or, if a timeout is
- * set, the timeout expires.
+ * Receives data into the supplied datagram packet by peeking. The data is
+ * not removed from socket buffer and can be received again by another
+ * {@code peekData()} or {@code receive()} call. This call blocks until
+ * either data has been received or, if a timeout is set, the timeout has
+ * been expired.
*
* @param pack
- * the DatagramPacket used to store the data
- *
- * @return the port the packet was received from
- *
- * @exception IOException
- * if an error occurs
+ * the datagram packet used to store the data.
+ * @return the port the packet was received from.
+ * @throws IOException
+ * if an error occurs while peeking at the data.
*/
protected abstract int peekData(DatagramPacket pack) throws IOException;
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/DatagramSocketImplFactory.java Wed May 6 08:33:17 2009
@@ -19,14 +19,17 @@
/**
* This interface defines a factory for datagram socket implementations. It is
- * used by the class <code>DatagramSocket</code> to create datagram socket
- * implementations.
+ * used by the class {@code DatagramSocket} to create a new datagram socket
+ * implementation.
+ *
+ * @see DatagramSocket
*/
public interface DatagramSocketImplFactory {
+
/**
- * Creates a new <code>SocketImpl</code> instance.
+ * Creates a new {@code DatagramSocketImpl} instance.
*
- * @return SocketImpl
+ * @return the new datagram socket implementation.
*/
DatagramSocketImpl createDatagramSocketImpl();
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/FileNameMap.java Wed May 6 08:33:17 2009
@@ -19,8 +19,8 @@
/**
* Defines a scheme for mapping a filename type to a MIME content type. Mainly
- * used by <code>URLStreamHandler</code> for determining the right content
- * handler to handle the resource.
+ * used by {@code URLStreamHandler} for determining the right content handler to
+ * handle the resource.
*
* @see ContentHandler
* @see URLConnection#getFileNameMap()
@@ -30,13 +30,11 @@
public interface FileNameMap {
/**
- * Determines the MIME types for a file <code>fileName</code> of a
- * <code>URL</code>.
+ * Determines the MIME type for a file {@code fileName} of a URL.
*
* @param fileName
* the name of the file to consider.
- *
- * @return the mime type
+ * @return the appropriate MIME type of the given file.
*/
public String getContentTypeFor(String fileName);
}
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpRetryException.java Wed May 6 08:33:17 2009
@@ -19,7 +19,8 @@
import java.io.IOException;
/**
- * The exception to be thrown when a request cannot be retried.
+ * If a HTTP request has to be retried, this exception will be thrown if the
+ * request cannot be retried automatically.
*/
public class HttpRetryException extends IOException {
@@ -30,12 +31,13 @@
private String location = null;
/**
- * new a HttpRetryException by given detail message and responseCode
+ * Creates a new {@code HttpRetryException} instance with the specified
+ * response code and the given detail message.
*
* @param detail
- * detail for this exception
+ * the detail message for this exception.
* @param code
- * http response code to return
+ * the HTTP response code from target host.
*/
public HttpRetryException(String detail, int code) {
super(detail);
@@ -43,16 +45,16 @@
}
/**
- * new a HttpRetryException by given detail message, responseCode and the
- * Location response header
+ * Creates a new {@code HttpRetryException} instance with the specified
+ * response code, the given detail message and the value of the location
+ * field from the response header.
*
* @param detail
- * detail for this exception
+ * the detail message for this exception.
* @param code
- * http response code to return
+ * the HTTP response code from target host.
* @param location
- * the error resulted from redirection, the Location header can
- * be recorded
+ * the destination URL of the redirection.
*/
public HttpRetryException(String detail, int code, String location) {
super(detail);
@@ -61,21 +63,27 @@
}
/**
- * @return the Location header recorded
+ * Gets the location value.
+ *
+ * @return the stored location from the HTTP header.
*/
public String getLocation() {
return location;
}
/**
- * @return the detail reason for this exception
+ * Gets the detail message.
+ *
+ * @return the detail message.
*/
public String getReason() {
return getMessage();
}
/**
- * @return a http response code
+ * Gets the response code.
+ *
+ * @return the HTTP response code.
*/
public int responseCode() {
return responseCode;
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/HttpURLConnection.java Wed May 6 08:33:17 2009
@@ -22,8 +22,8 @@
import org.apache.harmony.luni.util.Msg;
/**
- * This abstract subclass of <code>URLConnection</code> defines method for
- * managing HTTP connection according to the description given by RFC 2068
+ * This abstract subclass of {@code URLConnection} defines methods for managing
+ * HTTP connection according to the description given by RFC 2068.
*
* @see ContentHandler
* @see URL
@@ -35,21 +35,49 @@
private String methodTokens[] = { "GET", "DELETE", "HEAD", "OPTIONS",
"POST", "PUT", "TRACE" };
- // Request method, DEFAULT: "GET"
+ /**
+ * The HTTP request method of this {@code HttpURLConnection}. The default
+ * value is {@code "GET"}.
+ */
protected String method = "GET"; //$NON-NLS-1$
- // Response code obtained from the request
+ /**
+ * The status code of the response obtained from the HTTP request. The
+ * default value is {@code -1}.
+ * <p>
+ * <li>1xx: Informational</li>
+ * <li>2xx: Success</li>
+ * <li>3xx: Relocation/Redirection</li>
+ * <li>4xx: Client Error</li>
+ * <li>5xx: Server Error</li>
+ */
protected int responseCode = -1;
- // Response message, corresponds to the response code
+ /**
+ * The HTTP response message which corresponds to the response code.
+ */
protected String responseMessage;
+ /**
+ * Flag to define whether the protocol will automatically follow redirects
+ * or not. The default value is {@code true}.
+ */
protected boolean instanceFollowRedirects = followRedirects;
private static boolean followRedirects = true;
+ /**
+ * If the HTTP chunked encoding is enabled this parameter defines the
+ * chunk-length. Default value is {@code -1} that means the chunked encoding
+ * mode is disabled.
+ */
protected int chunkLength = -1;
+ /**
+ * If using HTTP fixed-length streaming mode this parameter defines the
+ * fixed length of content. Default value is {@code -1} that means the
+ * fixed-length streaming mode is disabled.
+ */
protected int fixedContentLength = -1;
private final static int DEFAULT_CHUNK_LENGTH = 1024;
@@ -209,7 +237,9 @@
public final static int HTTP_SEE_OTHER = 303;
/**
- * @deprecated Use HTTP_INTERNAL_ERROR
+ * Numeric status code, 500: Internal error
+ *
+ * @deprecated Use {@link #HTTP_INTERNAL_ERROR}
*/
@Deprecated
public final static int HTTP_SERVER_ERROR = 500;
@@ -240,12 +270,11 @@
public final static int HTTP_VERSION = 505;
/**
- * Constructs a <code>HttpURLConnection</code> pointing to the resource
- * specified by the <code>URL</code>.
+ * Constructs a new {@code HttpURLConnection} instance pointing to the
+ * resource specified by the {@code url}.
*
* @param url
- * the URL of this connection
- *
+ * the URL of this connection.
* @see URL
* @see URLConnection
*/
@@ -254,7 +283,7 @@
}
/**
- * Closes the connection with the HTTP server
+ * Closes the connection to the HTTP server.
*
* @see URLConnection#connect()
* @see URLConnection#connected
@@ -262,11 +291,9 @@
public abstract void disconnect();
/**
- * Answers a input stream from the server in the case of error such as the
- * requested file (txt, htm, html) is not found on the remote server.
- * <p>
- * If the content type is not what stated above,
- * <code>FileNotFoundException</code> is thrown.
+ * Returns an input stream from the server in the case of an error such as
+ * the requested file has not been found on the remote server. This stream
+ * can be used to read the data the server will send back.
*
* @return the error input stream returned by the server.
*/
@@ -275,12 +302,11 @@
}
/**
- * Answers the value of <code>followRedirects</code> which indicates if
- * this connection will follows a different URL redirected by the server. It
- * is enabled by default.
- *
- * @return The value of the flag
+ * Returns the value of {@code followRedirects} which indicates if this
+ * connection follows a different URL redirected by the server. It is
+ * enabled by default.
*
+ * @return the value of the flag.
* @see #setFollowRedirects
*/
public static boolean getFollowRedirects() {
@@ -288,12 +314,12 @@
}
/**
- * Answers the permission object (in this case, SocketPermission) with the
- * host and the port number as the target name and "resolve, connect" as the
- * action list.
- *
- * @return the permission object required for this connection
+ * Returns the permission object (in this case {@code SocketPermission})
+ * with the host and the port number as the target name and {@code
+ * "resolve, connect"} as the action list. If the port number of this URL
+ * instance is lower than {@code 0} the port will be set to {@code 80}.
*
+ * @return the permission object required for this connection.
* @throws IOException
* if an IO exception occurs during the creation of the
* permission object.
@@ -309,12 +335,11 @@
}
/**
- * Answers the request method which will be used to make the request to the
+ * Returns the request method which will be used to make the request to the
* remote HTTP server. All possible methods of this HTTP implementation is
* listed in the class definition.
*
- * @return the request method string
- *
+ * @return the request method string.
* @see #method
* @see #setRequestMethod
*/
@@ -323,13 +348,11 @@
}
/**
- * Answers the response code returned by the remote HTTP server
- *
- * @return the response code, -1 if no valid response code
+ * Returns the response code returned by the remote HTTP server.
*
+ * @return the response code, -1 if no valid response code.
* @throws IOException
* if there is an IO error during the retrieval.
- *
* @see #getResponseMessage
*/
public int getResponseCode() throws IOException {
@@ -357,15 +380,12 @@
}
/**
- * Answers the response message returned the remote HTTP server
- *
- * @return the response message. <code>null</code> if such response exists
+ * Returns the response message returned by the remote HTTP server.
*
+ * @return the response message. {@code null} if no such response exists.
* @throws IOException
- * if there is an IO error during the retrieval.
- *
+ * if there is an error during the retrieval.
* @see #getResponseCode()
- * @see IOException
*/
public String getResponseMessage() throws IOException {
if (responseMessage != null) {
@@ -378,12 +398,11 @@
/**
* Sets the flag of whether this connection will follow redirects returned
* by the remote server. This method can only be called with the permission
- * from the security manager
+ * from the security manager.
*
* @param auto
- * The value to set
- *
- * @see java.lang.SecurityManager#checkSetFactory()
+ * the value to enable or disable this option.
+ * @see SecurityManager#checkSetFactory()
*/
public static void setFollowRedirects(boolean auto) {
SecurityManager security = System.getSecurityManager();
@@ -398,12 +417,10 @@
* This method can only be called before the connection is made.
*
* @param method
- * The <code>non-null</code> string representing the method
- *
+ * the string representing the method to be used.
* @throws ProtocolException
- * Thrown when this is called after connected, or the method is
- * not supported by this HTTP implementation.
- *
+ * if this is called after connected, or the method is not
+ * supported by this HTTP implementation.
* @see #getRequestMethod()
* @see #method
*/
@@ -424,26 +441,28 @@
}
/**
- * Answers if this connection uses proxy.
+ * Returns whether this connection uses a proxy server or not.
*
- * @return true if this connection supports proxy, false otherwise.
+ * @return {@code true} if this connection passes a proxy server, false
+ * otherwise.
*/
public abstract boolean usingProxy();
/**
- * Answers if this connection follows redirects.
+ * Returns whether this connection follows redirects.
*
- * @return true if this connection follows redirects, false otherwise.
+ * @return {@code true} if this connection follows redirects, false
+ * otherwise.
*/
public boolean getInstanceFollowRedirects() {
return instanceFollowRedirects;
}
/**
- * Sets if this connection follows redirects.
+ * Sets whether this connection follows redirects.
*
* @param followRedirects
- * true if this connection should follows redirects, false
+ * {@code true} if this connection will follows redirects, false
* otherwise.
*/
public void setInstanceFollowRedirects(boolean followRedirects) {
@@ -451,16 +470,17 @@
}
/**
- * Answers the date value in the form of milliseconds since epoch
- * corresponding to the field <code>field</code>. Answers
- * <code>defaultValue</code> if no such field can be found in the response
- * header.
+ * Returns the date value in milliseconds since {@code 01.01.1970, 00:00h}
+ * corresponding to the header field {@code field}. The {@code defaultValue}
+ * will be returned if no such field can be found in the response header.
*
* @param field
- * the field in question
+ * the header field name.
* @param defaultValue
- * the default value if no field is found
- * @return milliseconds since epoch
+ * the default value to use if the specified header field wont be
+ * found.
+ * @return the header field represented in milliseconds since January 1,
+ * 1970 GMT.
*/
@Override
public long getHeaderFieldDate(String field, long defaultValue) {
@@ -468,17 +488,17 @@
}
/**
- * If length of a HTTP request body is known ahead, sets fixed length to
+ * If the length of a HTTP request body is known ahead, sets fixed length to
* enable streaming without buffering. Sets after connection will cause an
* exception.
*
- * @see <code>setChunkedStreamingMode</code>
+ * @see #setChunkedStreamingMode
* @param contentLength
- * the fixed length of the HTTP request body
+ * the fixed length of the HTTP request body.
* @throws IllegalStateException
- * if already connected or other mode already set
+ * if already connected or an other mode already set.
* @throws IllegalArgumentException
- * if contentLength is less than zero
+ * if {@code contentLength} is less than zero.
*/
public void setFixedLengthStreamingMode(int contentLength) {
if (super.connected) {
@@ -494,16 +514,16 @@
}
/**
- * If length of a HTTP request body is NOT known ahead, enable chunked
- * transfer encoding to enable streaming without buffering. Notice that not
- * all http servers support this mode. Sets after connection will cause an
+ * If the length of a HTTP request body is NOT known ahead, enable chunked
+ * transfer encoding to enable streaming with buffering. Notice that not all
+ * http servers support this mode. Sets after connection will cause an
* exception.
*
- * @see <code>setFixedLengthStreamingMode</code>
+ * @see #setFixedLengthStreamingMode
* @param chunklen
- * the length of a chunk
+ * the length of a chunk.
* @throws IllegalStateException
- * if already connected or other mode already set
+ * if already connected or an other mode already set.
*/
public void setChunkedStreamingMode(int chunklen) {
if (super.connected) {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet4Address.java Wed May 6 08:33:17 2009
@@ -19,6 +19,16 @@
import java.io.ObjectStreamException;
+/**
+ * This class represents a 32 bit long IPv4 address. The most common textual
+ * representation of an IPv4 address follows the pattern {@code b.b.b.b} where
+ * each {@code b} represents one of the four bytes. If only three parts are
+ * specified ({@code b.b.bb} ), the last part is then 16 bit long, the address
+ * represents a class B network address as <i>128.net.host</i>. A two part
+ * address ({@code b.bbb} ) allows to represent a class A network address as
+ * <i>net.host</i>. If there is only one part ({@code bbbb} ) the address is
+ * represented without any byte rearrangement.
+ */
public final class Inet4Address extends InetAddress {
private static final long serialVersionUID = 3286316764910316507L;
@@ -33,10 +43,11 @@
}
/**
- * Answers true if the address is a multicast address. Valid IPv4 multicast
- * addresses are prefixed with 1110 = 0xE
+ * Returns whether the represented address is a multicast address or not.
+ * Valid IPv4 multicast addresses are prefixed with 1110 = 0xE.
*
- * @return boolean
+ * @return {@code true} if this instance represents a multicast address,
+ * {@code false} otherwise.
*/
@Override
public boolean isMulticastAddress() {
@@ -44,9 +55,11 @@
}
/**
- * Answers if the address is the ANY Address
+ * Returns whether the represented address is the local wildcard ANY address
+ * or not.
*
- * @return boolean
+ * @return {@code true} if this instance represents the wildcard ANY
+ * address, {@code false} otherwise.
*/
@Override
public boolean isAnyLocalAddress() {
@@ -59,10 +72,11 @@
}
/**
- * Answers true if the address is a loopback address. Loopback ipv4
- * addresses are prefixed with: 011111111 = 127
+ * Returns whether the represented address is a loopback address or not.
+ * Loopback IPv4 addresses are prefixed with: 011111111 = 127.
*
- * @return boolean
+ * @return {@code true} if this instance represents a lookback address,
+ * {@code false} otherwise.
*/
@Override
public boolean isLoopbackAddress() {
@@ -70,13 +84,15 @@
}
/**
- * Answers whether this address has link-local scope.
- *
- * RFC 3484 Default Address Selection for Internet Protocol version 6 (IPv6)
- * states IPv4 auto-configuration addresses, prefix 169.254/16, IPv4
- * loopback addresses, prefix 127/8, are assigned link-local scope.
- *
- * @return boolean
+ * Returns whether this address has a link-local scope or not.
+ * <p>
+ * RFC 3484 <br>
+ * Default Address Selection for Internet Protocol Version 6 (IPv6) states
+ * IPv4 auto-configuration addresses, prefix 169.254/16, IPv4 loopback
+ * addresses, prefix 127/8, are assigned link-local scope.
+ *
+ * @return {@code true} if this instance represents a link-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isLinkLocalAddress() {
@@ -86,12 +102,15 @@
}
/**
- * Answers whether this address has site-local scope. RFC 3484 Default
- * Address Selection for Internet Protocol version 6 (IPv6) states IPv4
- * private addresses, prefixes 10/8, 172.16/12, and 192.168/16, are assigned
- * site-local scope.
+ * Returns whether this address has a site-local scope or not.
+ * <p>
+ * RFC 3484 <br>
+ * Default Address Selection for Internet Protocol Version 6 (IPv6) states
+ * IPv4 private addresses, prefixes 10/8, 172.16/12, and 192.168/16, are
+ * assigned site-local scope.
*
- * @return boolean
+ * @return {@code true} if this instance represents a site-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isSiteLocalAddress() {
@@ -102,11 +121,11 @@
}
/**
- * Answers true if an address is a global multicast address. Valid MCGlobal
- * IPv4 addresses are 224.0.1.0 - 238.255.255.255
+ * Returns whether the address is a global multicast address or not. Valid
+ * MCGlobal IPv4 addresses are 224.0.1.0 - 238.255.255.255.
*
- * @return boolean true, if the address is in the global multicast group,
- * false otherwise
+ * @return {@code true} if the address is in the global multicast group,
+ * {@code false} otherwise.
*/
@Override
public boolean isMCGlobal() {
@@ -140,10 +159,11 @@
}
/**
- * Answers false for all IPv4 addresses. There are no valid IPv4 Node-local
- * addresses
+ * Returns whether the address has a node-local scope or not. This method
+ * returns always {@code false} because there are no valid IPv4 node-local
+ * addresses.
*
- * @return boolean
+ * @return {@code false} for all IPv4 addresses.
*/
@Override
public boolean isMCNodeLocal() {
@@ -151,11 +171,12 @@
}
/**
- * Answers true if the address is a link-local address.The valid range for
- * IPv4 link-local addresses is: 224.0.0.0 to 239.0.0.255 Hence a mask of
- * 111000000000000000000000 = 0xE00000
+ * Returns whether the address is a link-local multicast address or not. The
+ * valid range for IPv4 link-local addresses is: 224.0.0.0 to 239.0.0.255
+ * Hence a mask of 111000000000000000000000 = 0xE00000.
*
- * @return boolean
+ * @return {@code true} if this instance represents a link-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isMCLinkLocal() {
@@ -163,11 +184,12 @@
}
/**
- * Answers true if the address is a site-local address.The valid range for
- * IPv4 site-local addresses is: 239.255.0.0 to 239.255.255.255 Hence a mask
- * of 11101111 11111111 = 0xEFFF.
+ * Returns whether the address is a site-local multicast address or not. The
+ * valid range for IPv4 site-local addresses is: 239.255.0.0 to
+ * 239.255.255.255 Hence a mask of 11101111 11111111 = 0xEFFF.
*
- * @return boolean
+ * @return {@code true} if this instance represents a site-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isMCSiteLocal() {
@@ -175,12 +197,13 @@
}
/**
- * Answers true if the address is a organization-local address. The valid
- * range for IPv4 org-local addresses is: 239.192.0.0 to 239.195.255.255
- * Hence masks of 11101111 11000000 to 11101111 11000011 are valid. 0xEFC0
- * to 0xEFC3
+ * Returns whether the address is a organization-local multicast address or
+ * not. The valid range for IPv4 organization-local addresses is:
+ * 239.192.0.0 to 239.195.255.255 Hence masks of 11101111 11000000 to
+ * 11101111 11000011 are valid. 0xEFC0 to 0xEFC3
*
- * @return true if org local address, false otherwise
+ * @return {@code true} if this instance represents a organization-local
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCOrgLocal() {
@@ -189,9 +212,9 @@
}
/**
- * Returns a String representation of the IP address.
+ * Returns a textual representation of this IP address.
*
- * @return Host address
+ * @return the textual representation of this host address.
*/
@Override
public String getHostAddress() {
@@ -206,9 +229,9 @@
}
/**
- * Overrides the basic hashcode function.
+ * Gets the hashcode of the represented IP address.
*
- * @return the hash code
+ * @return the appropriate hashcode value.
*/
@Override
public int hashCode() {
@@ -216,10 +239,13 @@
}
/**
- * Returns true if obj is of the same type as the IPv4 address and they have
- * the same IP address, false otherwise.
- *
- * @return true if equal and false otherwise
+ * Compares this instance with the IP address in the object {@code obj} and
+ * returns {@code true} if they are of the same type and represent the same
+ * IP address, {@code false} otherwise.
+ *
+ * @param obj
+ * the object to be tested for equality.
+ * @return {@code true} if the addresses are equal, {@code false} otherwise.
*/
@Override
public boolean equals(Object obj) {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/Inet6Address.java Wed May 6 08:33:17 2009
@@ -26,6 +26,9 @@
import org.apache.harmony.luni.util.Inet6Util;
import org.apache.harmony.luni.util.Msg;
+/**
+ * This class represents a 128 bit long IPv6 address.
+ */
public final class Inet6Address extends InetAddress {
private static final long serialVersionUID = 6880410070516793377L;
@@ -66,15 +69,15 @@
}
/**
- * Constructs an InetAddress, representing the <code>address</code> and
- * <code>hostName</code> and <code>scope_id</code>
+ * Constructs an {@code InetAddress} representing the {@code address} and
+ * {@code name} and {@code scope_id}.
*
* @param address
- * network address
+ * the network address.
* @param name
- * Name associated with the address
+ * the name associated with the address.
* @param scope_id
- * The scope id for link or site local addresses
+ * the scope id for link- or site-local addresses.
*/
Inet6Address(byte address[], String name, int scope_id) {
hostName = name;
@@ -86,18 +89,18 @@
}
/**
- * Constructs an IPv6 address according to the given <code>host</code>,
- * <code>addr</code> and <code>scope_id</code>.
+ * Constructs an IPv6 address according to the given {@code host}, {@code
+ * addr} and {@code scope_id}.
*
* @param host
- * hostname associated with the address
+ * the host name associated with the address.
* @param addr
- * network address
+ * the network address.
* @param scope_id
- * the scope id for link or site local addresses
- * @return an Inet6Address instance
+ * the scope id for link- or site-local addresses.
+ * @return the Inet6Address instance representing the IP address.
* @throws UnknownHostException
- * if the address is null or of invalid length
+ * if the address is null or has an invalid length.
*/
public static Inet6Address getByAddress(String host, byte[] addr,
int scope_id) throws UnknownHostException {
@@ -112,21 +115,21 @@
}
/**
- * Constructs an IPv6 address according to the given <code>host</code>,
- * <code>addr</code> and <code>nif</code>. <code>scope_id</code> is
- * set according to the given <code>nif</code> and the
- * <code>addr<code> type(e.g. site local or link local).
+ * Gets an IPv6 address instance according to the given {@code host},
+ * {@code addr} and {@code nif}. {@code scope_id} is set according to the
+ * given {@code nif} and the {@code addr} type (for example site-local or
+ * link-local).
*
* @param host
- * host name associated with the address
+ * the hostname associated with the address.
* @param addr
- * network address
+ * the network address.
* @param nif
- * the Network Interface that this address is associated with.
- * @return an Inet6Address instance
+ * the network interface that this address is associated with.
+ * @return the Inet6Address instance representing the IP address.
* @throws UnknownHostException
- * if the address is null or of invalid length, or the
- * interface doesn't have a numeric scope id for the given
+ * if the address is {@code null} or has an invalid length or
+ * the interface doesn't have a numeric scope id for the given
* address type.
*/
public static Inet6Address getByAddress(String host, byte[] addr,
@@ -167,9 +170,11 @@
}
/**
- * Returns true if one of following cases is true: 1. both addresses are
- * site local; 2. both addresses are link local; 3. ia is neither site local
- * nor link local;
+ * Returns {@code true} if one of following cases applies:
+ * <p>
+ * <li>1. both addresses are site local</li>
+ * <li>2. both addresses are link local</li>
+ * <li>3. {@code ia} is neither site local nor link local</li>
*/
private boolean compareLocalType(Inet6Address ia) {
if (ia.isSiteLocalAddress() && isSiteLocalAddress()) {
@@ -185,13 +190,13 @@
}
/**
- * Constructs an InetAddress, representing the <code>address</code> and
- * <code>hostName</code> and <code>scope_id</code>
+ * Constructs an {@code InetAddress} representing the {@code address} and
+ * {@code scope_id}.
*
* @param address
- * network address
+ * the network address.
* @param scope_id
- * The scope id for link or site local addresses
+ * the scope id for link- or site-local addresses.
*/
Inet6Address(byte address[], int scope_id) {
ipaddress = address;
@@ -202,13 +207,11 @@
}
/**
- * Answer true if the InetAddress is an IP multicast address.
+ * Returns whether this address is an IP multicast address or not. Valid
+ * IPv6 multicast addresses are binary prefixed with 11111111 or FF (hex).
*
- * Valid IPv6 multicast address have the binary prefixed with 11111111 or FF
- * (hex).
- *
- * @return boolean true, if the address is in the multicast group, false
- * otherwise
+ * @return {@code true} if this address is in the multicast group, {@code
+ * false} otherwise.
*/
@Override
public boolean isMulticastAddress() {
@@ -217,10 +220,11 @@
}
/**
- * Answer true if the InetAddress is the unspecified address "::".
+ * Returns whether this address is a unspecified wildcard address "::" or
+ * not.
*
- * @return boolean true, if the address is in the multicast group, false
- * otherwise
+ * @return {@code true} if this instance represents a wildcard address,
+ * {@code false} otherwise.
*/
@Override
public boolean isAnyLocalAddress() {
@@ -233,11 +237,11 @@
}
/**
- * Answer true if the InetAddress is the loopback address
- *
- * The valid IPv6 loopback address is ::1
+ * Returns whether this address is the loopback address or not. The only
+ * valid IPv6 loopback address is "::1".
*
- * @return boolean true if the address is the loopback, false otherwise
+ * @return {@code true} if this instance represents the loopback address,
+ * {@code false} otherwise.
*/
@Override
public boolean isLoopbackAddress() {
@@ -258,11 +262,11 @@
}
/**
- * Answer true if the InetAddress is a link-local address.
+ * Returns whether this address is a link-local address or not. A valid IPv6
+ * link-local address is prefixed with 1111111010.
*
- * A valid IPv6 link-local address is prefixed with 1111111010
- *
- * @return boolean true, if it is a link-local address, false otherwise
+ * @return {@code true} if this instance represents a link-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isLinkLocalAddress() {
@@ -272,11 +276,11 @@
}
/**
- * Answer true if the InetAddress is a site-local address.
- *
- * A valid IPv6 site-local address is prefixed with 1111111011
+ * Returns whether this address is a site-local address or not. A valid IPv6
+ * site-local address is prefixed with 1111111011.
*
- * @return boolean true, if it is a site-local address, false otherwise
+ * @return {@code true} if this instance represents a site-local address,
+ * {@code false} otherwise.
*/
@Override
public boolean isSiteLocalAddress() {
@@ -286,12 +290,11 @@
}
/**
- * Answer true if the InetAddress is a global multicast address.
+ * Returns whether this address is a global multicast address or not. A
+ * valid IPv6 global multicast address is 11111111xxxx1110 or FF0E hex.
*
- * A valid IPv6 global multicast address is 11111111xxxx1110 (i.e. FF0E)
- *
- * @return boolean true, if it is a global multicast address, false
- * otherwise
+ * @return {@code true} if this instance represents a global multicast
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCGlobal() {
@@ -301,13 +304,12 @@
}
/**
- * Answer true if the InetAddress is a node-local multicast address.
- *
- * A valid IPv6 node-local multicast address is prefixed with
- * 11111111xxxx0001
+ * Returns whether this address is a node-local multicast address or not. A
+ * valid IPv6 node-local multicast address is prefixed with
+ * 11111111xxxx0001.
*
- * @return boolean true, if it is a node-local multicast address, false
- * otherwise
+ * @return {@code true} if this instance represents a node-local multicast
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCNodeLocal() {
@@ -317,13 +319,12 @@
}
/**
- * Answer true if the InetAddress is a link-local multicast address.
+ * Returns whether this address is a link-local multicast address or not. A
+ * valid IPv6 link-local multicast address is prefixed with
+ * 11111111xxxx0010.
*
- * A valid IPv6 link-local multicast address is prefixed with
- * 11111111xxxx0010
- *
- * @return boolean true, if it is a link-local multicast address, false
- * otherwise
+ * @return {@code true} if this instance represents a link-local multicast
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCLinkLocal() {
@@ -333,13 +334,12 @@
}
/**
- * Answer true if the InetAddress is a site-local multicast address.
- *
- * A valid IPv6 site-local multicast address is prefixed with
- * 11111111xxxx0101
+ * Returns whether this address is a site-local multicast address or not. A
+ * valid IPv6 site-local multicast address is prefixed with
+ * 11111111xxxx0101.
*
- * @return boolean true, if it is a site-local multicast address, false
- * otherwise
+ * @return {@code true} if this instance represents a site-local multicast
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCSiteLocal() {
@@ -349,13 +349,12 @@
}
/**
- * Answer true if the InetAddress is a org-local multicast address.
+ * Returns whether this address is a organization-local multicast address or
+ * not. A valid IPv6 org-local multicast address is prefixed with
+ * 11111111xxxx1000.
*
- * A valid IPv6 org-local multicast address is prefixed with
- * 11111111xxxx1000
- *
- * @return boolean true, if it is a org-local multicast address, false
- * otherwise
+ * @return {@code true} if this instance represents a org-local multicast
+ * address, {@code false} otherwise.
*/
@Override
public boolean isMCOrgLocal() {
@@ -364,16 +363,22 @@
return (ipaddress[0] == -1) && (ipaddress[1] & 15) == 8;
}
+ /**
+ * Gets the textual representation of this IP address.
+ *
+ * @return the as a dotted string formatted IP address.
+ */
@Override
public String getHostAddress() {
return Inet6Util.createIPAddrStringFromByteArray(ipaddress);
}
/**
- * Returns the <code>scope id</code> of this address if it is associated
- * with an interface. Otherwise returns zero.
+ * Gets the scope id as a number if this address is linked to an interface.
+ * Otherwise returns {@code 0}.
*
- * @return the scope_id.
+ * @return the scope_id of this address or 0 when not linked with an
+ * interface.
*/
public int getScopeId() {
if (scope_id_set) {
@@ -383,10 +388,10 @@
}
/**
- * Returns the network interface if this address is instanced with a scoped
- * network interface. Otherwise returns null.
+ * Gets the network interface if this address is instanced with a scoped
+ * network interface. Otherwise returns {@code null}.
*
- * @return the scoped network interface.
+ * @return the scoped network interface of this address.
*/
public NetworkInterface getScopedInterface() {
if (scope_ifname_set) {
@@ -396,9 +401,9 @@
}
/**
- * Returns the hashcode of the receiver.
+ * Gets the hashcode of the represented IP address.
*
- * @return the hashcode
+ * @return the appropriate hashcode value.
*/
@Override
public int hashCode() {
@@ -407,12 +412,14 @@
}
/**
- * Returns true if obj is of the same type as the IPv6 address and they have
- * the same IP address, false otherwise. the scope id does not seem to be
- * part of the comparison
- *
- * @return String
- *
+ * Compares this instance with the IP address in the object {@code obj} and
+ * returns {@code true} if they are of the same type and represent the same
+ * IP address, {@code false} otherwise. The scope id does not seem to be
+ * part of the comparison.
+ *
+ * @param obj
+ * the object to be tested for equality.
+ * @return {@code true} if the addresses are equal, {@code false} otherwise.
*/
@Override
public boolean equals(Object obj) {
@@ -420,8 +427,12 @@
}
/**
- * An IPv4 compatible address is prefixed with 96 bits of 0's. The last
- * 32-bits are varied corresponding with the 32-bit IPv4 address space.
+ * Returns whether this address is IPv4 compatible or not. An IPv4
+ * compatible address is prefixed with 96 bits of 0's. The last 32-bits are
+ * varied corresponding with the 32-bit IPv4 address space.
+ *
+ * @return {@code true} if this instance represents an IPv4 compatible
+ * address, {@code false} otherwise.
*/
public boolean isIPv4CompatibleAddress() {
for (int i = 0; i < 12; i++) {
@@ -468,10 +479,10 @@
}
/**
- * Answers a string containing a concise, human-readable description of the
- * address.
+ * Returns a string containing a concise, human-readable description of this
+ * IP address.
*
- * @return String the description, as host/address
+ * @return the description, as host/address.
*/
@Override
public String toString() {
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/InetAddress.java Wed May 6 08:33:17 2009
@@ -37,9 +37,10 @@
import org.apache.harmony.luni.util.PriviAction;
/**
- * The Internet Protocol (IP) address class. This class encapsulates an IP
- * address and provides name and reverse name resolution functions. The address
- * is stored in network order, but as a signed (rather than unsigned) integer.
+ * The Internet Protocol (IP) address representation class. This class
+ * encapsulates an IP address and provides name and reverse name resolution
+ * functions. The address is stored in network order, but as a signed (rather
+ * than unsigned) integer.
*/
public class InetAddress extends Object implements Serializable {
@@ -88,11 +89,11 @@
}
/**
- * Constructs an InetAddress, representing the <code>address</code> and
- * <code>hostName</code>.
- *
+ * Constructs an {@code InetAddress}, representing the {@code address} and
+ * {@code hostName}.
+ *
* @param address
- * network address
+ * the network address.
*/
InetAddress(byte[] address) {
super();
@@ -100,11 +101,11 @@
}
/**
- * Constructs an InetAddress, representing the <code>address</code> and
- * <code>hostName</code>.
+ * Constructs an {@code InetAddress}, representing the {@code address} and
+ * {@code hostName}.
*
* @param address
- * network address
+ * the network address.
*/
InetAddress(byte[] address, String hostName) {
super();
@@ -117,11 +118,13 @@
}
/**
- * Compares this <code>InetAddress</code> against the specified object.
+ * Compares this {@code InetAddress} instance against the specified address
+ * in {@code obj}. Two addresses are equal if their address byte arrays have
+ * the same length and if the bytes in the arrays are equal.
*
* @param obj
- * the object to be tested for equality
- * @return boolean true, if the objects are equal
+ * the object to be tested for equality.
+ * @return {@code true} if both objects are equal, {@code false} otherwise.
*/
@Override
public boolean equals(Object obj) {
@@ -143,28 +146,29 @@
}
/**
- * Returns the IP address of this <code>InetAddress</code> as an array.
- * The elements are in network order (the highest order address byte is in
- * the zero-th element).
+ * Returns the IP address represented by this {@code InetAddress} instance
+ * as a byte array. The elements are in network order (the highest order
+ * address byte is in the zeroth element).
*
- * @return byte[] the address as a byte array
+ * @return the address in form of a byte array.
*/
public byte[] getAddress() {
return ipaddress.clone();
}
/**
- * Answer the IP addresses of a named host. The host name may either be a
- * machine name or a dotted string IP address. If the host name is empty or
- * null, an UnknownHostException is thrown. If the host name is a dotted IP
- * string, an array with the corresponding single InetAddress is returned.
+ * Gets all IP addresses associated with the given {@code host} identified
+ * by name or IP address in dot-notation. The IP address is resolved by the
+ * configured name service. If the host name is empty or {@code null} an
+ * {@code UnknownHostException} is thrown. If the host name is a dotted IP
+ * address string an array with the corresponding single {@code InetAddress}
+ * is returned.
*
* @param host
- * the hostName to be resolved to an address
- *
- * @return InetAddress[] an array of addresses for the host
+ * the host's name or IP to be resolved to an address.
+ * @return the array of addresses associated with the specified host.
* @throws UnknownHostException
- * if the address lookup fails
+ * if the address lookup fails.
*/
public static InetAddress[] getAllByName(String host)
throws UnknownHostException {
@@ -231,16 +235,17 @@
}
/**
- * Answers the address of a host, given a host string name. The host string
- * may be either a machine name or a dotted string IP address. If the
- * latter, the hostName field will be determined upon demand.
+ * Returns the address of a host according to the given host string name
+ * {@code host}. The host string may be either a machine name or a dotted
+ * string IP address. If the latter, the {@code hostName} field is
+ * determined upon demand. {@code host} can be {@code null} which means that
+ * an address of the loopback interface is returned.
*
* @param host
- * the hostName to be resolved to an address
- * @return InetAddress the InetAddress representing the host
- *
+ * the hostName to be resolved to an address or {@code null}.
+ * @return the {@code InetAddress} instance representing the host.
* @throws UnknownHostException
- * if the address lookup fails
+ * if the address lookup fails.
*/
public static InetAddress getByName(String host)
throws UnknownHostException {
@@ -263,18 +268,21 @@
}
/**
- * Answer the dotted string IP address representing this address.
+ * Gets the textual representation of this IP address.
*
- * @return String the corresponding dotted string IP address
+ * @return the textual representation of this host address in form of a
+ * dotted string.
*/
public String getHostAddress() {
return inetNtoaImpl(bytesToInt(ipaddress, 0));
}
/**
- * Answer the host name.
+ * Gets the host name of this IP address. If the IP address could not be
+ * resolved, the textual representation in a dotted-quad-notation is
+ * returned.
*
- * @return String the corresponding string name
+ * @return the corresponding string name of this IP address.
*/
public String getHostName() {
try {
@@ -309,9 +317,12 @@
}
/**
- * Answers canonical name for the host associated with the internet address
+ * Gets the fully qualified domain name for the host associated with this IP
+ * address. If a security manager is set, it is checked if the method caller
+ * is allowed to get the hostname. Otherwise, the textual representation in
+ * a dotted-quad-notation is returned.
*
- * @return String string containing the host name
+ * @return the fully qualified domain name of this IP address.
*/
public String getCanonicalHostName() {
String canonicalName;
@@ -340,12 +351,13 @@
}
/**
- * Answer the local host, if allowed by the security policy. Otherwise,
- * answer the loopback address which allows this machine to be contacted.
- *
- * @return InetAddress the InetAddress representing the local host
+ * Gets the local host address if the security policy allows this.
+ * Otherwise, gets the loopback address which allows this machine to be
+ * contacted.
+ *
+ * @return the {@code InetAddress} representing the local host.
* @throws UnknownHostException
- * if the address lookup fails
+ * if the address lookup fails.
*/
public static InetAddress getLocalHost() throws UnknownHostException {
String host = getHostNameImpl();
@@ -361,9 +373,9 @@
}
/**
- * Answer a hashcode for this IP address.
+ * Gets the hashcode of the represented IP address.
*
- * @return int the hashcode
+ * @return the appropriate hashcode value.
*/
@Override
public int hashCode() {
@@ -371,9 +383,10 @@
}
/**
- * Answer true if the InetAddress is an IP multicast address.
+ * Returns whether this address is an IP multicast address or not.
*
- * @return boolean true, if the address is in the multicast group
+ * @return {@code true} if this address is in the multicast group, {@code
+ * false} otherwise.
*/
public boolean isMulticastAddress() {
return ((ipaddress[0] & 255) >>> 4) == 0xE;
@@ -447,9 +460,9 @@
* Query the IP stack for the host address. The host is in address form.
*
* @param addr
- * the host address to lookup
+ * the host address to lookup.
* @throws UnknownHostException
- * if an error occurs during lookup
+ * if an error occurs during lookup.
*/
static native InetAddress getHostByAddrImpl(byte[] addr)
throws UnknownHostException;
@@ -460,7 +473,7 @@
}
/**
- * Convert a string containing an Ipv4 Internet Protocol dotted address into
+ * Convert a string containing an IPv4 Internet Protocol dotted address into
* a binary address. Note, the special case of '255.255.255.255' throws an
* exception, so this value should not be used as an argument. See also
* inetAddr(String).
@@ -481,7 +494,6 @@
* @param preferIPv6Addresses
* address preference if underlying platform is V4/V6
* @return InetAddress the host address
- *
* @throws UnknownHostException
* if an error occurs during lookup
*/
@@ -489,9 +501,9 @@
boolean preferIPv6Address) throws UnknownHostException;
/**
- * Query the IP stack for the host machine name.
+ * Gets the host name of the system.
*
- * @return String the host machine name
+ * @return String the system hostname
*/
static native String getHostNameImpl();
@@ -506,10 +518,10 @@
}
/**
- * Answers a string containing a concise, human-readable description of the
- * address.
+ * Returns a string containing a concise, human-readable description of this
+ * IP address.
*
- * @return String the description, as host/address
+ * @return the description, as host/address.
*/
@Override
public String toString() {
@@ -603,7 +615,7 @@
}
/**
- * Answer true if the string is a host name, false if it is an IP Address.
+ * Returns true if the string is a host name, false if it is an IP Address.
*/
private static boolean isHostName(String value) {
return !(Inet6Util.isValidIPV4Address(value) || Inet6Util
@@ -611,163 +623,186 @@
}
/**
- * Answer true if the address is a loop back address. Valid IPv4 loopback
- * addresses are 127.d.d.d Valid IPv6 loopback address is ::1
+ * Returns whether this address is a loopback address or not. This
+ * implementation returns always {@code false}. Valid IPv4 loopback
+ * addresses are 127.d.d.d The only valid IPv6 loopback address is ::1.
*
- * @return boolean
+ * @return {@code true} if this instance represents a loopback address,
+ * {@code false} otherwise.
*/
public boolean isLoopbackAddress() {
return false;
}
/**
- * Answers true if the address is a link local address.
- *
- * Valid IPv6 link local addresses are FE80::0 through to
- * FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
- *
- * There are no valid IPv4 link local addresses.
- *
- * @return boolean
+ * Returns whether this address is a link-local address or not. This
+ * implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 link-local addresses are FE80::0 through to
+ * FEBF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.
+ * <p>
+ * There are no valid IPv4 link-local addresses.
+ *
+ * @return {@code true} if this instance represents a link-local address,
+ * {@code false} otherwise.
*/
public boolean isLinkLocalAddress() {
return false;
}
/**
- * Answers true if the address is a site local address.
+ * Returns whether this address is a site-local address or not. This
+ * implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 site-local addresses are FEC0::0 through to
+ * FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF.
+ * <p>
+ * There are no valid IPv4 site-local addresses.
*
- * Valid IPv6 link local addresses are FEC0::0 through to
- * FEFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
- *
- * There are no valid IPv4 site local addresses.
- *
- * @return boolean
+ * @return {@code true} if this instance represents a site-local address,
+ * {@code false} otherwise.
*/
public boolean isSiteLocalAddress() {
return false;
}
/**
- * Answers true if the address is a global multicast address.
- *
- * Valid IPv6 link global multicast addresses are FFxE:/112 where x is a set
+ * Returns whether this address is a global multicast address or not. This
+ * implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 link-global multicast addresses are FFxE:/112 where x is a set
* of flags, and the additional 112 bits make up the global multicast
- * address space
- *
+ * address space.
+ * <p>
* Valid IPv4 global multicast addresses are between: 224.0.1.0 to
- * 238.255.255.255
- *
- * @return boolean
+ * 238.255.255.255.
+ *
+ * @return {@code true} if this instance represents a global multicast
+ * address, {@code false} otherwise.
*/
public boolean isMCGlobal() {
return false;
}
/**
- * Answers true if the address is a node local multicast address.
- *
- * Valid IPv6 node local multicast addresses are FFx1:/112 where x is a set
- * of flags, and the additional 112 bits make up the node local multicast
- * address space
- *
- * There are no valid IPv4 node local multicast addresses.
- *
- * @return boolean
+ * Returns whether this address is a node-local multicast address or not.
+ * This implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 node-local multicast addresses are FFx1:/112 where x is a set
+ * of flags, and the additional 112 bits make up the node-local multicast
+ * address space.
+ * <p>
+ * There are no valid IPv4 node-local multicast addresses.
+ *
+ * @return {@code true} if this instance represents a node-local multicast
+ * address, {@code false} otherwise.
*/
public boolean isMCNodeLocal() {
return false;
}
/**
- * Answers true if the address is a link local multicast address.
- *
- * Valid IPv6 link local multicast addresses are FFx2:/112 where x is a set
- * of flags, and the additional 112 bits make up the node local multicast
- * address space
- *
+ * Returns whether this address is a link-local multicast address or not.
+ * This implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 link-local multicast addresses are FFx2:/112 where x is a set
+ * of flags, and the additional 112 bits make up the link-local multicast
+ * address space.
+ * <p>
* Valid IPv4 link-local addresses are between: 224.0.0.0 to 224.0.0.255
- *
- * @return boolean
+ *
+ * @return {@code true} if this instance represents a link-local multicast
+ * address, {@code false} otherwise.
*/
public boolean isMCLinkLocal() {
return false;
}
/**
- * Answers true if the address is a site local multicast address.
- *
- * Valid IPv6 site local multicast addresses are FFx5:/112 where x is a set
- * of flags, and the additional 112 bits make up the node local multicast
- * address space
- *
+ * Returns whether this address is a site-local multicast address or not.
+ * This implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 site-local multicast addresses are FFx5:/112 where x is a set
+ * of flags, and the additional 112 bits make up the site-local multicast
+ * address space.
+ * <p>
* Valid IPv4 site-local addresses are between: 239.252.0.0 to
* 239.255.255.255
- *
- * @return boolean
+ *
+ * @return {@code true} if this instance represents a site-local multicast
+ * address, {@code false} otherwise.
*/
public boolean isMCSiteLocal() {
return false;
}
/**
- * Answers true if the address is a organization local multicast address.
- *
- * Valid IPv6 organization local multicast addresses are FFx8:/112 where x
- * is a set of flags, and the additional 112 bits make up the node local
- * multicast address space
- *
+ * Returns whether this address is a organization-local multicast address or
+ * not. This implementation returns always {@code false}.
+ * <p>
+ * Valid IPv6 organization-local multicast addresses are FFx8:/112 where x
+ * is a set of flags, and the additional 112 bits make up the
+ * organization-local multicast address space.
+ * <p>
* Valid IPv4 organization-local addresses are between: 239.192.0.0 to
* 239.251.255.255
- *
- * @return boolean
+ *
+ * @return {@code true} if this instance represents a organization-local
+ * multicast address, {@code false} otherwise.
*/
public boolean isMCOrgLocal() {
return false;
}
/**
- * Method isAnyLocalAddress.
+ * Returns whether this is a wildcard address or not. This implementation
+ * returns always {@code false}.
*
- * @return boolean
+ * @return {@code true} if this instance represents a wildcard address,
+ * {@code false} otherwise.
*/
public boolean isAnyLocalAddress() {
return false;
}
/**
- * Tries to see if the InetAddress is reachable. This method first tries to
- * use ICMP(ICMP ECHO REQUEST). When first step fails, the TCP connection on
- * port 7 (Echo) shall be lauched.
+ * Tries to reach this {@code InetAddress}. This method first tries to use
+ * ICMP <i>(ICMP ECHO REQUEST)</i>. When first step fails, a TCP connection
+ * on port 7 (Echo) of the remote host is established.
*
* @param timeout
- * timeout in milliseconds
- * @return true if address is reachable
+ * timeout in milliseconds before the test fails if no connection
+ * could be established.
+ * @return {@code true} if this address is reachable, {@code false}
+ * otherwise.
* @throws IOException
- * if I/O operation meets error
+ * if an error occurs during an I/O operation.
* @throws IllegalArgumentException
- * if timeout is less than zero
+ * if timeout is less than zero.
*/
public boolean isReachable(int timeout) throws IOException {
return isReachable(null, 0, timeout);
}
/**
- * Tries to see if the InetAddress is reachable. This method first tries to
- * use ICMP(ICMP ECHO REQUEST). When first step fails, the TCP connection on
- * port 7 (Echo) shall be lauched.
+ * Tries to reach this {@code InetAddress}. This method first tries to use
+ * ICMP <i>(ICMP ECHO REQUEST)</i>. When first step fails, a TCP connection
+ * on port 7 (Echo) of the remote host is established.
*
* @param netif
- * the network interface through which to connect
+ * the network interface on which to connection should be
+ * established.
* @param ttl
- * max hops to live
+ * the maximum count of hops (time-to-live).
* @param timeout
- * timeout in milliseconds
- * @return true if address is reachable
+ * timeout in milliseconds before the test fails if no connection
+ * could be established.
+ * @return {@code true} if this address is reachable, {@code false}
+ * otherwise.
* @throws IOException
- * if I/O operation meets error
+ * if an error occurs during an I/O operation.
* @throws IllegalArgumentException
- * if ttl or timeout is less than zero
+ * if ttl or timeout is less than zero.
*/
public boolean isReachable(NetworkInterface netif, final int ttl,
final int timeout) throws IOException {
@@ -934,19 +969,20 @@
}
/**
- * Answers the InetAddress corresponding to the array of bytes. In the case
- * of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16
- * bytes. If not, an UnknownHostException is thrown.
- *
+ * Returns the {@code InetAddress} corresponding to the array of bytes. In
+ * the case of an IPv4 address there must be exactly 4 bytes and for IPv6
+ * exactly 16 bytes. If not, an {@code UnknownHostException} is thrown.
+ * <p>
* The IP address is not validated by a name service.
- *
- * The high order byte is <code>ipAddress[0]</code>.
- *
+ * <p>
+ * The high order byte is {@code ipAddress[0]}.
+ *
* @param ipAddress
- * either a 4 (IPv4) or 16 (IPv6) byte array
- * @return the InetAddress
- *
+ * is either a 4 (IPv4) or 16 (IPv6) byte long array.
+ * @return an {@code InetAddress} instance representing the given IP address
+ * {@code ipAddress}.
* @throws UnknownHostException
+ * if the given byte array has no valid length.
*/
public static InetAddress getByAddress(byte[] ipAddress)
throws UnknownHostException {
@@ -956,21 +992,18 @@
}
/**
- * Answers the InetAddress corresponding to the array of bytes. In the case
- * of an IPv4 address there must be exactly 4 bytes and for IPv6 exactly 16
- * bytes. If not, an UnknownHostException is thrown.
- *
- * The IP address is not validated by a name service.
- *
- * The high order byte is <code>ipAddress[0]</code>.
+ * Returns the {@code InetAddress} corresponding to the array of bytes. In
+ * the case of an IPv4 address there must be exactly 4 bytes and for IPv6
+ * exactly 16 bytes. If not, an {@code UnknownHostException} is thrown. The
+ * IP address is not validated by a name service. The high order byte is
+ * {@code ipAddress[0]}.
*
* @param ipAddress
- * either a 4 (IPv4) or 16 (IPv6) byte array
+ * either a 4 (IPv4) or 16 (IPv6) byte array.
* @param scope_id
* the scope id for an IPV6 scoped address. If not a scoped
- * address just pass in 0
+ * address just pass in 0.
* @return the InetAddress
- *
* @throws UnknownHostException
*/
static InetAddress getByAddress(byte[] ipAddress, int scope_id)
@@ -1021,25 +1054,26 @@
}
/**
- * Answers the InetAddress corresponding to the array of bytes, and the
- * given hostname. In the case of an IPv4 address there must be exactly 4
- * bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException is
- * thrown.
- *
+ * Returns the {@code InetAddress} corresponding to the array of bytes, and
+ * the given hostname. In the case of an IPv4 address there must be exactly
+ * 4 bytes and for IPv6 exactly 16 bytes. If not, an {@code
+ * UnknownHostException} will be thrown.
+ * <p>
* The host name and IP address are not validated.
- *
+ * <p>
* The hostname either be a machine alias or a valid IPv6 or IPv4 address
* format.
- *
- * The high order byte is <code>ipAddress[0]</code>.
- *
+ * <p>
+ * The high order byte is {@code ipAddress[0]}.
+ *
* @param hostName
- * string representation of hostname or ip address
+ * the string representation of hostname or IP address.
* @param ipAddress
- * either a 4 (IPv4) or 16 (IPv6) byte array
- * @return the InetAddress
- *
+ * either a 4 (IPv4) or 16 (IPv6) byte long array.
+ * @return an {@code InetAddress} instance representing the given IP address
+ * and hostname.
* @throws UnknownHostException
+ * if the given byte array has no valid length.
*/
public static InetAddress getByAddress(String hostName, byte[] ipAddress)
throws UnknownHostException {
@@ -1049,27 +1083,21 @@
}
/**
- * Answers the InetAddress corresponding to the array of bytes, and the
- * given hostname. In the case of an IPv4 address there must be exactly 4
- * bytes and for IPv6 exactly 16 bytes. If not, an UnknownHostException is
- * thrown.
- *
- * The host name and IP address are not validated.
- *
- * The hostname either be a machine alias or a valid IPv6 or IPv4 address
- * format.
- *
- * The high order byte is <code>ipAddress[0]</code>.
+ * Returns the {@code InetAddress} corresponding to the array of bytes, and
+ * the given hostname. In the case of an IPv4 address there must be exactly
+ * 4 bytes and for IPv6 exactly 16 bytes. If not, an {@code
+ * UnknownHostException} is thrown. The host name and IP address are not
+ * validated. The hostname either be a machine alias or a valid IPv6 or IPv4
+ * address format. The high order byte is {@code ipAddress[0]}.
*
* @param hostName
- * string representation of hostname or IP address
+ * string representation of hostname or IP address.
* @param ipAddress
- * either a 4 (IPv4) or 16 (IPv6) byte array
+ * either a 4 (IPv4) or 16 (IPv6) byte array.
* @param scope_id
* the scope id for a scoped address. If not a scoped address
- * just pass in 0
+ * just pass in 0.
* @return the InetAddress
- *
* @throws UnknownHostException
*/
static InetAddress getByAddressInternal(String hostName, byte[] ipAddress,
@@ -1140,8 +1168,8 @@
}
/**
- * Creates an InetAddress based on an ipAddressString. No error handling is
- * performed here.
+ * Creates an InetAddress based on the {@code ipAddressString}. No error
+ * handling is performed here.
*/
static InetAddress createHostNameFromIPAddress(String ipAddressString)
throws UnknownHostException {