harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r772095 [5/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/SocketOptions.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketOptions.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketOptions.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketOptions.java Wed May  6 08:33:17 2009
@@ -19,66 +19,138 @@
 
 
 /**
- * Defines the protocol to get & set Socket options.
+ * Defines an interface for socket implementations to get and set socket
+ * options. It is implemented by the classes {@code SocketImpl} and {@code
+ * DatagramSocketImpl}.
+ * 
+ * @see SocketImpl
+ * @see DatagramSocketImpl
  */
 public interface SocketOptions {
 
-	public static final int SO_LINGER = 128;
-
-	public static final int SO_TIMEOUT = 4102;
-
-	public static final int TCP_NODELAY = 1;
-
-	// For 5 and 6 see MulticastSocket
-
-	// For 7 see PlainDatagramSocketImpl
-	
-	public static final int IP_MULTICAST_IF = 16;
-
-	public static final int SO_BINDADDR = 15;
-
-	public static final int SO_REUSEADDR = 4;
-
-	// 10 not currently used
-	
-	public static final int SO_SNDBUF = 4097;
-
-	public static final int SO_RCVBUF = 4098;
-
-	// For 13, see DatagramSocket
-	
-	public static final int SO_KEEPALIVE = 8;
-
-	public static final int IP_TOS = 3;
-
-	public static final int IP_MULTICAST_LOOP = 18;
-
-	public static final int SO_BROADCAST = 32;
-
-	public static final int SO_OOBINLINE = 4099;
-
-	public static final int IP_MULTICAST_IF2 = 31;
-
-	/**
-	 * Answer the declared socket option.
-	 * 
-	 * @return Object the option value
-	 * @param optID
-	 *            the option identifier
-	 * @exception SocketException
-	 *                thrown if an error occurs getting the option
-	 */
-	public Object getOption(int optID) throws SocketException;
-
-	/**
-	 * Set the declared socket option to the value.
-	 * 
-	 * @param optID
-	 *            the option identifier
-	 * @param val
-	 *            the option value to be set
-	 * @exception SocketException
-	 *                thrown if an error occurs setting the option
-	 */
+    /**
+     * This option specifies the behavior of the {@code close()} method if there
+     * is still some buffered data to be sent while closing the socket. If the
+     * value of this option is set to {@code 0} the method closes the TCP socket
+     * forcefully and returns immediately. Is this value greater than {@code 0}
+     * the method blocks this time in milliseconds. If all data could be sent
+     * during this timeout the socket is closed normally otherwise forcefully.
+     * Valid values for this option are in the range {@code 0 <= SO_LINGER <=
+     * 65535}.
+     */
+    public static final int SO_LINGER = 128;
+
+    /**
+     * Timeout for blocking operations. The argument value is specified in
+     * milliseconds. An {@code InterruptedIOException} is thrown if this timeout
+     * expires.
+     */
+    public static final int SO_TIMEOUT = 4102;
+
+    /**
+     * This option specifies whether data is sent immediately on this socket, as
+     * a side-effect though, this could lead to a low packet efficiency. The
+     * socket implementation uses the Nagle's algorithm to try to reach a higher
+     * packet efficiency if this option is disabled.
+     */
+    public static final int TCP_NODELAY = 1;
+
+    // For 5 and 6 see MulticastSocket
+
+    // For 7 see PlainDatagramSocketImpl
+    
+    /**
+     * This option specifies the interface which is used to send multicast
+     * packets. It's only available on a {@code MulticastSocket}.
+     */
+    public static final int IP_MULTICAST_IF = 16;
+
+    /**
+     * This option can be used to set one specific interface on a multihomed
+     * host on which incoming connections are accepted. It's only available on
+     * server-side sockets.
+     */
+    public static final int SO_BINDADDR = 15;
+
+    /**
+     * This option specifies whether a reuse of a local address is allowed even
+     * if an other socket is not yet removed by the operating system. It's only
+     * available on a {@code MulticastSocket}.
+     */
+    public static final int SO_REUSEADDR = 4;
+
+    // 10 not currently used
+    
+    /**
+     * Buffer size of the outgoing channel.
+     */
+    public static final int SO_SNDBUF = 4097;
+
+    /**
+     * Buffer size of the incoming channel.
+     */
+    public static final int SO_RCVBUF = 4098;
+
+    // For 13, see DatagramSocket
+    
+    /**
+     * This option specifies whether socket implementations can send keepalive
+     * messages if no data has been sent for a longer time.
+     */
+    public static final int SO_KEEPALIVE = 8;
+    
+    /**
+     * This option specifies the value for the Type-of-Service (TOS) field of
+     * the IP header.
+     */
+    public static final int IP_TOS = 3;
+    
+    /**
+     * This option specifies whether the local loopback of multicast packets is
+     * enabled or disabled. This option is enabled by default on multicast
+     * sockets.
+     */
+    public static final int IP_MULTICAST_LOOP = 18;
+    
+    /**
+     * This option can be used to enable broadcasting on datagram sockets.
+     */
+    public static final int SO_BROADCAST = 32;
+    
+    /**
+     * This option specifies whether sending TCP urgent data is supported on
+     * this socket or not.
+     */
+    public static final int SO_OOBINLINE = 4099;
+    
+    /**
+     * This option can be used to set one specific interface on a multihomed
+     * host on which incoming connections are accepted. It's only available on
+     * server-side sockets. This option supports setting outgoing interfaces
+     * with either IPv4 or IPv6 addresses.
+     */
+    public static final int IP_MULTICAST_IF2 = 31;
+
+    /**
+     * Gets the value for the specified socket option.
+     * 
+     * @return the option value.
+     * @param optID
+     *            the option identifier.
+     * @throws SocketException
+     *             if an error occurs reading the option value.
+     */
+    public Object getOption(int optID) throws SocketException;
+
+    /**
+     * Sets the value of the specified socket option.
+     * 
+     * @param optID
+     *            the option identifier.
+     * @param val
+     *            the value to be set for the option.
+     * @throws SocketException
+     *             if an error occurs setting the option value.
+     */
     public void setOption(int optID, Object val) throws SocketException;
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermission.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermission.java Wed May  6 08:33:17 2009
@@ -28,11 +28,13 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * SocketPermissions represent permission to access resources via sockets. The
- * name of the permission should be either the (possibly wildcarded (eg.
- * *.company.com)) DNS style name of the of the host for which access is being
- * requested, or its IP address in standard nn.nn.nn.nn ("dot") notation. The
- * action list can be made up of any of the following:
+ * Regulates the access to network operations available through sockets through
+ * permissions. A permission consists of a target (a host), and an associated
+ * action list. The target should identify the host by either indicating the
+ * (possibly wildcarded (eg. {@code .company.com})) DNS style name of the host
+ * or its IP address in standard {@code nn.nn.nn.nn} ("dot") notation. The
+ * action list can be made up of one or more of the following actions separated
+ * by a comma:
  * <dl>
  * <dt>connect</dt>
  * <dd>requests permission to connect to the host</dd>
@@ -41,23 +43,24 @@
  * <dt>accept</dt>
  * <dd>requests permission to accept connections from the host</dd>
  * <dt>resolve</dt>
- * <dd>requests permission to resolve the host name</dd>
+ * <dd>requests permission to resolve the hostname</dd>
  * </dl>
- * Note that "resolve" is implied when any (or none) of the others are present.
+ * Note that {@code resolve} is implied when any (or none) of the others are
+ * present.
  * <p>
  * Access to a particular port can be requested by appending a colon and a
- * single digit to the name (eg. "*.company.com:7000"). A range of port numbers
- * can also be specified, by appending a pattern of the form <low>-<high> where
- * <low> and <high> are valid port numbers. If either <low> or <high> is omitted
- * it is equivalent to entering the lowest or highest possible value
- * respectively. For example:
+ * single digit to the name (eg. {@code .company.com:7000}). A range of port
+ * numbers can also be specified, by appending a pattern of the form
+ * <i>LOW-HIGH</i> where <i>LOW</i> and <i>HIGH</i> are valid port numbers. If
+ * either <i>LOW</i> or <i>HIGH</i> is omitted it is equivalent to entering the
+ * lowest or highest possible value respectively. For example:
  * 
  * <pre>
- * SocketPermission(&quot;www.company.com:7000-&quot;, &quot;connect&quot;, &quot;accept&quot;)
+ * {@code SocketPermission(&quot;www.company.com:7000-&quot;, &quot;connect,accept&quot;)}
  * </pre>
  * 
- * represents permission to connect to and accept connections from
- * www.company.com on ports in the range 7000 to 65535.
+ * represents the permission to connect to and accept connections from {@code
+ * www.company.com} on ports in the range {@code 7000} to {@code 65535}.
  */
 public final class SocketPermission extends Permission implements Serializable {
 
@@ -105,18 +108,19 @@
     transient int actionsMask = SP_RESOLVE;
 
     /**
-     * Constructs an instance of this class. The host name can be a DNS name, an
-     * individual hostname, an ip address or the empty string which implies
-     * localhost. The port or port range is optional.
+     * Constructs a new {@code SocketPermission} instance. The hostname can be a
+     * DNS name, an individual hostname, an IP address or the empty string which
+     * implies {@code localhost}. The port or port range is optional.
      * <p>
-     * The action list is a comma-seperated list which can consist of "connect",
-     * "listen", "accept", and "resolve". They are case-insensitive and can be
-     * put together in any order. "resolve" is always implied.
+     * The action list is a comma-separated list which can consists of the
+     * possible operations {@code "connect"}, {@code "listen"}, {@code "accept"}
+     * , and {@code "resolve"}. They are case-insensitive and can be put
+     * together in any order. {@code "resolve"} is implied per default.
      * 
      * @param host
-     *            java.lang.String the host name
+     *            the hostname this permission is valid for.
      * @param action
-     *            java.lang.String the action string
+     *            the action string of this permission.
      */
     public SocketPermission(String host, String action) {
         super(host.equals("") ? "localhost" : host); //$NON-NLS-1$ //$NON-NLS-2$
@@ -135,14 +139,14 @@
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the equal objects using a class specific comparison.
-     * <p>
-     * 
+     * Compares the argument {@code o} to this instance and returns {@code true}
+     * if they represent the same permission using a class specific comparison.
+     *
      * @param o
-     *            the object to compare with this object
-     * @return <code>true</code> if the object is the same as this object
-     *         <code>false</code> if it is different from this object
+     *            the object to compare with this {@code SocketPermission}
+     *            instance.
+     * @return {@code true} if they represent the same permission, {@code false}
+     *         otherwise.
      * @see #hashCode
      */
     @Override
@@ -171,12 +175,11 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Any two objects which
-     * answer <code>true</code> when passed to <code>.equals</code> must
-     * answer the same value for this method.
-     * 
-     * @return int the receiver's hash.
+     * Returns the hash value for this {@code SocketPermission} instance. Any
+     * two objects which returns {@code true} when passed to {@code equals()}
+     * must return the same value as a result of this method.
      * 
+     * @return the hashcode value for this instance.
      * @see #equals
      */
     @Override
@@ -185,10 +188,11 @@
     }
 
     /**
-     * Answers the canonical action list of this SocketPermission in the order:
-     * connect, listen, accept, resolve.
+     * Gets a comma-separated list of all actions allowed by this permission. If
+     * more than one action is returned they follow this order: {@code connect},
+     * {@code listen}, {@code accept}, {@code resolve}.
      * 
-     * @return java.lang.String the canonical action list
+     * @return the comma-separated action list.
      */
     @Override
     public String getActions() {
@@ -196,7 +200,7 @@
     }
 
     /**
-     * Stores the actions for this permission as a bit field
+     * Stores the actions for this permission as a bit field.
      * 
      * @param actions
      *            java.lang.String the action list
@@ -235,16 +239,17 @@
     }
 
     /**
-     * Check the permission to see if the actions requested by the argument
-     * permission are permissable. All argument permission actions, host and
-     * port must be implied by this permission in order to return true. This
-     * permission may imply additional actions etc. not present in the argument
-     * permission.
+     * Checks whether this {@code SocketPermission} instance allows all actions
+     * which are allowed by the given permission object {@code p}. All argument
+     * permission actions, hosts and ports must be implied by this permission
+     * instance in order to return {@code true}. This permission may imply
+     * additional actions not present in the argument permission.
      * 
-     * @return boolean true if this permission implies <code>p</code>, and
-     *         false otherwise
      * @param p
-     *            java.security.Permission the other socket permission
+     *            the socket permission which has to be implied by this
+     *            instance.
+     * @return {@code true} if this permission instance implies all permissions
+     *         represented by {@code p}, {@code false} otherwise.
      */
     @Override
     public boolean implies(Permission p) {
@@ -274,9 +279,10 @@
     }
 
     /**
-     * Answers a PermissionCollection for storing SocketPermission objects.
+     * Creates a new {@code PermissionCollection} to store {@code
+     * SocketPermission} objects.
      * 
-     * @return java.security.PermissionCollection a permission collection
+     * @return the new permission collection.
      */
     @Override
     public PermissionCollection newPermissionCollection() {
@@ -454,9 +460,9 @@
         throw new IllegalArgumentException(Msg.getString("K004a") + " " + host);
     }
 
-    /*
+    /**
      * Determines whether or not this permission could refer to the same host as
-     * sp
+     * sp.
      */
     boolean checkHost(SocketPermission sp) {
         if (isPartialWild) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermissionCollection.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermissionCollection.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermissionCollection.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketPermissionCollection.java Wed May  6 08:33:17 2009
@@ -23,9 +23,9 @@
 import java.util.Vector;
 
 /**
- * SocketPermissionCollection is a class which holds a collection of
- * SocketPermission objects and can answer a boolean indicating whether or not a
- * specific permissions is implied by a SocketPermissionCollection.
+ * This class represents a list of {@code SocketPermission} objects and provides
+ * a method to check whether or not a specific permission is implied by this
+ * {@code SocketPermissionCollection}.
  */
 final class SocketPermissionCollection extends PermissionCollection {
 
@@ -50,15 +50,15 @@
         permissions.addElement(permission);
     }
 
-    // Answers an enumeration of the permissions
+    // Returns an enumeration of the permissions
     @Override
     public Enumeration<Permission> elements() {
         return permissions.elements();
     }
 
     /**
-     * Answers if this permission collection implies <code>permission</code>.
-     * Basically it tests if <code>permission</code> is the subset of this
+     * Returns whether this permission collection implies {@code permission}.
+     * Basically it tests whether {@code permission} is the subset of this
      * collection.
      */
     @Override

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketTimeoutException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketTimeoutException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketTimeoutException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/SocketTimeoutException.java Wed May  6 08:33:17 2009
@@ -19,23 +19,28 @@
 
 import java.io.InterruptedIOException;
 
+/**
+ * This exception is thrown when a timeout expired on a socket {@code read} or
+ * {@code accept} operation.
+ */
 public class SocketTimeoutException extends InterruptedIOException {
 
     private static final long serialVersionUID = -8846654841826352300L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Creates a new {@code SocketTimeoutException} instance with its walkback
+     * filled in.
      */
     public SocketTimeoutException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
+     * Creates a new {@code SocketTimeoutException} instance with its walkback
+     * and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message of this exception.
      */
     public SocketTimeoutException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URI.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URI.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URI.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URI.java Wed May  6 08:33:17 2009
@@ -74,10 +74,36 @@
     private URI() {
     }
 
+    /**
+     * Creates a new URI instance according to the given string {@code uri}.
+     *
+     * @param uri
+     *            the textual URI representation to be parsed into a URI object.
+     * @throws URISyntaxException
+     *             if the given string {@code uri} doesn't fit to the
+     *             specification RFC2396 or could not be parsed correctly.
+     */
     public URI(String uri) throws URISyntaxException {
         new Helper().parseURI(uri, false);
     }
 
+    /**
+     * Creates a new URI instance using the given arguments. This constructor
+     * first creates a temporary URI string from the given components. This
+     * string will be parsed later on to create the URI instance.
+     * <p>
+     * {@code [scheme:]scheme-specific-part[#fragment]}
+     *
+     * @param scheme
+     *            the scheme part of the URI.
+     * @param ssp
+     *            the scheme-specific-part of the URI.
+     * @param frag
+     *            the fragment part of the URI.
+     * @throws URISyntaxException
+     *             if the temporary created string doesn't fit to the
+     *             specification RFC2396 or could not be parsed correctly.
+     */
     public URI(String scheme, String ssp, String frag)
             throws URISyntaxException {
         StringBuffer uri = new StringBuffer();
@@ -98,6 +124,33 @@
         new Helper().parseURI(uri.toString(), false);
     }
 
+    /**
+     * Creates a new URI instance using the given arguments. This constructor
+     * first creates a temporary URI string from the given components. This
+     * string will be parsed later on to create the URI instance.
+     * <p>
+     * {@code [scheme:][user-info@]host[:port][path][?query][#fragment]}
+     *
+     * @param scheme
+     *            the scheme part of the URI.
+     * @param userinfo
+     *            the user information of the URI for authentication and
+     *            authorization.
+     * @param host
+     *            the host name of the URI.
+     * @param port
+     *            the port number of the URI.
+     * @param path
+     *            the path to the resource on the host.
+     * @param query
+     *            the query part of the URI to specify parameters for the
+     *            resource.
+     * @param fragment
+     *            the fragment part of the URI.
+     * @throws URISyntaxException
+     *             if the temporary created string doesn't fit to the
+     *             specification RFC2396 or could not be parsed correctly.
+     */
     public URI(String scheme, String userinfo, String host, int port,
             String path, String query, String fragment)
             throws URISyntaxException {
@@ -164,11 +217,52 @@
         new Helper().parseURI(uri.toString(), true);
     }
 
+    /**
+     * Creates a new URI instance using the given arguments. This constructor
+     * first creates a temporary URI string from the given components. This
+     * string will be parsed later on to create the URI instance.
+     * <p>
+     * {@code [scheme:]host[path][#fragment]}
+     *
+     * @param scheme
+     *            the scheme part of the URI.
+     * @param host
+     *            the host name of the URI.
+     * @param path
+     *            the path to the resource on the host.
+     * @param fragment
+     *            the fragment part of the URI.
+     * @throws URISyntaxException
+     *             if the temporary created string doesn't fit to the
+     *             specification RFC2396 or could not be parsed correctly.
+     */
     public URI(String scheme, String host, String path, String fragment)
             throws URISyntaxException {
         this(scheme, null, host, -1, path, null, fragment);
     }
 
+    /**
+     * Creates a new URI instance using the given arguments. This constructor
+     * first creates a temporary URI string from the given components. This
+     * string will be parsed later on to create the URI instance.
+     * <p>
+     * {@code [scheme:][//authority][path][?query][#fragment]}
+     *
+     * @param scheme
+     *            the scheme part of the URI.
+     * @param authority
+     *            the authority part of the URI.
+     * @param path
+     *            the path to the resource on the host.
+     * @param query
+     *            the query part of the URI to specify parameters for the
+     *            resource.
+     * @param fragment
+     *            the fragment part of the URI.
+     * @throws URISyntaxException
+     *             if the temporary created string doesn't fit to the
+     *             specification RFC2396 or could not be parsed correctly.
+     */
     public URI(String scheme, String authority, String path, String query,
             String fragment) throws URISyntaxException {
         if (scheme != null && path != null && path.length() > 0
@@ -741,6 +835,21 @@
         }
     }
 
+    /**
+     * Compares this URI with the given argument {@code uri}. This method will
+     * return a negative value if this URI instance is less than the given
+     * argument and a positive value if this URI instance is greater than the
+     * given argument. The return value {@code 0} indicates that the two
+     * instances represent the same URI. To define the order the single parts of
+     * the URI are compared with each other. String components will be orderer
+     * in the natural case-sensitive way. A hierarchical URI is less than an
+     * opaque URI and if one part is {@code null} the URI with the undefined
+     * part is less than the other one.
+     *
+     * @param uri
+     *            the URI this instance has to compare with.
+     * @return the value representing the order of the two instances.
+     */
     public int compareTo(URI uri) {
         int ret = 0;
 
@@ -845,6 +954,14 @@
         return 0;
     }
 
+    /**
+     * Parses the given argument {@code uri} and creates an appropriate URI
+     * instance.
+     *
+     * @param uri
+     *            the string which has to be parsed to create the URI instance.
+     * @return the created instance representing the given URI.
+     */
     public static URI create(String uri) {
         URI result = null;
         try {
@@ -923,6 +1040,16 @@
         return first.substring(previndex).equals(second.substring(previndex));
     }
 
+    /**
+     * Compares this URI instance with the given argument {@code o} and
+     * determines if both are equal. Two URI instances are equal if all single
+     * parts are identical in their meaning.
+     *
+     * @param o
+     *            the URI this instance has to be compared with.
+     * @return {@code true} if both URI instances point to the same resource,
+     *         {@code false} otherwise.
+     */
     @Override
     public boolean equals(Object o) {
         if (!(o instanceof URI)) {
@@ -1004,136 +1131,146 @@
         }
     }
 
+    /**
+     * Gets the decoded authority part of this URI.
+     *
+     * @return the decoded authority part or {@code null} if undefined.
+     */
     public String getAuthority() {
         return decode(authority);
     }
 
     /**
-     * Returns the fragment component.
+     * Gets the decoded fragment part of this URI.
      * 
-     * @return String
+     * @return the decoded fragment part or {@code null} if undefined.
      */
     public String getFragment() {
         return decode(fragment);
     }
 
     /**
-     * Returns the host component.
+     * Gets the host part of this URI.
      * 
-     * @return String
+     * @return the host part or {@code null} if undefined.
      */
     public String getHost() {
         return host;
     }
 
     /**
-     * Returns the path component.
+     * Gets the decoded path part of this URI.
      * 
-     * @return String
+     * @return the decoded path part or {@code null} if undefined.
      */
     public String getPath() {
         return decode(path);
     }
 
     /**
-     * Returns the port number.
+     * Gets the port number of this URI.
      * 
-     * @return int
+     * @return the port number or {@code -1} if undefined.
      */
     public int getPort() {
         return port;
     }
 
     /**
-     * Returns the query component.
+     * Gets the decoded query part of this URI.
      * 
-     * @return String
+     * @return the decoded query part or {@code null} if undefined.
      */
     public String getQuery() {
         return decode(query);
     }
 
     /**
-     * Returns the authority component in raw form.
+     * Gets the authority part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded authority part or {@code null} if undefined.
      */
     public String getRawAuthority() {
         return authority;
     }
 
     /**
-     * Returns the fragment component in raw form.
+     * Gets the fragment part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded fragment part or {@code null} if undefined.
      */
     public String getRawFragment() {
         return fragment;
     }
 
     /**
-     * Returns the path component in raw form.
+     * Gets the path part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded path part or {@code null} if undefined.
      */
     public String getRawPath() {
         return path;
     }
 
     /**
-     * Returns the query component in raw form.
+     * Gets the query part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded query part or {@code null} if undefined.
      */
     public String getRawQuery() {
         return query;
     }
 
     /**
-     * Returns the scheme-specific part component in raw form.
+     * Gets the scheme-specific part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded scheme-specific part or {@code null} if undefined.
      */
     public String getRawSchemeSpecificPart() {
         return schemespecificpart;
     }
 
     /**
-     * Returns the user-info component in raw form.
+     * Gets the user-info part of this URI in raw form.
      * 
-     * @return String
+     * @return the encoded user-info part or {@code null} if undefined.
      */
     public String getRawUserInfo() {
         return userinfo;
     }
 
     /**
-     * Returns the scheme.
+     * Gets the scheme part of this URI.
      * 
-     * @return String
+     * @return the scheme part or {@code null} if undefined.
      */
     public String getScheme() {
         return scheme;
     }
 
     /**
-     * Returns the scheme-specific part component.
+     * Gets the decoded scheme-specific part of this URI.
      * 
-     * @return String
+     * @return the decoded scheme-specific part or {@code null} if undefined.
      */
     public String getSchemeSpecificPart() {
         return decode(schemespecificpart);
     }
 
     /**
-     * Returns the userinfo.
+     * Gets the decoded user-info part of this URI.
      * 
-     * @return String
+     * @return the decoded user-info part or {@code null} if undefined.
      */
     public String getUserInfo() {
         return decode(userinfo);
     }
 
+    /**
+     * Gets the hashcode value of this URI instance.
+     *
+     * @return the appropriate hashcode value.
+     */
     @Override
     public int hashCode() {
         if (hash == -1) {
@@ -1143,18 +1280,22 @@
     }
 
     /**
-     * Indicates whether this URI is absolute
+     * Indicates whether this URI is absolute, which means that a scheme part is
+     * defined in this URI.
      * 
-     * @return boolean
+     * @return {@code true} if this URI is absolute, {@code false} otherwise.
      */
     public boolean isAbsolute() {
         return absolute;
     }
 
     /**
-     * Indicates whether this URI is opaque
+     * Indicates whether this URI is opaque or not. An opaque URI is absolute
+     * and has a scheme-specific part which does not start with a slash
+     * character. All parts except scheme, scheme-specific and fragment are
+     * undefined.
      * 
-     * @return true if the URI is opaque, otherwise false
+     * @return {@code true} if the URI is opaque, {@code false} otherwise.
      */
     public boolean isOpaque() {
         return opaque;
@@ -1249,6 +1390,12 @@
         return result;
     }
 
+    /**
+     * Normalizes the path part of this URI.
+     *
+     * @return an URI object which represents this instance with a normalized
+     *         path.
+     */
     public URI normalize() {
         if (opaque) {
             return this;
@@ -1267,9 +1414,14 @@
     }
 
     /**
-     * Return this uri instance if it has already been determined as a
-     * ServerAuthority Otherwise try to parse it again as a server authority to
-     * produce a URISyntaxException with the proper diagnostic message.
+     * Tries to parse the authority component of this URI to divide it into the
+     * host, port, and user-info. If this URI is already determined as a
+     * ServerAuthority this instance will be returned without changes.
+     *
+     * @return this instance with the components of the parsed server authority.
+     * @throws URISyntaxException
+     *             if the authority part could not be parsed as a server-based
+     *             authority.
      */
     public URI parseServerAuthority() throws URISyntaxException {
         if (!serverAuthority) {
@@ -1278,6 +1430,14 @@
         return this;
     }
 
+    /**
+     * Makes the given URI {@code relative} to a relative URI against the URI
+     * represented by this instance.
+     *
+     * @param relative
+     *            the URI which has to be relativized against this URI.
+     * @return the relative URI.
+     */
     public URI relativize(URI relative) {
         if (relative.opaque || opaque) {
             return relative;
@@ -1325,6 +1485,14 @@
         return result;
     }
 
+    /**
+     * Resolves the given URI {@code relative} against the URI represented by
+     * this instance.
+     *
+     * @param relative
+     *            the URI which has to be resolved against this URI.
+     * @return the resolved URI.
+     */
     public URI resolve(URI relative) {
         if (relative.absolute || opaque) {
             return relative;
@@ -1395,6 +1563,16 @@
         string = null;
     }
 
+    /**
+     * Creates a new URI instance by parsing the given string {@code relative}
+     * and resolves the created URI against the URI represented by this
+     * instance.
+     *
+     * @param relative
+     *            the given string to create the new URI instance which has to
+     *            be resolved later on.
+     * @return the created and resolved URI.
+     */
     public URI resolve(String relative) {
         return resolve(create(relative));
     }
@@ -1435,10 +1613,21 @@
         }
     }
 
+    /**
+     * Returns the textual string representation of this URI instance using the
+     * US-ASCII encoding.
+     *
+     * @return the US-ASCII string representation of this URI.
+     */
     public String toASCIIString() {
         return encodeOthers(toString());
     }
 
+    /**
+     * Returns the textual string representation of this URI instance.
+     *
+     * @return the textual string representation of this URI.
+     */
     @Override
     public String toString() {
         if (string == null) {
@@ -1522,6 +1711,14 @@
         return convertHexToLowerCase(result.toString());
     }
 
+    /**
+     * Converts this URI instance to a URL.
+     *
+     * @return the created URL representing the same resource as this URI.
+     * @throws MalformedURLException
+     *             if an error occurs while creating the URL or no protocol
+     *             handler could be found.
+     */
     public URL toURL() throws MalformedURLException {
         if (!absolute) {
             throw new IllegalArgumentException(Msg.getString("K0312") + ": " //$NON-NLS-1$//$NON-NLS-2$

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URIEncoderDecoder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URIEncoderDecoder.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URIEncoderDecoder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URIEncoderDecoder.java Wed May  6 08:33:17 2009
@@ -23,11 +23,10 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class is used to encode a string using the format required by
- * <code>application/x-www-form-urlencoded</code> MIME content type.
- * 
- * It contains helper methods used by the URI class, and performs encoding and
- * decoding in a slightly different way than URLEncoder and URLDecoder.
+ * This class is used to encode a string using the format required by {@code
+ * application/x-www-form-urlencoded} MIME content type. It contains helper
+ * methods used by the URI class, and performs encoding and decoding in a
+ * slightly different way than {@code URLEncoder} and {@code URLDecoder}.
  */
 class URIEncoderDecoder {
 
@@ -37,19 +36,17 @@
 
     /**
      * Validate a string by checking if it contains any characters other than:
-     * 
      * 1. letters ('a'..'z', 'A'..'Z') 2. numbers ('0'..'9') 3. characters in
-     * the legalset parameter 4. others (Unicode characters that are not in
+     * the legalset parameter 4. others (unicode characters that are not in
      * US-ASCII set, and are not ISO Control or are not ISO Space characters)
      * <p>
-     * called from URI.Helper.parseURI() to validate each component
-     * <p>
-     * 
+     * called from {@code URI.Helper.parseURI()} to validate each component
+     *
      * @param s
-     *            java.lang.String the string to be validated
+     *            {@code java.lang.String} the string to be validated
      * @param legal
-     *            java.lang.String the characters allowed in the String s
-     * 
+     *            {@code java.lang.String} the characters allowed in the String
+     *            s
      */
     static void validate(String s, String legal) throws URISyntaxException {
         for (int i = 0; i < s.length();) {
@@ -100,13 +97,12 @@
      * by '%'.
      * <p>
      * For example: '#' -> %23
-     * <p>
-     * Other characters, which are Unicode chars that are not US-ASCII, and are
+     * Other characters, which are unicode chars that are not US-ASCII, and are
      * not ISO Control or are not ISO Space chars, are preserved.
      * <p>
-     * Called from URI.quoteComponent() (for multiple argument constructors)
-     * <p>
-     * 
+     * Called from {@code URI.quoteComponent()} (for multiple argument
+     * constructors)
+     *
      * @param s
      *            java.lang.String the string to be converted
      * @param legal
@@ -146,8 +142,7 @@
      * For example: Euro currency symbol -> "%E2%82%AC".
      * <p>
      * Called from URI.toASCIIString()
-     * <p>
-     * 
+     *
      * @param s
      *            java.lang.String the string to be converted
      * @return java.lang.String the converted string
@@ -171,19 +166,16 @@
     }
 
     /**
-     * Decodes the string argument which is assumed to be encoded in the
-     * <code>x-www-form-urlencoded</code> MIME content type using the UTF-8
-     * encoding scheme.
+     * Decodes the string argument which is assumed to be encoded in the {@code
+     * x-www-form-urlencoded} MIME content type using the UTF-8 encoding scheme.
      * <p>
-     * '%' and two following hex digit characters are converted to the
+     *'%' and two following hex digit characters are converted to the
      * equivalent byte value. All other characters are passed through
      * unmodified.
-     * 
      * <p>
      * e.g. "A%20B%20C %24%25" -> "A B C $%"
      * <p>
      * Called from URI.getXYZ() methods
-     * <p>
      * 
      * @param s
      *            java.lang.String The encoded string.

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URISyntaxException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URISyntaxException.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URISyntaxException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URISyntaxException.java Wed May  6 08:33:17 2009
@@ -20,7 +20,8 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * Represents an exception that occurred during parsing of a URI.
+ * A {@code URISyntaxException} will be thrown if some information could not be parsed
+ * while creating a URI.
  */
 public class URISyntaxException extends Exception {
 
@@ -31,17 +32,21 @@
     private int index;
 
     /**
-     * Constructs a URISyntaxException, containing the input that caused the
-     * exception, a description of the problem, and the index at which the error
-     * occurred.
+     * Constructs a new {@code URISyntaxException} instance containing the
+     * string that caused the exception, a description of the problem and the
+     * index at which the error occurred.
      * 
      * @param input
+     *            the string that caused the exception.
      * @param reason
+     *            the reason why the exception occurred.
      * @param index
-     * @exception NullPointerException
-     *                if input or reason is null
-     * @exception IllegalArgumentException
-     *                if index < -1
+     *            the position where the exception occurred.
+     * @throws NullPointerException
+     *             if one of the arguments {@code input} or {@code reason} is
+     *             {@code null}.
+     * @throws IllegalArgumentException
+     *             if the value for {@code index} is lesser than {@code -1}.
      */
     public URISyntaxException(String input, String reason, int index) {
         super(reason);
@@ -59,14 +64,16 @@
     }
 
     /**
-     * Constructs a URISyntaxException containing the string that caused the
-     * exception and a description of the error.
+     * Constructs a new {@code URISyntaxException} instance containing the
+     * string that caused the exception and a description of the problem.
      * 
-     * @param input
+     *@param input
+     *            the string that caused the exception.
      * @param reason
-     * 
-     * @exception NullPointerException
-     *                if input or reason is null
+     *            the reason why the exception occurred.
+     * @throws NullPointerException
+     *             if one of the arguments {@code input} or {@code reason} is
+     *             {@code null}.
      */
     public URISyntaxException(String input, String reason) {
         super(reason);
@@ -80,39 +87,39 @@
     }
 
     /**
-     * Answers the index at which the syntax error was found, or -1 if the index
-     * is unknown/unavailable.
+     * Gets the index at which the syntax error was found or {@code -1} if the
+     * index is unknown/unavailable.
      * 
-     * @return the index of the syntax error
+     * @return the index of the syntax error.
      */
     public int getIndex() {
         return index;
     }
 
     /**
-     * Answers a String describing the syntax error in the URI string
+     * Gets a description of the syntax error.
      * 
-     * @return a String describing the syntax error
+     * @return the string describing the syntax error.
      */
     public String getReason() {
         return super.getMessage();
     }
 
     /**
-     * Answers the String that contained the syntax error
+     * Gets the initial string that contains an invalid syntax.
      * 
-     * @return the String that caused the exception
+     * @return the string that caused the exception.
      */
     public String getInput() {
         return input;
     }
 
     /**
-     * Returns a description of the exception, including the reason, the string
-     * that had the syntax error, and the index of the syntax error if
+     * Gets a description of the exception, including the reason, the string
+     * that caused the syntax error and the position of the syntax error if
      * available.
      * 
-     * @return a String containing information about the exception.
+     * @return a sting containing information about the exception.
      * @see java.lang.Throwable#getMessage()
      */
     @Override

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URL.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URL.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URL.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URL.java Wed May  6 08:33:17 2009
@@ -29,8 +29,11 @@
 import org.apache.harmony.luni.util.Util;
 
 /**
- * An instance of class URL specifies the location of a resource on the world
- * wide web as specified by RFC 1738.
+ * A URL instance specifies the location of a resource on the internet as
+ * specified by RFC 1738. Such a resource can be a simple file or a service
+ * which generates the output dynamically. A URL is divided in its parts
+ * protocol, host name, port, path, file, user-info, query, reference and
+ * authority. However, not each of this parts has to be defined.
  */
 public final class URL implements java.io.Serializable {
     private static final long serialVersionUID = -7627629688361524110L;
@@ -119,15 +122,16 @@
     private static URLStreamHandlerFactory streamHandlerFactory;
 
     /**
-     * Sets the URL Stream (protocol) handler factory. This method can be
-     * invoked only once during an application's lifetime.
+     * Sets the {@code URLStreamHandlerFactory} which creates protocol specific
+     * stream handlers. This method can be invoked only once during an
+     * application's lifetime. If the {@code URLStreamHandlerFactory} is already
+     * set an {@link Error} will be thrown.
      * <p>
-     * A security check is performed to verify that the current Policy allows
-     * the stream handler factory to be set.
-     * 
+     * A security check is performed to verify whether the current policy allows
+     * to set the stream handler factory.
+     *
      * @param streamFactory
-     *            URLStreamHandlerFactory The factory to use for finding stream
-     *            handlers.
+     *            the factory to be used for creating stream protocol handlers.
      */
     public static synchronized void setURLStreamHandlerFactory(
             URLStreamHandlerFactory streamFactory) {
@@ -143,90 +147,55 @@
     }
 
     /**
-     * Constructs a new URL instance by parsing the specification.
+     * Creates a new URL instance by parsing the string {@code spec}.
      * 
      * @param spec
-     *            java.lang.String a URL specification.
-     * 
+     *            the URL string representation which has to be parsed.
      * @throws MalformedURLException
-     *             if the spec could not be parsed as an URL.
+     *             if the given string {@code spec} could not be parsed as a
+     *             URL.
      */
     public URL(String spec) throws MalformedURLException {
         this((URL) null, spec, (URLStreamHandler) null);
     }
 
     /**
-     * Constructs a new URL by parsing the specification given by
-     * <code>spec</code> and using the context provided by
-     * <code>context</code>.
-     * <p>
-     * The protocol of the specification is obtained by parsing the
-     * <code> spec </code> string.
-     * <p>
-     * If the <code>spec</code> does not specify a protocol:
-     * <ul>
-     * <li>If the context is <code>null</code>, then a
-     * <code>MalformedURLException</code>.</li>
-     * <li>If the context is not <code>null</code>, then the protocol is
-     * obtained from the context.</li>
-     * </ul>
-     * If the <code>spec</code> does specify a protocol:
-     * <ul>
-     * <li>If the context is <code>null</code>, or specifies a different
-     * protocol than the spec, the context is ignored.</li>
-     * <li>If the context is not <code>null</code> and specifies the same
-     * protocol as the specification, the properties of the new <code>URL</code>
-     * are obtained from the context.</li>
-     * </ul>
+     * Creates a new URL to the specified resource {@code spec}. This URL is
+     * relative to the given {@code context}. If the protocol of the parsed URL
+     * does not match with the protocol of the context URL, then the newly
+     * created URL is absolute and bases only on the given URL represented by
+     * {@code spec}. Otherwise the protocol is defined by the context URL.
      * 
      * @param context
-     *            java.net.URL URL to use as context.
+     *            the URL which is used as the context.
      * @param spec
-     *            java.lang.String a URL specification.
-     * 
+     *            the URL string representation which has to be parsed.
      * @throws MalformedURLException
-     *             if the spec could not be parsed as an URL.
+     *             if the given string {@code spec} could not be parsed as a URL
+     *             or an invalid protocol has been found.
      */
     public URL(URL context, String spec) throws MalformedURLException {
         this(context, spec, (URLStreamHandler) null);
     }
 
     /**
-     * Constructs a new URL by parsing the specification given by
-     * <code>spec</code> and using the context provided by
-     * <code>context</code>.
-     * <p>
-     * If the handler argument is non-null, a security check is made to verify
-     * that user-defined protocol handlers can be specified.
-     * <p>
-     * The protocol of the specification is obtained by parsing the
-     * <code> spec </code> string.
-     * <p>
-     * If the <code>spec</code> does not specify a protocol:
-     * <ul>
-     * <li>If the context is <code>null</code>, then a
-     * <code>MalformedURLException</code>.</li>
-     * <li>If the context is not <code>null</code>, then the protocol is
-     * obtained from the context.</li>
-     * </ul>
-     * If the <code>spec</code> does specify a protocol:
-     * <ul>
-     * <li>If the context is <code>null</code>, or specifies a different
-     * protocol than the spec, the context is ignored.</li>
-     * <li>If the context is not <code>null</code> and specifies the same
-     * protocol as the specification, the properties of the new <code>URL</code>
-     * are obtained from the context.</li>
-     * </ul>
+     * Creates a new URL to the specified resource {@code spec}. This URL is
+     * relative to the given {@code context}. The {@code handler} will be used
+     * to parse the URL string representation. If this argument is {@code null}
+     * the default {@code URLStreamHandler} will be used. If the protocol of the
+     * parsed URL does not match with the protocol of the context URL, then the
+     * newly created URL is absolute and bases only on the given URL represented
+     * by {@code spec}. Otherwise the protocol is defined by the context URL.
      * 
      * @param context
-     *            java.net.URL URL to use as context.
+     *            the URL which is used as the context.
      * @param spec
-     *            java.lang.String a URL specification.
+     *            the URL string representation which has to be parsed.
      * @param handler
-     *            java.net.URLStreamHandler a URLStreamHandler.
-     * 
+     *            the specific stream handler to be used by this URL.
      * @throws MalformedURLException
-     *             if the spec could not be parsed as an URL
+     *             if the given string {@code spec} could not be parsed as a URL
+     *             or an invalid protocol has been found.
      */
     public URL(URL context, String spec, URLStreamHandler handler)
             throws MalformedURLException {
@@ -347,17 +316,18 @@
     }
 
     /**
-     * Constructs a new URL instance using the arguments provided.
+     * Creates a new URL instance using the given arguments. The URL uses the
+     * default port for the specified protocol.
      * 
      * @param protocol
-     *            String the protocol for the URL.
+     *            the protocol of the new URL.
      * @param host
-     *            String the name of the host.
+     *            the host name or IP address of the new URL.
      * @param file
      *            the name of the resource.
-     * 
      * @throws MalformedURLException
-     *             if the parameters do not represent a valid URL.
+     *             if the combination of all arguments do not represent a valid
+     *             URL or the protocol is invalid.
      */
     public URL(String protocol, String host, String file)
             throws MalformedURLException {
@@ -365,19 +335,21 @@
     }
 
     /**
-     * Constructs a new URL instance using the arguments provided.
+     * Creates a new URL instance using the given arguments. The URL uses the
+     * specified port instead of the default port for the given protocol.
      * 
      * @param protocol
-     *            String the protocol for the URL.
+     *            the protocol of the new URL.
      * @param host
-     *            String the name of the host.
+     *            the host name or IP address of the new URL.
      * @param port
-     *            int the port number.
+     *            the specific port number of the URL. {@code -1} represents the
+     *            default port of the protocol.
      * @param file
-     *            String the name of the resource.
-     * 
+     *            the name of the resource.
      * @throws MalformedURLException
-     *             if the parameters do not represent a valid URL.
+     *             if the combination of all arguments do not represent a valid
+     *             URL or the protocol is invalid.
      */
     public URL(String protocol, String host, int port, String file)
             throws MalformedURLException {
@@ -385,24 +357,27 @@
     }
 
     /**
-     * Constructs a new URL instance using the arguments provided.
-     * 
-     * If the handler argument is non-null, a security check is made to verify
-     * that user-defined protocol handlers can be specified.
-     * 
+     * Creates a new URL instance using the given arguments. The URL uses the
+     * specified port instead of the default port for the given protocol.
+     *
      * @param protocol
-     *            the protocol for the URL.
+     *            the protocol of the new URL.
      * @param host
-     *            the name of the host.
+     *            the host name or IP address of the new URL.
      * @param port
-     *            the port number.
+     *            the specific port number of the URL. {@code -1} represents the
+     *            default port of the protocol.
      * @param file
      *            the name of the resource.
      * @param handler
-     *            the stream handler that this URL uses.
-     * 
+     *            the stream handler to be used by this URL.
      * @throws MalformedURLException
-     *             if the parameters do not represent an URL.
+     *             if the combination of all arguments do not represent a valid
+     *             URL or the protocol is invalid.
+     * @throws SecurityException
+     *             if {@code handler} is non-{@code null}, and a security
+     *             manager is installed that disallows user-defined protocol
+     *             handlers.
      */
     public URL(String protocol, String host, int port, String file,
             URLStreamHandler handler) throws MalformedURLException {
@@ -478,23 +453,20 @@
     }
 
     /**
-     * Sets the properties of this URL using the provided arguments. This method
-     * is used both within this class and by the <code>URLStreamHandler</code>
-     * code.
+     * Sets the properties of this URL using the provided arguments. Only a
+     * {@code URLStreamHandler} can use this method to set fields of the
+     * existing URL instance. A URL is generally constant.
      * 
      * @param protocol
-     *            the new protocol.
+     *            the protocol to be set.
      * @param host
-     *            the new host name.
+     *            the host name to be set.
      * @param port
-     *            the new port number.
+     *            the port number to be set.
      * @param file
-     *            the new file component.
+     *            the file to be set.
      * @param ref
-     *            the new reference.
-     * 
-     * @see URL
-     * @see URLStreamHandler
+     *            the reference to be set.
      */
     protected void set(String protocol, String host, int port, String file,
             String ref) {
@@ -510,16 +482,18 @@
     }
 
     /**
-     * Compares the argument to the receiver, and answers true if they represent
-     * the same URL. Two URLs are equal if they have the same file, host, port,
-     * protocol, and reference components.
+     * Compares this URL instance with the given argument {@code o} and
+     * determines if both are equal. Two URL instances are equal if all single
+     * parts are identical in their meaning. Compares the argument to the
+     * receiver, and returns true if they represent the same URL. Two URLs are
+     * equal if they have the same file, host, port, protocol, and reference
+     * components.
      * 
      * @param o
-     *            the object to compare with this URL.
-     * @return <code>true</code> if the object is the same as this URL,
-     *         <code>false</code> otherwise.
-     * 
-     * @see #hashCode()
+     *            the URL this instance has to be compared with.
+     * @return {@code true} if both instances represents the same URL, {@code
+     *         false} otherwise.
+     * @see #hashCode
      */
     @Override
     public boolean equals(Object o) {
@@ -536,21 +510,23 @@
     }
 
     /**
-     * Answers true if the receiver and the argument refer to the same file. All
-     * components except the reference are compared.
+     * Returns whether this URL refers to the same resource as the given
+     * argument {@code otherURL}. All URL components except the reference field
+     * are compared.
      * 
      * @param otherURL
-     *            URL to compare against.
-     * @return true if the same resource, false otherwise
+     *            the URL to compare against.
+     * @return {@code true} if both instances refer to the same resource,
+     *         {@code false} otherwise.
      */
     public boolean sameFile(URL otherURL) {
         return strmHandler.sameFile(this, otherURL);
     }
 
     /**
-     * Answers a hash code for this URL object.
+     * Gets the hashcode value of this URL instance.
      * 
-     * @return the hashcode for hashtable indexing
+     * @return the appropriate hashcode value.
      */
     @Override
     public int hashCode() {
@@ -569,7 +545,6 @@
      * one. Senders must check if the strmHandler is null before calling the
      * method if they do not want this behavior (a speed optimization).
      */
-
     void setupStreamHandler() {
         // Check for a cached (previously looked up) handler for
         // the requested protocol.
@@ -631,27 +606,35 @@
     }
 
     /**
-     * Answers an Object representing the resource referenced by this URL.
-     * 
-     * @return The object of the resource pointed by this URL.
+     * Gets the content of the resource which is referred by this URL. By
+     * default one of the following object types will be returned:
+     * <p>
+     * <li>Image for pictures</li>
+     * <li>AudioClip for audio sequences</li>
+     * <li>{@link InputStream} for all other data</li>
      * 
+     * @return the content of the referred resource.
      * @throws IOException
-     *             If an error occurred obtaining the content.
+     *             if an error occurs obtaining the content.
      */
     public final Object getContent() throws IOException {
         return openConnection().getContent();
     }
 
     /**
-     * Answers an Object representing the resource referenced by this URL.
+     * Gets the content of the resource which is referred by this URL. The
+     * argument {@code types} is an array of allowed or expected object types.
+     * {@code null} will be returned if the obtained object type does not match
+     * with one from this list. Otherwise the first type that matches will be
+     * used.
      * 
      * @param types
-     *            The list of acceptable content types
-     * @return The object of the resource pointed by this URL, or null if the
-     *         content does not match a specified content type.
-     * 
+     *            the list of allowed or expected object types.
+     * @return the object representing the resource referred by this URL,
+     *         {@code null} if the content does not match to a specified content
+     *         type.
      * @throws IOException
-     *             If an error occurred obtaining the content.
+     *             if an error occurs obtaining the content.
      */
     // Param not generic in spec
     @SuppressWarnings("unchecked")
@@ -660,60 +643,58 @@
     }
 
     /**
-     * Answers a stream for reading from this URL.
-     * 
-     * @return a stream on the contents of the resource.
+     * Opens an InputStream to read the resource referred by this URL.
      * 
+     * @return the stream which allows to read the resource.
      * @throws IOException
-     *             if a stream could not be created.
+     *             if an error occurs while opening the InputStream.
      */
     public final InputStream openStream() throws java.io.IOException {
         return openConnection().getInputStream();
     }
 
     /**
-     * Creates a connection to this URL using the appropriate ProtocolHandler.
-     * 
-     * @return The connection to this URL.
+     * Opens a connection to the remote resource specified by this URL. This
+     * connection allows bidirectional data transfer.
      * 
+     * @return the connection to this URL.
      * @throws IOException
-     *             if the connection to the URL is not possible.
+     *             if an error occurs while opening the connection.
      */
     public URLConnection openConnection() throws IOException {
         return strmHandler.openConnection(this);
     }
 
     /**
-     * Creates a URI related with this URL
+     * Converts this URL instance into an equivalent URI object.
      * 
-     * @return a URI related to this URL
+     * @return the URI instance that represents this URL.
      * @throws URISyntaxException
-     *             if this URL cannot format into URI
+     *             if this URL cannot be converted into a URI.
      */
     public URI toURI() throws URISyntaxException {
         return new URI(toExternalForm());
     }
 
     /**
-     * The method is the same as <code>openConnection()</code> except that it
-     * uses the <code>proxy</code> to establish a connection to this URL using
-     * appropriate ProtocolHandler.
+     * Opens a connection to the remote resource specified by this URL. The
+     * connection will be established through the given proxy and allows
+     * bidirectional data transfer.
      * 
-     * @return The connection to this URL.
      * @param proxy
-     *            the proxy which is used to make the connection
-     * 
-     * @exception IOException
-     *                thrown if an IO error occurs during connection
-     *                establishment
-     * @exception SecurityException
-     *                thrown if a security manager is installed and it denies
-     *                the permission to connect to the proxy.
-     * @exception IllegalArgumentException
-     *                thrown if the proxy is null or of an invalid type.
-     * @exception UnsupportedOperationException
-     *                thrown if the protocol handler doesn't support this
-     *                method.
+     *            the proxy through which the connection will be established.
+     * @return the appropriate URLconnection instance representing the
+     *         connection to this URL.
+     * @throws IOException
+     *             if an I/O error occurs while opening the connection.
+     * @throws SecurityException
+     *             if a security manager is installed and it denies to connect
+     *             to the proxy.
+     * @throws IllegalArgumentException
+     *             if the argument proxy is {@code null} or is an invalid type.
+     * @throws UnsupportedOperationException
+     *             if the protocol handler does not support opening connections
+     *             through proxies.
      */
     public URLConnection openConnection(Proxy proxy) throws IOException {
         if (null == proxy) {
@@ -723,10 +704,11 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
+     * Returns a string containing a concise, human-readable representation of
+     * this URL. The returned string is the same as the result of the method
+     * {@code toExternalForm()}.
      * 
-     * @return a printable representation for the receiver.
+     * @return the string representation of this URL.
      */
     @Override
     public String toString() {
@@ -734,13 +716,10 @@
     }
 
     /**
-     * Create and return the String representation of this URL.
-     * 
-     * @return the external representation of this URL.
+     * Returns a string containing a concise, human-readable representation of
+     * this URL.
      * 
-     * @see #toString()
-     * @see URL
-     * @see URLStreamHandler#toExternalForm(URL)
+     * @return the string representation of this URL.
      */
     public String toExternalForm() {
         if (strmHandler == null) {
@@ -793,10 +772,9 @@
      * <p>
      * Note that, we really only need the readObject method but the spec that
      * says readObject will be ignored if no writeObject is present.
-     * 
+     *
      * @param s
-     *            the stream to write to.
-     * 
+     *            the stream to write on.
      * @throws IOException
      *             if an IO Exception occurs during the write.
      */
@@ -805,110 +783,108 @@
     }
 
     /**
-     * Answers the file component of this URL.
+     * Gets the value of the file part of this URL.
      * 
-     * @return the receiver's file.
+     * @return the file name this URL refers to or an empty string if the file
+     *         part is not set.
      */
     public String getFile() {
         return file;
     }
 
     /**
-     * Answers the host component of this URL.
+     * Gets the value of the host part of this URL.
      * 
-     * @return the receiver's host.
+     * @return the host name or IP address of this URL.
      */
     public String getHost() {
         return host;
     }
 
     /**
-     * Answers the port component of this URL.
+     * Gets the port number of this URL or {@code -1} if the port is not set.
      * 
-     * @return the receiver's port.
+     * @return the port number of this URL.
      */
     public int getPort() {
         return port;
     }
 
     /**
-     * Answers the protocol component of this URL.
+     * Gets the protocol of this URL.
      * 
-     * @return the receiver's protocol.
+     * @return the protocol type of this URL.
      */
     public String getProtocol() {
         return protocol;
     }
 
     /**
-     * Answers the reference component of this URL.
+     * Gets the value of the reference part of this URL.
      * 
-     * @return the receiver's reference component.
+     * @return the reference part of this URL.
      */
     public String getRef() {
         return ref;
     }
 
     /**
-     * Answers the query component of this URL.
+     * Gets the value of the query part of this URL.
      * 
-     * @return the receiver's query.
+     * @return the query part of this URL.
      */
     public String getQuery() {
         return query;
     }
 
     /**
-     * Answers the path component of this URL.
+     * Gets the value of the path part of this URL.
      * 
-     * @return the receiver's path.
+     * @return the path part of this URL.
      */
     public String getPath() {
         return path;
     }
 
     /**
-     * Answers the user info component of this URL.
+     * Gets the value of the user-info part of this URL.
      * 
-     * @return the receiver's user info.
+     * @return the user-info part of this URL.
      */
     public String getUserInfo() {
         return userInfo;
     }
 
     /**
-     * Answers the authority component of this URL.
+     * Gets the value of the authority part of this URL.
      * 
-     * @return the receiver's authority.
+     * @return the authority part of this URL.
      */
     public String getAuthority() {
         return authority;
     }
 
     /**
-     * Sets the properties of this URL using the provided arguments. This method
-     * is used both within this class and by the <code>URLStreamHandler</code>
-     * code.
+     * Sets the properties of this URL using the provided arguments. Only a
+     * {@code URLStreamHandler} can use this method to set fields of the
+     * existing URL instance. A URL is generally constant.
      * 
      * @param protocol
-     *            the new protocol.
+     *            the protocol to be set.
      * @param host
-     *            the new host name.
+     *            the host name to be set.
      * @param port
-     *            the new port number.
+     *            the port number to be set.
      * @param authority
-     *            the new authority.
+     *            the authority to be set.
      * @param userInfo
-     *            the new user info.
+     *            the user-info to be set.
      * @param path
-     *            the new path component.
+     *            the path to be set.
      * @param query
-     *            the new query.
+     *            the query to be set.
      * @param ref
-     *            the new reference.
-     * 
-     * @see URL
-     * @see URLStreamHandler
+     *            the reference to be set.
      */
     protected void set(String protocol, String host, int port,
             String authority, String userInfo, String path, String query,
@@ -929,10 +905,11 @@
     }
 
     /**
-     * Returns the default port for this URL as defined by the URLStreamHandler.
-     * 
-     * @return the default port for this URL
-     * 
+     * Gets the default port number of the protocol used by this URL. If no
+     * default port is defined by the protocol or the {@code URLStreamHandler},
+     * {@code -1} will be returned.
+     *
+     * @return the default port number according to the protocol of this URL.
      * @see URLStreamHandler#getDefaultPort
      */
     public int getDefaultPort() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLClassLoader.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLClassLoader.java?rev=772095&r1=772094&r2=772095&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLClassLoader.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/URLClassLoader.java Wed May  6 08:33:17 2009
@@ -51,8 +51,8 @@
 /**
  * This class loader is responsible for loading classes and resources from a
  * list of URLs which can refer to either directories or JAR files. Classes
- * loaded by this <code>URLClassLoader</code> are granted permission to access
- * the URLs contained in the URL search list.
+ * loaded by this {@code URLClassLoader} are granted permission to access the
+ * URLs contained in the URL search list.
  */
 public class URLClassLoader extends SecureClassLoader {
 
@@ -79,15 +79,18 @@
         }
 
         /**
-         * Overrides the loadClass() of <code>ClassLoader</code>. It calls
-         * the security manager's <code>checkPackageAccess()</code> before
+         * Overrides the {@code loadClass()} of {@code ClassLoader}. It calls
+         * the security manager's {@code checkPackageAccess()} before
          * attempting to load the class.
          *
-         * @param className    String the name of the class to search for.
-         * @param resolveClass boolean indicates if class should be resolved after
-         *                     loading.
          * @return the Class object.
-         * @throws ClassNotFoundException If the class could not be found.
+         * @param className
+         *            String the name of the class to search for.
+         * @param resolveClass
+         *            boolean indicates if class should be resolved after
+         *            loading.
+         * @throws ClassNotFoundException
+         *             If the class could not be found.
          */
         @Override
         protected synchronized Class<?> loadClass(String className,
@@ -600,35 +603,37 @@
 
 
     /**
-     * Constructs a new instance of this class. The newly created instance will
-     * have the system ClassLoader as its parent. URLs that end with "/" are
-     * assumed to be directories, otherwise they are assumed to be Jar files.
-     * 
+     * Constructs a new {@code URLClassLoader} instance. The newly created
+     * instance will have the system ClassLoader as its parent. URLs that end
+     * with "/" are assumed to be directories, otherwise they are assumed to be
+     * JAR files.
+     *
      * @param urls
-     *            the URLs to search
-     * 
+     *            the list of URLs where a specific class or file could be
+     *            found.
      * @throws SecurityException
-     *             if a security manager exists and its checkCreateClassLoader
-     *             method doesn't allow creation of new ClassLoaders
+     *             if a security manager exists and its {@code
+     *             checkCreateClassLoader()} method doesn't allow creation of
+     *             new ClassLoaders.
      */
     public URLClassLoader(URL[] urls) {
         this(urls, ClassLoader.getSystemClassLoader(), null);
     }
 
     /**
-     * Constructs a new instance of this class. The newly created instance will
-     * have the specified ClassLoader as its parent. URLs that end with "/" are
-     * assumed to be directories, otherwise they are assumed to be Jar files.
+     * Constructs a new URLClassLoader instance. The newly created instance will
+     * have the system ClassLoader as its parent. URLs that end with "/" are
+     * assumed to be directories, otherwise they are assumed to be JAR files.
      * 
      * @param urls
-     *            the URLs to search
-     * 
+     *            the list of URLs where a specific class or file could be
+     *            found.
      * @param parent
-     *            the ClassLoader to assign as this loader's parent.
-     * 
+     *            the class loader to assign as this loader's parent.
      * @throws SecurityException
-     *             if a security manager exists and its checkCreateClassLoader
-     *             method doesn't allow creation of new ClassLoaders
+     *             if a security manager exists and its {@code
+     *             checkCreateClassLoader()} method doesn't allow creation of
+     *             new class loaders.
      */
     public URLClassLoader(URL[] urls, ClassLoader parent) {
         this(urls, parent, null);
@@ -637,7 +642,8 @@
     /**
      * Adds the specified URL to the search list.
      *
-     * @param url java.net.URL the new URL
+     * @param url
+     *            the URL which is to add.
      */
     protected void addURL(URL url) {
         try {
@@ -648,13 +654,13 @@
     }
 
     /**
-     * Answers an enumeration of URLs that contain the specified resource.
+     * Returns all known URLs which point to the specified resource.
      *
-     * @param name java.lang.String the name of the requested resource
-     * @return Enumeration the enumeration of URLs that contain the specified
-     *         resource.
+     * @param name
+     *            the name of the requested resource.
+     * @return the enumeration of URLs which point to the specified resource.
      * @throws IOException
-     *             thrown if an IO Exception occurs while attempting to connect
+     *             if an I/O error occurs while attempting to connect.
      */
     @Override
     public Enumeration<URL> findResources(final String name) throws IOException {
@@ -702,7 +708,8 @@
     /**
      * Converts an input stream into a byte array.
      *
-     * @param is the input stream
+     * @param is
+     *            the input stream
      * @return byte[] the byte array
      */
     private static byte[] getBytes(InputStream is)
@@ -717,15 +724,16 @@
     }
 
     /**
-     * Answers the permissions for the given code source. First this method
-     * retrieves the permissions from the system policy. If the protocol is
-     * "file:/" then a new permission, <code>FilePermission</code>, granting
-     * the read permission to the file is added to the permission collection.
+     * Gets all permissions for the specified {@code codesource}. First, this
+     * method retrieves the permissions from the system policy. If the protocol
+     * is "file:/" then a new permission, {@code FilePermission}, granting the
+     * read permission to the file is added to the permission collection.
      * Otherwise, connecting to and accepting connections from the URL is
      * granted.
      *
-     * @param codesource CodeSource
-     * @return PermissionCollection
+     * @param codesource
+     *            the code source object whose permissions have to be known.
+     * @return the list of permissions according to the code source object.
      */
     @Override
     protected PermissionCollection getPermissions(final CodeSource codesource) {
@@ -766,9 +774,9 @@
     }
 
     /**
-     * Answers the search list of this URLClassLoader
+     * Returns the search list of this {@code URLClassLoader}.
      *
-     * @return java.net.URL[]
+     * @return the list of all known URLs of this instance.
      */
     public URL[] getURLs() {
         return originalUrls.toArray(new URL[originalUrls.size()]);
@@ -776,9 +784,6 @@
 
     /**
      * Determines if the URL is pointing to a directory.
-     *
-     * @param url java.net.URL
-     * @return boolean
      */
     private static boolean isDirectory(URL url) {
         String file = url.getFile();
@@ -786,15 +791,15 @@
     }
 
     /**
-     * Answers an instance of <code>URLClassLoader</code>.
-     * <code>loadClass()</code> of the new instance will call the
-     * SecurityManager's <code>checkPackageAccess()</code> before loading a
-     * class.
+     * Returns a new {@code URLClassLoader} instance for the given URLs and the
+     * system {@code ClassLoader} as its parent. The method {@code loadClass()}
+     * of the new instance will call {@code
+     * SecurityManager.checkPackageAccess()} before loading a class.
      *
-     * @param urls java.net.URL[] a list of URLs that is passed to the new
-     *             URLClassloader
-     * @return java.net.URLClassLoader the new instance of
-     *         <code>URLClassLoader</code>
+     * @param urls
+     *            the list of URLs that is passed to the new {@code
+     *            URLClassloader}.
+     * @return the created {@code URLClassLoader} instance.
      */
     public static URLClassLoader newInstance(final URL[] urls) {
         URLClassLoader sub = AccessController
@@ -808,15 +813,17 @@
     }
 
     /**
-     * Answers an instance of <code>URLClassLoader</code>.
-     * <code>loadClass()</code> of the new instance will call security
-     * manager's <code>checkPackageAccess()</code> before loading a class.
+     * Returns a new {@code URLClassLoader} instance for the given URLs and the
+     * specified {@code ClassLoader} as its parent. The method {@code
+     * loadClass()} of the new instance will call the SecurityManager's {@code
+     * checkPackageAccess()} before loading a class.
      *
-     * @param urls     URL[] the list of URLs that is passed to the new
-     *                 <code>URLClassloader</code>
-     * @param parentCl ClassLoader the parent class loader that is passed to
-                       the new <code>URLClassloader</code>
-     * @return URLClassLoader the new instance of <code>URLClassLoader</code>
+     * @param urls
+     *            the list of URLs that is passed to the new URLClassloader.
+     * @param parentCl
+     *            the parent class loader that is passed to the new
+     *            URLClassloader.
+     * @return the created {@code URLClassLoader} instance.
      */
     public static URLClassLoader newInstance(final URL[] urls,
                                              final ClassLoader parentCl) {
@@ -831,24 +838,24 @@
     }
 
     /**
-     * Constructs a new instance of this class. The newly created instance will
-     * have the specified ClassLoader as its parent and use the specified
-     * factory to create stream handlers. URLs that end with "/" are assumed to
-     * be directories, otherwise they are assumed to be Jar files.
+     * Constructs a new {@code URLClassLoader} instance. The newly created
+     * instance will have the specified {@code ClassLoader} as its parent and
+     * use the specified factory to create stream handlers. URLs that end with
+     * "/" are assumed to be directories, otherwise they are assumed to be JAR
+     * files.
      * 
      * @param searchUrls
-     *            java.net.URL[] the URLs that will be searched in the order
-     *            they were specified for resource
-     * 
+     *            the list of URLs where a specific class or file could be
+     *            found.
      * @param parent
-     *            ClassLoader the ClassLoader name of the resource to find.
-     * 
+     *            the {@code ClassLoader} to assign as this loader's parent.
      * @param factory
-     *            java.net.URLStreamHandlerFactory the factory that will used to
-     *            create stream (protocol) handlers
+     *            the factory that will be used to create protocol-specific
+     *            stream handlers.
      * @throws SecurityException
-     *             if a security manager exists and its checkCreateClassLoader
-     *             method doesn't allow creation of new ClassLoaders
+     *             if a security manager exists and its {@code
+     *             checkCreateClassLoader()} method doesn't allow creation of
+     *             new {@code ClassLoader}s.
      */
     public URLClassLoader(URL[] searchUrls, ClassLoader parent,
                           URLStreamHandlerFactory factory) {
@@ -875,13 +882,15 @@
     }
 
     /**
-     * Locates and loads the specified class, searching this URLClassLoader's
-     * list of URLS.
+     * Tries to locate and load the specified class using the known URLs. If the
+     * class could be found, a class object representing the loaded class will
+     * be returned.
      *
-     * @param clsName String the name of the class.
-     * @return Class the class that has been loaded.
-     * @throws java.lang.ClassNotFoundException
-     *          if the class cannot be loaded
+     * @param clsName
+     *            the name of the class which has to be found.
+     * @return the class that has been loaded.
+     * @throws ClassNotFoundException
+     *             if the specified class cannot be loaded.
      */
     @Override
     protected Class<?> findClass(final String clsName)
@@ -899,7 +908,7 @@
     }
 
     /**
-     * Answers an URL that will be checked if it contains the class or resource.
+     * Returns an URL that will be checked if it contains the class or resource.
      * If the file component of the URL is not a directory, a Jar URL will be
      * created.
      *
@@ -926,11 +935,12 @@
     }
 
     /**
-     * Answers a URL referencing the specified resource or null if no resource
-     * could be found.
+     * Returns an URL referencing the specified resource or {@code null} if the
+     * resource could not be found.
      *
-     * @param name java.lang.String the name of the requested resource
-     * @return URL URL for the resource.
+     * @param name
+     *            the name of the requested resource.
+     * @return the URL which points to the given resource.
      */
     @Override
     public URL findResource(final String name) {
@@ -956,7 +966,7 @@
     }
 
     /**
-     * Answers a URL among the given ones referencing the specified resource or
+     * Returns a URL among the given ones referencing the specified resource or
      * null if no resource could be found.
      *
      * @param resName java.lang.String the name of the requested resource
@@ -1065,14 +1075,19 @@
     }
 
     /**
-     * Define a new Package using information extracted from the specified
-     * Manifest.
+     * Defines a new package using the information extracted from the specified
+     * manifest.
      *
-     * @param packageName The name of the package
-     * @param manifest    The Manifest for the Package
-     * @param url         The code source for the Package
-     * @return The Package created
-     * @throws IllegalArgumentException if the Package already exists
+     * @param packageName
+     *            the name of the new package.
+     * @param manifest
+     *            the manifest containing additional information for the new
+     *            package.
+     * @param url
+     *            the URL to the code source for the new package.
+     * @return the created package.
+     * @throws IllegalArgumentException
+     *             if a package with the given name already exists.
      */
     protected Package definePackage(String packageName, Manifest manifest,
                                     URL url) throws IllegalArgumentException {
@@ -1144,8 +1159,10 @@
     /**
      * returns URLs referenced in the string classpath.
      *
-     * @param root      the jar URL that classpath is related to
-     * @param classpath the relative URLs separated by spaces
+     * @param root
+     *            the jar URL that classpath is related to
+     * @param classpath
+     *            the relative URLs separated by spaces
      * @return URL[] the URLs contained in the string classpath.
      */
     private ArrayList<URL> getInternalURLs(URL root, String classpath) {



Mime
View raw message