You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/05/06 10:33:22 UTC
svn commit: r772095 [5/6] -
/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/net/
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("www.company.com:7000-", "connect", "accept")
+ * {@code SocketPermission("www.company.com:7000-", "connect,accept")}
* </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) {