harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [6/6] - /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
Date Wed, 06 May 2009 08:33:22 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLConnection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLConnection.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLConnection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLConnection.java Wed May  6 08:33:17 2009
@@ -34,12 +34,16 @@
 import org.apache.harmony.luni.util.PriviAction;
 
 /**
- * The URLConnection class is responsible for establishing a connection to an
- * URL for a given protocol. The correct URLConnection subclass to call is
- * determined by <code>URLStreamHandler.openConnection()</code>.
+ * Concrete implementations of the abstract {@code URLConnection} class provide
+ * a communication link to a URL for exchanging data with a specific protocol
+ * type. A {@code URLConnection} can only be set up after the instantiation but
+ * before connecting to the remote resource.
  */
 public abstract class URLConnection {
 
+    /**
+     * The URL which represents the remote target of this {@code URLConnection}.
+     */
     protected URL url;
 
     private String contentType;
@@ -52,16 +56,39 @@
 
     private long lastModified = -1;
 
+    /**
+     * The data must be modified more recently than this time in milliseconds
+     * since January 1, 1970, GMT to be transmitted.
+     */
     protected long ifModifiedSince;
 
+    /**
+     * Specifies whether the using of caches is enabled or the data has to be
+     * recent for every request.
+     */
     protected boolean useCaches = defaultUseCaches;
 
+    /**
+     * Specifies whether this {@code URLConnection} is already connected to the
+     * remote resource. If this field is set to {@code true} the flags for
+     * setting up the connection are not changeable anymore.
+     */
     protected boolean connected;
 
+    /**
+     * Specifies whether this {@code URLConnection} allows sending data.
+     */
     protected boolean doOutput;
 
+    /**
+     * Specifies whether this {@code URLConnection} allows receiving data.
+     */
     protected boolean doInput = true;
 
+    /**
+     * Specifies whether this {@code URLConnection} allows user interaction as
+     * it is needed for authentication purposes.
+     */
     protected boolean allowUserInteraction = defaultAllowUserInteraction;
 
     private static ContentHandlerFactory contentHandlerFactory;
@@ -71,7 +98,7 @@
     private int connectTimeout = 0;
 
     /**
-     * Cache for storing Content handler
+     * Cache for storing content handler
      */
     static Hashtable<String, Object> contentHandlers = new Hashtable<String, Object>();
 
@@ -82,34 +109,31 @@
     private static FileNameMap fileNameMap;
 
     /**
-     * Creates a URLConnection pointing to the resource specified by the
-     * <code>url</code>
+     * Creates a new {@code URLConnection} instance pointing to the resource
+     * specified by the given URL.
+     *
+     * @param url
+     *            the URL which represents the resource this {@code
+     *            URLConnection} will point to.
      */
     protected URLConnection(URL url) {
         this.url = url;
     }
 
     /**
-     * Establishes the connection to the resource specified by this
-     * <code>URL</code> with this <code>method</code>, along with other
-     * options that can only be set before this connection is made.
+     * Establishes the connection to the earlier configured resource. The
+     * connection can only be set up before this method has been called.
      * 
      * @throws IOException
-     *             If an error occurs while connecting
-     * 
-     * @see java.io.IOException
-     * @see URLStreamHandler
+     *             if an error occurs while connecting to the resource.
      */
     public abstract void connect() throws IOException;
 
     /**
-     * Answers the value of <code>allowUserInteraction</code> which indicates
-     * if this connection allows user interaction
+     * Gets the option value which indicates whether user interaction is allowed
+     * on this {@code URLConnection}.
      * 
-     * @return the value of the flag
-     * 
-     * @see #getDefaultRequestProperty
-     * @see #setDefaultRequestProperty
+     * @return the value of the option {@code allowUserInteraction}.
      * @see #allowUserInteraction
      */
     public boolean getAllowUserInteraction() {
@@ -117,21 +141,16 @@
     }
 
     /**
-     * Answers the object pointed to by this <code>URL</code>. It first
-     * attempts to get the content type from <code>getContentType()</code>,
-     * which looks for the response header field "Content-Type". If none is
-     * found, it will guess the content type from the filename extension. If
-     * that fails, it will guess by inspecting the stream.
-     * 
-     * @return a non-null object
+     * Gets an object representing the content of the resource this {@code
+     * URLConnection} is connected to. First, it attempts to get the content
+     * type from the method {@code getContentType()} which looks at the response
+     * header field "Content-Type". If none is found it will guess the content
+     * type from the filename extension. If that fails the stream itself will be
+     * used to guess the content type.
      * 
+     * @return the content representing object.
      * @throws IOException
-     *             if an IO error occurred
-     * 
-     * @see ContentHandler
-     * @see ContentHandlerFactory
-     * @see IOException
-     * @see #setContentHandlerFactory
+     *             if an error occurs obtaining the content.
      */
     public Object getContent() throws java.io.IOException {
         if (!connected) {
@@ -150,19 +169,20 @@
     }
 
     /**
-     * Answers the object pointed to by this <code>URL</code>. It first
-     * attempts to get the content type from <code>getContentType()</code>,
-     * which looks for the response header field "Content-Type". If none is
-     * found, it will guess the content type from the filename extension. If
-     * that fails, it will guess by inspecting the stream.
+     * Gets an object representing the content of the resource this {@code
+     * URLConnection} is connected to. First, it attempts to get the content
+     * type from the method {@code getContentType()} which looks at the response
+     * header field "Content-Type". If none is found it will guess the content
+     * type from the filename extension. If that fails the stream itself will be
+     * used to guess the content type. The content type must match with one of
+     * the list {@code types}.
      * 
      * @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.
-     * 
+     *            the list of acceptable content types.
+     * @return the content representing object or {@code null} if the content
+     *         type does not match with one of the specified types.
      * @throws IOException
-     *             If an error occurred obtaining the content.
+     *             if an error occurs obtaining the content.
      */
     // Param is not generic in spec
     @SuppressWarnings("unchecked")
@@ -183,20 +203,18 @@
     }
 
     /**
-     * Answers the Content encoding type of the response body, null if no such
-     * field is found in the header response.
-     * 
-     * @return The content encoding type
+     * Gets the content encoding type specified by the response header field
+     * {@code content-encoding} or {@code null} if this field is not set.
      * 
-     * @see #getContentType
+     * @return the value of the response header field {@code content-encoding}.
      */
     public String getContentEncoding() {
         return getHeaderField("Content-Encoding"); //$NON-NLS-1$
     }
 
     /**
-     * Answers the specific ContentHandler that will handle the type
-     * <code>contentType</code>
+     * Returns the specific ContentHandler that will handle the type {@code
+     * contentType}.
      * 
      * @param type
      *            The type that needs to be handled
@@ -271,55 +289,41 @@
     }
 
     /**
-     * Answers the length of the content or body in the response header in
-     * bytes. Answer -1 if <code> Content-Length </code> cannot be found in the
-     * response header.
+     * Gets the content length in bytes specified by the response header field
+     * {@code content-length} or {@code -1} if this field is not set.
      * 
-     * @return The length of the content
-     * 
-     * @see #getContentType
+     * @return the value of the response header field {@code content-length}.
      */
     public int getContentLength() {
         return getHeaderFieldInt("Content-Length", -1); //$NON-NLS-1$
     }
 
     /**
-     * Answers the type of the content. Answers <code> null </code> if there's
-     * no such field.
-     * 
-     * @return The type of the content
+     * Gets the MIME-type of the content specified by the response header field
+     * {@code content-type} or {@code null} if type is unknown.
      * 
-     * @see #guessContentTypeFromName
-     * @see #guessContentTypeFromStream
+     * @return the value of the response header field {@code content-type}.
      */
     public String getContentType() {
         return getHeaderField("Content-Type"); //$NON-NLS-1$
     }
 
     /**
-     * Answers the date in milliseconds since epoch when this response header
-     * was created, or 0 if the field <code>Date</code> is not found in the
-     * header.
-     * 
-     * @return Date in millisecond since epoch
-     * 
-     * @see #getExpiration
-     * @see #getLastModified
-     * @see java.util.Date
+     * Gets the timestamp when this response has been sent as a date in
+     * milliseconds since January 1, 1970 GMT or {@code 0} if this timestamp is
+     * unknown.
      * 
+     * @return the sending timestamp of the current response.
      */
     public long getDate() {
         return getHeaderFieldDate("Date", 0); //$NON-NLS-1$
     }
 
     /**
-     * Answers whether this connection allow user interaction by default.
+     * Gets the default setting whether this connection allows user interaction.
      * 
-     * @return the value of <code>defaultAllowUserInteraction</code>
-     * 
-     * @see #getAllowUserInteraction
-     * @see #setDefaultAllowUserInteraction
-     * @see #setAllowUserInteraction
+     * @return the value of the default setting {@code
+     *         defaultAllowUserInteraction}.
      * @see #allowUserInteraction
      */
     public static boolean getDefaultAllowUserInteraction() {
@@ -327,14 +331,14 @@
     }
 
     /**
-     * Answers the default value for the field specified by <code>field</code>,
-     * null if there's no such field.
+     * Gets the default value for the specified request {@code field} or {@code
+     * null} if the field could not be found. The current implementation of this
+     * method returns always {@code null}.
      * 
      * @param field
-     *            the field to get the request property for
-     * @return the field to be looked up
-     * 
-     * @deprecated Use getRequestProperty().
+     *            the request field whose default value shall be returned.
+     * @return the default value for the given field.
+     * @deprecated Use {@link #getRequestProperty}
      */
     @Deprecated
     public static String getDefaultRequestProperty(String field) {
@@ -342,13 +346,9 @@
     }
 
     /**
-     * Answers whether this connection use caches by default.
+     * Gets the default setting whether this connection allows using caches.
      * 
-     * @return true if this connection use caches by default, false otherwise
-     * 
-     * @see #getUseCaches
-     * @see #setDefaultUseCaches
-     * @see #setUseCaches
+     * @return the value of the default setting {@code defaultUseCaches}.
      * @see #useCaches
      */
     public boolean getDefaultUseCaches() {
@@ -356,11 +356,11 @@
     }
 
     /**
-     * Answers whether this connection supports input.
-     * 
-     * @return true if this connection supports input, false otherwise
+     * Gets the value of the option {@code doInput} which specifies whether this
+     * connection allows to receive data.
      * 
-     * @see #setDoInput
+     * @return {@code true} if this connection allows input, {@code false}
+     *         otherwise.
      * @see #doInput
      */
     public boolean getDoInput() {
@@ -368,11 +368,11 @@
     }
 
     /**
-     * Answers whether this connection supports output.
+     * Gets the value of the option {@code doOutput} which specifies whether
+     * this connection allows to send data.
      * 
-     * @return true if this connection supports output, false otherwise
-     * 
-     * @see #setDoOutput
+     * @return {@code true} if this connection allows output, {@code false}
+     *         otherwise.
      * @see #doOutput
      */
     public boolean getDoOutput() {
@@ -380,26 +380,20 @@
     }
 
     /**
-     * Answers the date in milliseconds since epoch when this response header
-     * expires or 0 if the field <code>Expires</code> is not found in the
-     * header.
-     * 
-     * @return Date in milliseconds since epoch
-     * 
-     * @see #getHeaderField(int)
-     * @see #getHeaderField(String)
-     * @see #getHeaderFieldDate(String, long)
-     * @see #getHeaderFieldInt(String, int)
-     * @see #getHeaderFieldKey(int)
+     * Gets the timestamp when this response will be expired in milliseconds
+     * since January 1, 1970 GMT or {@code 0} if this timestamp is unknown.
+     * 
+     * @return the value of the response header field {@code expires}.
      */
     public long getExpiration() {
         return getHeaderFieldDate("Expires", 0); //$NON-NLS-1$
     }
 
     /**
-     * Answers the MIME table of this URL connection.
+     * Gets the table which is used by all {@code URLConnection} instances to
+     * determine the MIME-type according to a file extension.
      * 
-     * @return FileNameMap
+     * @return the file name map to determine the MIME-type.
      */
     public static FileNameMap getFileNameMap() {
         // Must use lazy initialization or there is a bootstrap problem
@@ -412,28 +406,24 @@
     }
 
     /**
-     * Answers the value of the field at position <code>pos<code>.
-     * Answers <code>null</code> if there are fewer than <code>pos</code> fields
-     * in the response header.
-     *
-     * @param 		pos 		the position of the field
-     * @return 		The value of the field
+     * Gets the header value at the field position {@code pos} or {@code null}
+     * if the header has fewer than {@code pos} fields. The current
+     * implementation of this method returns always {@code null}.
      *
-     * @see 		#getHeaderFieldDate
-     * @see 		#getHeaderFieldInt
-     * @see 		#getHeaderFieldKey
+     * @param pos
+     *            the field position of the response header.
+     * @return the value of the field at position {@code pos}.
      */
     public String getHeaderField(int pos) {
         return null;
     }
 
     /**
-     * Provides an unmodifiable map of the connection header values. The map
-     * keys are the String header field names. Each map value is a List of the
-     * header field values associated with that key name.
-     * 
-     * @return the mapping of header field names to values
+     * Gets an unchangeable map of the response-header fields and values. The
+     * response-header field names are the key values of the map. The map values
+     * are lists of header field values associated with a particular key name.
      * 
+     * @return the response-header representing generic map.
      * @since 1.4
      */
     public Map<String, List<String>> getHeaderFields() {
@@ -441,12 +431,11 @@
     }
 
     /**
-     * Provides an unmodifiable map of the request properties. The map keys are
-     * Strings, the map values are each a List of Strings, with each request
-     * property name mapped to its corresponding property values.
-     * 
-     * @return the mapping of request property names to values
+     * Gets an unchangeable map of general request properties used by this
+     * connection. The request property names are the key values of the map. The
+     * map values are lists of property values of the corresponding key name.
      * 
+     * @return the request-property representing generic map.
      * @since 1.4
      */
     public Map<String, List<String>> getRequestProperties() {
@@ -457,19 +446,17 @@
     }
 
     /**
-     * Adds the given request property. Will not overwrite any existing
-     * properties associated with the given field name.
+     * Adds the given property to the request header. Existing properties with
+     * the same name will not be overwritten by this method.
      * 
      * @param field
-     *            the request property field name
+     *            the request property field name to add.
      * @param newValue
-     *            the property value
-     * 
-     * @throws IllegalStateException -
-     *             if connection already established
-     * @throws NullPointerException -
-     *             if field is null
-     * 
+     *            the value of the property which is to add.
+     * @throws IllegalStateException
+     *             if the connection has been already established.
+     * @throws NullPointerException
+     *             if the property name is {@code null}.
      * @since 1.4
      */
     public void addRequestProperty(String field, String newValue) {
@@ -482,35 +469,29 @@
     }
 
     /**
-     * Answers the value of the field corresponding to the <code>key</code>
-     * Answers <code>null</code> if there is no such field.
+     * Gets the value of the header field specified by {@code key} or {@code
+     * null} if there is no field with this name. The current implementation of
+     * this method returns always {@code null}.
      * 
      * @param key
-     *            the name of the header field
-     * @return The value of the header field
-     * 
-     * @see #getHeaderFieldDate
-     * @see #getHeaderFieldInt
-     * @see #getHeaderFieldKey
+     *            the name of the header field.
+     * @return the value of the header field.
      */
     public String getHeaderField(String key) {
         return null;
     }
 
     /**
-     * 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.
+     * Gets the specified header value as a date in milliseconds since January
+     * 1, 1970 GMT. Returns the {@code defaultValue} if no such header field
+     * could be found.
      * 
      * @param field
-     *            the field in question
+     *            the header field name whose value is needed.
      * @param defaultValue
-     *            the default value if no field is found or the value is invalid
-     * @return milliseconds since epoch
-     * 
-     * @see #ifModifiedSince
-     * @see #setIfModifiedSince
+     *            the default value if no field has been found.
+     * @return the value of the specified header field as a date in
+     *         milliseconds.
      */
     @SuppressWarnings("deprecation")
     public long getHeaderFieldDate(String field, long defaultValue) {
@@ -526,14 +507,15 @@
     }
 
     /**
-     * Answers the integer value of the specified field. Answers default value
-     * <code>defaultValue</code> if no such field exists.
+     * Gets the specified header value as a number. Returns the {@code
+     * defaultValue} if no such header field could be found or the value could
+     * not be parsed as an {@code Integer}.
      * 
      * @param field
-     *            the field to return
+     *            the header field name whose value is needed.
      * @param defaultValue
-     *            to be returned if <code>field></code> does not exist
-     * @return value of the field
+     *            the default value if no field has been found.
+     * @return the value of the specified header field as a number.
      */
     public int getHeaderFieldInt(String field, int defaultValue) {
         try {
@@ -544,68 +526,48 @@
     }
 
     /**
-     * Answers the name of the field at position specified by <code>posn</code>,
-     * null if there are fewer than <code>posn</code> fields.
+     * Gets the name of the header field at the given position {@code posn} or
+     * {@code null} if there are fewer than {@code posn} fields. The current
+     * implementation of this method returns always {@code null}.
      * 
      * @param posn
-     *            the position to look for; the first field being 0
-     * @return the name of the field
-     * 
-     * @see #getHeaderFieldDate
-     * @see #getHeaderFieldInt
-     * @see #getHeaderField(int)
-     * @see #getHeaderField(String)
-     * @see #getHeaderFieldDate(String, long)
-     * @see #getHeaderFieldInt(String, int)
-     * @see #getHeaderFieldKey(int)
+     *            the position of the header field which has to be returned.
+     * @return the header field name at the given position.
      */
     public String getHeaderFieldKey(int posn) {
         return null;
     }
 
     /**
-     * Answers the value of <code>ifModifiedSince</code> of this connection in
-     * milliseconds since epoch
-     * 
-     * @return the time since epoch
+     * Gets the point of time since when the data must be modified to be
+     * transmitted. Some protocols transmit data only if it has been modified
+     * more recently than a particular time.
      * 
+     * @return the time in milliseconds since January 1, 1970 GMT.
      * @see #ifModifiedSince
-     * @see #setIfModifiedSince
      */
     public long getIfModifiedSince() {
         return ifModifiedSince;
     }
 
     /**
-     * Creates an InputStream for reading from this URL Connection. It throws
-     * UnknownServiceException by default. This method should be overridden by
-     * its subclasses
-     * 
-     * @return The InputStream to read from
+     * Gets an {@code InputStream} for reading data from the resource pointed by
+     * this {@code URLConnection}. It throws an UnknownServiceException by
+     * default. This method must be overridden by its subclasses.
      * 
+     * @return the InputStream to read data from.
      * @throws IOException
-     *             If an InputStream could not be created
-     * 
-     * @see #getContent()
-     * @see #getContent(Class[])
-     * @see #getOutputStream
-     * @see java.io.InputStream
-     * @see java.io.IOException
-     * 
+     *             if no InputStream could be created.
      */
     public InputStream getInputStream() throws IOException {
         throw new UnknownServiceException(Msg.getString("K004d")); //$NON-NLS-1$
     }
 
     /**
-     * Answers the value of the field <code>Last-Modified</code> in the
-     * response header, 0 if no such field exists
+     * Gets the value of the response header field {@code last-modified} or
+     * {@code 0} if this value is not set.
      * 
-     * @return the value of the field last modified
-     * 
-     * @see java.util.Date
-     * @see #getDate
-     * @see #getExpiration
+     * @return the value of the {@code last-modified} header field.
      */
     public long getLastModified() {
         if (lastModified != -1) {
@@ -615,60 +577,45 @@
     }
 
     /**
-     * Creates an OutputStream for writing to this URL Connection. It throws
-     * UnknownServiceException by default. This method should be overridden by
-     * subclasses.
-     * 
-     * @return The OutputStream to write to
+     * Gets an {@code OutputStream} for writing data to this {@code
+     * URLConnection}. It throws an {@code UnknownServiceException} by default.
+     * This method must be overridden by its subclasses.
      * 
+     * @return the OutputStream to write data.
      * @throws IOException
-     *             If an OutputStream could not be created
-     * 
-     * @see #getContent()
-     * @see #getContent(Class[])
-     * @see #getInputStream
-     * @see java.io.IOException
-     * 
+     *             if no OutputStream could be created.
      */
     public OutputStream getOutputStream() throws IOException {
         throw new UnknownServiceException(Msg.getString("K005f")); //$NON-NLS-1$
     }
 
     /**
-     * Answers the permissions necessary to make the connection. Depending on
-     * the protocol, this can be any of the permission subclasses. The
-     * permission returned may also depend on the state of the connection, E.G
-     * In the case of HTTP, redirection can change the applicable permission if
-     * the host changed.
-     * 
-     * <p>
-     * By default, this methods returns <code>AllPermission</code>.
-     * Subclasses should override this and return the appropriate permission
-     * object.
-     * 
-     * @return the permission object governing the connection
+     * Gets a {@code Permission} object representing all needed permissions to
+     * open this connection. The returned permission object depends on the state
+     * of the connection and will be {@code null} if no permissions are
+     * necessary. By default, this method returns {@code AllPermission}.
+     * Subclasses should overwrite this method to return an appropriate
+     * permission object.
      * 
+     * @return the permission object representing the needed permissions to open
+     *         this connection.
      * @throws IOException
-     *             if an IO exception occurs during the creation of the
-     *             permission object.
+     *             if an I/O error occurs while creating the permission object.
      */
     public java.security.Permission getPermission() throws IOException {
         return new java.security.AllPermission();
     }
 
     /**
-     * Answers the value corresponding to the field in the request Header, null
-     * if no such field exists.
+     * Gets the value of the request header property specified by {code field}
+     * or {@code null} if there is no field with this name. The current
+     * implementation of this method returns always {@code null}.
      * 
      * @param field
-     *            the field to get the property for
-     * @return the field to look up
-     * @throws IllegalStateException -
-     *             if connection already established
-     * 
-     * @see #getDefaultRequestProperty
-     * @see #setDefaultRequestProperty
-     * @see #setRequestProperty
+     *            the name of the request header property.
+     * @return the value of the property.
+     * @throws IllegalStateException
+     *             if the connection has been already established.
      */
     public String getRequestProperty(String field) {
         if (connected) {
@@ -678,55 +625,49 @@
     }
 
     /**
-     * Answers the <code>URL</code> of this connection
-     * 
-     * @return the URL of this connection
+     * Gets the URL represented by this {@code URLConnection}.
      * 
-     * @see URL
-     * @see #URLConnection(URL)
+     * @return the URL of this connection.
      */
     public URL getURL() {
         return url;
     }
 
     /**
-     * Answers whether this connection uses caches
+     * Gets the value of the flag which specifies whether this {@code
+     * URLConnection} allows to use caches.
      * 
-     * @return the value of the flag
+     * @return {@code true} if using caches is allowed, {@code false} otherwise.
      */
     public boolean getUseCaches() {
         return useCaches;
     }
 
     /**
-     * Determines the MIME type of the file specified by the
-     * <code> string </code> URL, using the filename extension. Any fragment
+     * Determines the MIME-type of the given resource {@code url} by resolving
+     * the filename extension with the internal FileNameMap. Any fragment
      * identifier is removed before processing.
      * 
      * @param url
-     *            the MIME type of the file.
-     * @return the string representation of an URL
-     * 
-     * @see FileNameMap
-     * @see FileNameMap#getContentTypeFor(String)
-     * @see #getContentType
-     * @see #guessContentTypeFromStream
-     * 
+     *            the URL with the filename to get the MIME type.
+     * @return the guessed content type or {@code null} if the type could not be
+     *         determined.
      */
     public static String guessContentTypeFromName(String url) {
         return getFileNameMap().getContentTypeFor(url);
     }
 
     /**
-     * Examines the bytes of the input stream and returns the MIME type, null if
-     * no content type can be deduced.
+     * Determines the MIME-type of the resource represented by the input stream
+     * {@code is} by reading its first few characters.
      * 
      * @param is
-     *            the input stream for the URL
-     * @return the type of the input stream
-     * 
+     *            the resource representing input stream to determine the
+     *            content type.
+     * @return the guessed content type or {@code null} if the type could not be
+     *         determined.
      * @throws IOException
-     *             If an IO error occurs
+     *             if an I/O error occurs while reading from the input stream.
      */
     @SuppressWarnings("nls")
     public static String guessContentTypeFromStream(InputStream is)
@@ -830,14 +771,15 @@
 
     /**
      * Sets the flag indicating whether this connection allows user interaction
-     * This can only be called prior to connection establishment.
+     * or not. This method can only be called prior to the connection
+     * establishment.
      * 
      * @param newValue
-     *            the value of the flag to be set
-     * 
+     *            the value of the flag to be set.
      * @throws IllegalStateException
-     *             if this method attempts to change the flag after a connection
-     *             has been established
+     *             if this method attempts to change the flag after the
+     *             connection has been established.
+     * @see #allowUserInteraction
      */
     public void setAllowUserInteraction(boolean newValue) {
         if (connected) {
@@ -847,22 +789,15 @@
     }
 
     /**
-     * Sets the current content handler factory to be
-     * <code>contentFactory</code>. It can only do so with the permission of
-     * the security manager. The ContentFactory can only be specified once
-     * during the lifetime of an application.
+     * Sets the internally used content handler factory. The content factory can
+     * only be set if it is allowed by the security manager and only once during
+     * the lifetime of the application.
      * 
      * @param contentFactory
-     *            the factory
-     * 
+     *            the content factory to be set.
      * @throws Error
-     *             if a ContentFactory has been created before SecurityException
-     *             if the security manager does not allow this action
-     * 
-     * @see ContentHandler
-     * @see ContentHandlerFactory
-     * @see java.lang.SecurityException
-     * @see java.lang.SecurityManager#checkSetFactory()
+     *             if the security manager does not allow to set the content
+     *             factory or it has been already set earlier ago.
      */
     public static synchronized void setContentHandlerFactory(
             ContentHandlerFactory contentFactory) {
@@ -877,41 +812,42 @@
     }
 
     /**
-     * Set whether user interaction is allowed by default. Existing
-     * URLConnections are unaffected.
+     * Sets the default value for the flag indicating whether this connection
+     * allows user interaction or not. Existing {@code URLConnection}s are
+     * unaffected.
      * 
      * @param allows
-     *            allow user interaction
+     *            the default value of the flag to be used for new connections.
+     * @see #defaultAllowUserInteraction
+     * @see #allowUserInteraction
      */
     public static void setDefaultAllowUserInteraction(boolean allows) {
         defaultAllowUserInteraction = allows;
     }
 
     /**
-     * Sets the <code>field</code> in the default request header with the
-     * value <code>value</code>
+     * Sets the default value of the specified request header field. This value
+     * will be used for the specific field of every newly created connection.
+     * The current implementation of this method does nothing.
      * 
      * @param field
-     *            the request header field to be set
+     *            the request header field to be set.
      * @param value
-     *            the new value
-     * 
-     * @deprecated Use getRequestProperty().
+     *            the default value to be used.
+     * @deprecated Use {@link #setRequestProperty} of an existing {@code
+     *             URLConnection} instance.
      */
     @Deprecated
     public static void setDefaultRequestProperty(String field, String value) {
     }
 
     /**
-     * Set whether caches are used by default. Existing URLConnections are
-     * unaffected.
+     * Sets the default value for the flag indicating whether this connection
+     * allows to use caches. Existing {@code URLConnection}s are unaffected.
      * 
      * @param newValue
-     *            the value of the flag to be set
-     * 
-     * @see #getDefaultUseCaches
-     * @see #getUseCaches
-     * @see #setUseCaches
+     *            the default value of the flag to be used for new connections.
+     * @see #defaultUseCaches
      * @see #useCaches
      */
     public void setDefaultUseCaches(boolean newValue) {
@@ -922,20 +858,15 @@
     }
 
     /**
-     * Sets whether this URLConnection allows input. It cannot be set after the
-     * connection is made.
+     * Sets the flag indicating whether this {@code URLConnection} allows input.
+     * It cannot be set after the connection is established.
      * 
      * @param newValue
-     *            boolean
-     * 
+     *            the new value for the flag to be set.
      * @throws IllegalAccessError
-     *             Exception thrown when this method attempts to change the
-     *             value after connected
-     * 
+     *             if this method attempts to change the value after the
+     *             connection has been already established.
      * @see #doInput
-     * @see #getDoInput
-     * @see #setDoInput
-     * @see java.lang.IllegalAccessError
      */
     public void setDoInput(boolean newValue) {
         if (connected) {
@@ -945,20 +876,15 @@
     }
 
     /**
-     * Sets whether this URLConnection allows output. It cannot be set after the
-     * connection is made.
+     * Sets the flag indicating whether this {@code URLConnection} allows
+     * output. It cannot be set after the connection is established.
      * 
      * @param newValue
-     *            boolean
-     * 
+     *            the new value for the flag to be set.
      * @throws IllegalAccessError
-     *             Exception thrown when this method attempts to change the
-     *             value after connected
-     * 
+     *             if this method attempts to change the value after the
+     *             connection has been already established.
      * @see #doOutput
-     * @see #getDoOutput
-     * @see #setDoOutput
-     * @see java.lang.IllegalAccessError
      */
     public void setDoOutput(boolean newValue) {
         if (connected) {
@@ -968,8 +894,8 @@
     }
 
     /**
-     * With permission from the security manager, this method sets the
-     * <code>map</code> to be the MIME Table of this URL connection.
+     * Sets the internal map which is used by all {@code URLConnection}
+     * instances to determine the MIME-type according to a filename extension.
      * 
      * @param map
      *            the MIME table to be set.
@@ -983,12 +909,16 @@
     }
 
     /**
-     * Sets the header field <code>ifModifiedSince</code>.
+     * Sets the point of time since when the data must be modified to be
+     * transmitted. Some protocols transmit data only if it has been modified
+     * more recently than a particular time. The data will be transmitted
+     * regardless of its timestamp if this option is set to {@code 0}.
      * 
      * @param newValue
-     *            number of milliseconds since epoch
+     *            the time in milliseconds since January 1, 1970 GMT.
      * @throws IllegalStateException
-     *             if already connected.
+     *             if this {@code URLConnection} has already been connected.
+     * @see #ifModifiedSince
      */
     public void setIfModifiedSince(long newValue) {
         if (connected) {
@@ -998,23 +928,18 @@
     }
 
     /**
-     * Sets the value of the request header field <code> field </code> to
-     * <code>newValue</code> Only the current URL Connection is affected. It
-     * can only be called before the connection is made
+     * Sets the value of the specified request header field. The value will only
+     * be used by the current {@code URLConnection} instance. This method can
+     * only be called before the connection is established.
      * 
      * @param field
-     *            the field
+     *            the request header field to be set.
      * @param newValue
-     *            the field's new value
-     * 
-     * @throws IllegalStateException -
-     *             if connection already established
-     * @throws NullPointerException -
-     *             if field is null
-     * 
-     * @see #getDefaultRequestProperty
-     * @see #setDefaultRequestProperty
-     * @see #getRequestProperty
+     *            the new value of the specified property.
+     * @throws IllegalStateException
+     *             if the connection has been already established.
+     * @throws NullPointerException
+     *             if the parameter {@code field} is {@code null}.
      */
     public void setRequestProperty(String field, String newValue) {
         if (connected) {
@@ -1026,19 +951,15 @@
     }
 
     /**
-     * Sets the flag indicating if this connection uses caches. This value
-     * cannot be set after the connection is made.
+     * Sets the flag indicating whether this connection allows to use caches or
+     * not. This method can only be called prior to the connection
+     * establishment.
      * 
      * @param newValue
-     *            the value of the flag to be set
-     * 
+     *            the value of the flag to be set.
      * @throws IllegalStateException
-     *             Exception thrown when this method attempts to change the
-     *             value after connected
-     * 
-     * @see #getDefaultUseCaches
-     * @see #setDefaultUseCaches
-     * @see #getUseCaches
+     *             if this method attempts to change the flag after the
+     *             connection has been established.
      * @see #useCaches
      */
     public void setUseCaches(boolean newValue) {
@@ -1049,13 +970,16 @@
     }
 
     /**
-     * Sets a timeout for connection to perform non-block. Default is zero.
-     * Timeout of zero means infinite.
+     * Sets the timeout value in milliseconds for establishing the connection to
+     * the resource pointed by this {@code URLConnection} instance. A {@code
+     * SocketTimeoutException} is thrown if the connection could not be
+     * established in this time. Default is {@code 0} which stands for an
+     * infinite timeout.
      * 
      * @param timeout
-     *            timeout for connection in milliseconds.
+     *            the connecting timeout in milliseconds.
      * @throws IllegalArgumentException
-     *             if timeout is less than zero.
+     *             if the parameter {@code timeout} is less than zero.
      */
     public void setConnectTimeout(int timeout) {
         if (0 > timeout) {
@@ -1065,22 +989,25 @@
     }
 
     /**
-     * Returns a timeout of connection by milliseconds
+     * Gets the configured connecting timeout.
      * 
-     * @return timeout of connection by milliseconds
+     * @return the connecting timeout value in milliseconds.
      */
     public int getConnectTimeout() {
         return connectTimeout;
     }
 
     /**
-     * Sets a timeout for reading to perform non-block. Default is zero. Timeout
-     * of zero means infinite.
+     * Sets the timeout value in milliseconds for reading from the input stream
+     * of an established connection to the resource. A {@code
+     * SocketTimeoutException} is thrown if the connection could not be
+     * established in this time. Default is {@code 0} which stands for an
+     * infinite timeout.
      * 
      * @param timeout
-     *            timeout for reading in milliseconds.
+     *            the reading timeout in milliseconds.
      * @throws IllegalArgumentException
-     *             if timeout is less than zero.
+     *             if the parameter {@code timeout} is less than zero.
      */
     public void setReadTimeout(int timeout) {
         if (0 > timeout) {
@@ -1090,21 +1017,20 @@
     }
 
     /**
-     * Returns a timeout of reading by milliseconds
+     * Gets the configured timeout for reading from the input stream of an
+     * established connection to the resource.
      * 
-     * @return timeout of reading by milliseconds
+     * @return the reading timeout value in milliseconds.
      */
     public int getReadTimeout() {
         return readTimeout;
     }
 
     /**
-     * Answers the name of the class of the <code>URLConnection </code>
-     * 
-     * @return The string representation of this <code>URLConnection</code>
+     * Returns the string representation containing the name of this class and
+     * the URL.
      * 
-     * @see #getURL
-     * @see #URLConnection(URL)
+     * @return the string representation of this {@code URLConnection} instance.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLDecoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLDecoder.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLDecoder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLDecoder.java Wed May  6 08:33:17 2009
@@ -27,28 +27,26 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class is used to decode a string which is encoded in the
- * <code>application/x-www-form-urlencoded</code> MIME content type.
+ * This class is used to decode a string which is encoded in the {@code
+ * application/x-www-form-urlencoded} MIME content type.
  */
 public class URLDecoder {
 
     static Charset defaultCharset;
 
     /**
-     * Decodes the string argument which is assumed to be encoded in the
-     * <code>x-www-form-urlencoded</code> MIME content type.
+     * Decodes the argument which is assumed to be encoded in the {@code
+     * x-www-form-urlencoded} MIME content type.
      * <p>
-     * '+' will be converted to space, '%' and two following hex digit
+     *'+' will be converted to space, '%' and two following hex digit
      * characters are converted to the equivalent byte value. All other
-     * characters are passed through unmodified.
-     * <p>
-     * e.g. "A+B+C %24%25" -> "A B C $%"
-     * 
+     * characters are passed through unmodified. For example "A+B+C %24%25" ->
+     * "A B C $%".
+     *
      * @param s
-     *            java.lang.String The encoded string.
-     * @return java.lang.String The decoded version.
-     * 
-     * @deprecated use URLDecoder#decode(String, String) instead
+     *            the encoded string.
+     * @return the decoded clear-text representation of the given string.
+     * @deprecated use {@link #decode(String, String)} instead.
      */
     @Deprecated
     public static String decode(String s) {
@@ -71,22 +69,22 @@
     }
 
     /**
-     * Decodes the string argument which is assumed to be encoded in the
-     * <code>x-www-form-urlencoded</code> MIME content type using the
-     * specified encoding scheme.
+     * Decodes the argument which is assumed to be encoded in the {@code
+     * x-www-form-urlencoded} MIME content type using the specified encoding
+     * scheme.
      * <p>
-     * '+' will be converted to space, '%' and two following hex digit
+     *'+' will be converted to space, '%' and two following hex digit
      * characters are converted to the equivalent byte value. All other
-     * characters are passed through unmodified.
-     * 
-     * <p>
-     * e.g. "A+B+C %24%25" -> "A B C $%"
-     * 
+     * characters are passed through unmodified. For example "A+B+C %24%25" ->
+     * "A B C $%".
+     *
      * @param s
-     *            java.lang.String The encoded string.
+     *            the encoded string.
      * @param enc
-     *            java.lang.String The encoding scheme to use
-     * @return java.lang.String The decoded version.
+     *            the encoding scheme to be used.
+     * @return the decoded clear-text representation of the given string.
+     * @throws UnsupportedEncodingException
+     *             if the specified encoding scheme is invalid.
      */
     public static String decode(String s, String enc)
             throws UnsupportedEncodingException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLEncoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLEncoder.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLEncoder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLEncoder.java Wed May  6 08:33:17 2009
@@ -21,7 +21,7 @@
 
 /**
  * This class is used to encode a string using the format required by
- * <code>application/x-www-form-urlencoded</code> MIME content type.
+ * {@code application/x-www-form-urlencoded} MIME content type.
  */
 public class URLEncoder {
 
@@ -34,23 +34,18 @@
     }
 
     /**
-     * This class contains a utility method for converting a string to the
-     * format required by the <code>application/x-www-form-urlencoded</code>
-     * MIME content type.
+     * Encodes a given string {@code s} in a x-www-form-urlencoded string using
+     * the specified encoding scheme {@code enc}.
      * <p>
      * All characters except letters ('a'..'z', 'A'..'Z') and numbers ('0'..'9')
-     * and characters '.', '-', '*', '_' are converted into their hexidecimal
-     * value prepended by '%'.
-     * <p>
-     * For example: '#' -> %23
-     * <p>
-     * In addition, spaces are substituted by '+'
-     * 
-     * @return java.lang.String the string to be converted
+     * and characters '.', '-', '*', '_' are converted into their hexadecimal
+     * value prepended by '%'. For example: '#' -> %23. In addition, spaces are
+     * substituted by '+'
+     *
      * @param s
-     *            java.lang.String the converted string
-     * 
-     * @deprecated use URLEncoder#encode(String, String) instead
+     *            the string to be encoded.
+     * @return the encoded string.
+     * @deprecated use {@link #encode(String, String)} instead.
      */
     @Deprecated
     public static String encode(String s) {
@@ -75,25 +70,21 @@
     }
 
     /**
-     * This class contains a utility method for converting a string to the
-     * format required by the <code>application/x-www-form-urlencoded</code>
-     * MIME content type.
-     * 
+     * Encodes the given string {@code s} in a x-www-form-urlencoded string
+     * using the specified encoding scheme {@code enc}.
+     * <p>
      * All characters except letters ('a'..'z', 'A'..'Z') and numbers ('0'..'9')
      * and characters '.', '-', '*', '_' are converted into their hexadecimal
-     * value prepended by '%'.
-     * 
-     * For example: '#' -> %23
-     * 
-     * In addition, spaces are substituted by '+'
-     * 
+     * value prepended by '%'. For example: '#' -> %23. In addition, spaces are
+     * substituted by '+'
+     *
      * @param s
-     *            the string to be converted
+     *            the string to be encoded.
      * @param enc
-     *            the name of a charset to use for encoding unsafe chars
-     * @return the converted string
+     *            the encoding scheme to be used.
+     * @return the encoded string.
      * @throws UnsupportedEncodingException
-     *             if the named charset is unsupported
+     *             if the specified encoding scheme is invalid.
      */
     public static String encode(String s, String enc)
             throws UnsupportedEncodingException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandler.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandler.java Wed May  6 08:33:17 2009
@@ -23,40 +23,39 @@
 import org.apache.harmony.luni.util.URLUtil;
 
 /**
- * The abstract superclass of all classes that implement Protocol Handler.
+ * The abstract class {@code URLStreamHandler} is the base for all classes which
+ * can handle the communication with a URL object over a particular protocol
+ * type.
  */
 public abstract class URLStreamHandler {
     /**
-     * Establishes a connection to the resource specified by <code>URL</code>.
-     * Since different protocols may have unique ways of connecting, it must be
-     * overwritten by the subclass.
+     * Establishes a new connection to the resource specified by the URL {@code
+     * u}. Since different protocols also have unique ways of connecting, it
+     * must be overwritten by the subclass.
      * 
-     * @return java.net.URLConnection
      * @param u
-     *            java.net.URL
-     * 
-     * @exception IOException
-     *                thrown if an IO error occurs during connection
-     *                establishment
+     *            the URL to the resource where a connection has to be opened.
+     * @return the opened URLConnection to the specified resource.
+     * @throws IOException
+     *             if an I/O error occurs during opening the connection.
      */
     protected abstract URLConnection openConnection(URL u) throws IOException;
 
     /**
-     * The method is the same as <code>openConnection(URL u)</code> except
-     * that it uses the <code>proxy</code> to establish a connection to the
-     * <code>URL</code>. Since different protocols may have different ways of
-     * connecting, it must be overwritten by the subclass.
+     * Establishes a new connection to the resource specified by the URL {@code
+     * u} using the given {@code proxy}. Since different protocols also have
+     * unique ways of connecting, it must be overwritten by the subclass.
      * 
-     * @return java.net.URLConnection
      * @param u
-     *            java.net.URL
+     *            the URL to the resource where a connection has to be opened.
      * @param proxy
-     *            the proxy which is used to make the connection
-     * 
+     *            the proxy that is used to make the connection.
+     * @return the opened URLConnection to the specified resource.
      * @throws IOException
-     *             thrown if an IO error occurs during connection establishment
+     *             if an I/O error occurs during opening the connection.
      * @throws IllegalArgumentException
-     *             if any argument is null or the type of proxy is wrong.
+     *             if any argument is {@code null} or the type of proxy is
+     *             wrong.
      * @throws UnsupportedOperationException
      *             if the protocol handler doesn't support this method.
      */
@@ -66,21 +65,22 @@
     }
 
     /**
-     * Parse the <code>string</code>str into <code>URL</code> using u's
-     * context. URL strings generally have the following format:
-     * <code><center>//www.company.com/java/file1.java#reference </center></code>
+     * Parses the clear text URL in {@code str} into a URL object. URL strings
+     * generally have the following format:
+     * <p>
+     * http://www.company.com/java/file1.java#reference
+     * <p>
      * The string is parsed in HTTP format. If the protocol has a different URL
      * format this method must be overridden.
      * 
      * @param u
-     *            java.net.URL The URL to receive parsed values.
+     *            the URL to fill in the parsed clear text URL parts.
      * @param str
-     *            java.lang.String The string URL spec from which u is derived
+     *            the URL string that is to be parsed.
      * @param start
-     *            int The index in the string from which to begin parsing
+     *            the string position from where to begin parsing.
      * @param end
-     *            int The index to stop parsing
-     * 
+     *            the string position to stop parsing.
      * @see #toExternalForm
      * @see URL
      */
@@ -236,25 +236,23 @@
     }
 
     /**
-     * Sets the fields of the <code>URL</code> with the supplied arguments
+     * Sets the fields of the URL {@code u} to the values of the supplied
+     * arguments.
      * 
      * @param u
-     *            java.net.URL The non-null URL to be set
+     *            the non-null URL object to be set.
      * @param protocol
-     *            java.lang.String The protocol
+     *            the protocol.
      * @param host
-     *            java.lang.String The host name
+     *            the host name.
      * @param port
-     *            int The port number
+     *            the port number.
      * @param file
-     *            java.lang.String The file component
+     *            the file component.
      * @param ref
-     *            java.lang.String The reference
-     * 
-     * @see java.util.Set
-     * 
+     *            the reference.
      * @deprecated use setURL(URL, String String, int, String, String, String,
-     *             String, String)
+     *             String, String) instead.
      */
     @Deprecated
     protected void setURL(URL u, String protocol, String host, int port,
@@ -266,28 +264,27 @@
     }
 
     /**
-     * Sets the fields of the <code>URL</code> with the supplied arguments
+     * Sets the fields of the URL {@code u} to the values of the supplied
+     * arguments.
      * 
      * @param u
-     *            java.net.URL The non-null URL to be set
+     *            the non-null URL object to be set.
      * @param protocol
-     *            java.lang.String The protocol
+     *            the protocol.
      * @param host
-     *            java.lang.String The host name
+     *            the host name.
      * @param port
-     *            int The port number
+     *            the port number.
      * @param authority
-     *            java.lang.String The authority
+     *            the authority.
      * @param userInfo
-     *            java.lang.String The user info
+     *            the user info.
      * @param file
-     *            java.lang.String The file component
+     *            the file component.
      * @param query
-     *            java.lang.String The query
+     *            the query.
      * @param ref
-     *            java.lang.String The reference
-     * 
-     * @see java.util.Set
+     *            the reference.
      */
     protected void setURL(URL u, String protocol, String host, int port,
             String authority, String userInfo, String file, String query,
@@ -299,12 +296,11 @@
     }
 
     /**
-     * Answers the string equivalent of an URL using HTTP parsinf format.
+     * Returns the clear text representation of a given URL using HTTP format.
      * 
-     * @return java.lang.String the string representation of this URL
      * @param url
-     *            java.net.URL the url object to be processed
-     * 
+     *            the URL object to be converted.
+     * @return the clear text representation of the specified URL.
      * @see #parseURL
      * @see URL#toExternalForm()
      */
@@ -331,17 +327,15 @@
     }
 
     /**
-     * Compares the two urls, and answers true if they represent the same URL.
-     * Two URLs are equal if they have the same file, host, port, protocol,
-     * query, and ref components.
+     * Compares two URL objects whether they represent the same URL. Two URLs
+     * are equal if they have the same file, host, port, protocol, query, and
+     * reference components.
      * 
      * @param url1
-     *            URL the first URL to compare
+     *            the first URL to compare.
      * @param url2
-     *            URL the second URL to compare
-     * @return <code>true</code> if the URLs are the same <code>false</code>
-     *         if the URLs are different
-     * 
+     *            the second URL to compare.
+     * @return {@code true} if the URLs are the same, {@code false} otherwise.
      * @see #hashCode
      */
     protected boolean equals(URL url1, URL url2) {
@@ -358,14 +352,21 @@
     }
 
     /**
-     * Return the default port.
+     * Returns the default port of the protocol used by the handled URL. The
+     * current implementation returns always {@code -1}.
+     *
+     * @return the appropriate default port number of the protocol.
      */
     protected int getDefaultPort() {
         return -1;
     }
 
     /**
-     * Return the InetAddress for the host of the URL, or null.
+     * Returns the host address of the given URL.
+     *
+     * @param url
+     *            the URL object where to read the host address from.
+     * @return the host address of the specified URL.
      */
     protected InetAddress getHostAddress(URL url) {
         try {
@@ -380,20 +381,25 @@
     }
 
     /**
-     * Answers a hash code for the URL object.
+     * Returns the hashcode value for the given URL object.
      * 
-     * @return int the hashcode for hashtable indexing
+     * @param url
+     *            the URL to determine the hashcode.
+     * @return the hashcode of the given URL.
      */
     protected int hashCode(URL url) {
         return toExternalForm(url).hashCode();
     }
 
     /**
-     * Compares the two urls, and answers true if they have the same host
-     * components.
-     * 
-     * @return <code>true</code> if the hosts of the URLs are the same
-     *         <code>false</code> if the hosts are different
+     * Compares two URL objects whether they refer to the same host.
+     *
+     * @param url1
+     *            the first URL to be compared.
+     * @param url2
+     *            the second URL to be compared.
+     * @return {@code true} if both URLs refer to the same host, {@code false}
+     *         otherwise.
      */
     protected boolean hostsEqual(URL url1, URL url2) {
         String host1 = getHost(url1), host2 = getHost(url2);
@@ -410,10 +416,15 @@
     }
 
     /**
-     * Answers true if the urls refer to the same file. Compares the protocol,
-     * host, port and file components.
+     * Compares two URL objects whether they refer to the same file. In the
+     * comparison included are the URL components protocol, host, port and file.
      * 
-     * @return boolean true if the same resource, false otherwise
+     * @param url1
+     *            the first URL to be compared.
+     * @param url2
+     *            the second URL to be compared.
+     * @return {@code true} if both URLs refer to the same file, {@code false}
+     *         otherwise.
      */
     protected boolean sameFile(URL url1, URL url2) {
         String s1 = url1.getProtocol();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandlerFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandlerFactory.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandlerFactory.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLStreamHandlerFactory.java Wed May  6 08:33:17 2009
@@ -18,16 +18,18 @@
 package java.net;
 
 /**
- * Defines a factory which creates URL Stream (protocol) Handler It is used by
- * the classes <code>URL</code>
+ * Defines a factory which creates an {@code URLStreamHandler} for a specified
+ * protocol. It is used by the class {@code URL}.
  */
 public interface URLStreamHandlerFactory {
+
     /**
-     * Creates a new <code>URL Stream Handler</code> instance.
+     * Creates a new {@code URLStreamHandler} instance for the given {@code
+     * protocol}.
      * 
-     * @return java.net.URLStreamHandler
      * @param protocol
-     *            java.lang.String
+     *            the protocol for which a handler is needed.
+     * @return the created handler.
      */
     URLStreamHandler createURLStreamHandler(String protocol);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownHostException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownHostException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownHostException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownHostException.java Wed May  6 08:33:17 2009
@@ -20,26 +20,26 @@
 import java.io.IOException;
 
 /**
- * This UnknownHostException is thrown when an IP address resolution is
- * attempted and no host or resolver may be found.
+ * Is thrown when a hostname can not be resolved.
  */
 public class UnknownHostException extends IOException {
 
     private static final long serialVersionUID = -4639126076052875403L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code UnknownHostException} instance with its walkback
+     * filled in.
      */
     public UnknownHostException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code UnknownHostException} instance with its walkback
+     * and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public UnknownHostException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownServiceException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownServiceException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownServiceException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/UnknownServiceException.java Wed May  6 08:33:17 2009
@@ -20,28 +20,29 @@
 import java.io.IOException;
 
 /**
- * This UnknownServiceException is thrown when a particular service requested
- * isn't support by the URL. Examples are attempts to read from an URL via an
- * <code>InputStream</code> or write to an URL via an
- * <code>OutputStream</code>
+ * Is thrown if no appropriate {@code ContentHandler} could be found for a
+ * particular service requested by the URL connection. This could be happened if
+ * there is an invalid MIME type or the application wants to send data over a
+ * read-only connection.
  */
 public class UnknownServiceException extends IOException {
 
     private static final long serialVersionUID = -4169033248853639508L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code UnknownServiceException} instance with its
+     * walkback filled in.
      */
     public UnknownServiceException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Constructs a new {@code UnknownServiceException} instance with its
+     * walkback and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for this exception.
      */
     public UnknownServiceException(String detailMessage) {
         super(detailMessage);



Mime
View raw message