diff -r f2358d18923a -r 1d9cb0d080e3 jdk/src/share/classes/java/net/URL.java --- a/jdk/src/share/classes/java/net/URL.java Mon Jul 29 19:36:54 2013 -0700 +++ b/jdk/src/share/classes/java/net/URL.java Tue Jul 30 11:04:19 2013 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1995, 2012, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -32,7 +32,7 @@ import sun.security.util.SecurityConstants; /** - * Class URL represents a Uniform Resource + * Class {@code URL} represents a Uniform Resource * Locator, a pointer to a "resource" on the World * Wide Web. A resource can be something as simple as a file or a * directory, or it can be a reference to a more complicated object, @@ -49,10 +49,10 @@ * *

* The URL above indicates that the protocol to use is - * http (HyperText Transfer Protocol) and that the + * {@code http} (HyperText Transfer Protocol) and that the * information resides on a host machine named - * www.example.com. The information on that host - * machine is named /docs/resource1.html. The exact + * {@code www.example.com}. The information on that host + * machine is named {@code /docs/resource1.html}. The exact * meaning of this name on the host machine is both protocol * dependent and host dependent. The information normally resides in * a file, but it could be generated on the fly. This component of @@ -62,13 +62,13 @@ * port number to which the TCP connection is made on the remote host * machine. If the port is not specified, the default port for * the protocol is used instead. For example, the default port for - * http is 80. An alternative port could be + * {@code http} is {@code 80}. An alternative port could be * specified as: * 

  *     http://www.example.com:1080/docs/resource1.html
  *
*

- * The syntax of URL is defined by RFC 2396: Uniform * Resource Identifiers (URI): Generic Syntax, amended by RFC 2732: Format for @@ -86,7 +86,7 @@ * This fragment is not technically part of the URL. Rather, it * indicates that after the specified resource is retrieved, the * application is specifically interested in that part of the - * document that has the tag chapter1 attached to it. The + * document that has the tag {@code chapter1} attached to it. The * meaning of a tag is resource specific. *

* An application can also specify a "relative URL", @@ -170,8 +170,8 @@ private int port = -1; /** - * The specified file name on that host. file is - * defined as path[?query] + * The specified file name on that host. {@code file} is + * defined as {@code path[?query]} * @serial */ private String file; @@ -220,42 +220,42 @@ private int hashCode = -1; /** - * Creates a URL object from the specified - * protocol, host, port - * number, and file.

+ * Creates a {@code URL} object from the specified + * {@code protocol}, {@code host}, {@code port} + * number, and {@code file}.

* - * host can be expressed as a host name or a literal + * {@code host} can be expressed as a host name or a literal * IP address. If IPv6 literal address is used, it should be - * enclosed in square brackets ('[' and ']'), as + * enclosed in square brackets ({@code '['} and {@code ']'}), as * specified by RFC 2732; * However, the literal IPv6 address format defined in RFC 2373: IP * Version 6 Addressing Architecture is also accepted.

* - * Specifying a port number of -1 + * Specifying a {@code port} number of {@code -1} * indicates that the URL should use the default port for the * protocol.

* * If this is the first URL object being created with the specified * protocol, a stream protocol handler object, an instance of - * class URLStreamHandler, is created for that protocol: + * class {@code URLStreamHandler}, is created for that protocol: *

    *
  1. If the application has previously set up an instance of - * URLStreamHandlerFactory as the stream handler factory, - * then the createURLStreamHandler method of that instance + * {@code URLStreamHandlerFactory} as the stream handler factory, + * then the {@code createURLStreamHandler} method of that instance * is called with the protocol string as an argument to create the * stream protocol handler. - *
  2. If no URLStreamHandlerFactory has yet been set up, - * or if the factory's createURLStreamHandler method - * returns null, then the constructor finds the + *
  3. If no {@code URLStreamHandlerFactory} has yet been set up, + * or if the factory's {@code createURLStreamHandler} method + * returns {@code null}, then the constructor finds the * value of the system property: * 
          *         java.protocol.handler.pkgs
      *
    - * If the value of that system property is not null, + * If the value of that system property is not {@code null}, * it is interpreted as a list of packages separated by a vertical - * slash character '|'. The constructor tries to load + * slash character '{@code |}'. The constructor tries to load * the class named: * 
          *         <package>.<protocol>.Handler
@@ -263,7 +263,7 @@
      *     where <package> is replaced by the name of the package
      *     and <protocol> is replaced by the name of the protocol.
      *     If this class does not exist, or if the class exists but it is not
-     *     a subclass of URLStreamHandler, then the next package
+     *     a subclass of {@code URLStreamHandler}, then the next package
      *     in the list is tried.
      * 
  4. If the previous step fails to find a protocol handler, then the
      *     constructor tries to load from a system default package.
@@ -271,8 +271,8 @@
      *         <system default package>.<protocol>.Handler
      *
    5. * If this class does not exist, or if the class exists but it is not a - * subclass of URLStreamHandler, then a - * MalformedURLException is thrown. + * subclass of {@code URLStreamHandler}, then a + * {@code MalformedURLException} is thrown. *
* *

Protocol handlers for the following protocols are guaranteed @@ -304,13 +304,13 @@ } /** - * Creates a URL from the specified protocol - * name, host name, and file name. The + * Creates a URL from the specified {@code protocol} + * name, {@code host} name, and {@code file} name. The * default port for the specified protocol is used. *

* This method is equivalent to calling the four-argument - * constructor with the arguments being protocol, - * host, -1, and file. + * constructor with the arguments being {@code protocol}, + * {@code host}, {@code -1}, and {@code file}. * * No validation of the inputs is performed by this constructor. * @@ -327,21 +327,21 @@ } /** - * Creates a URL object from the specified - * protocol, host, port - * number, file, and handler. Specifying - * a port number of -1 indicates that + * Creates a {@code URL} object from the specified + * {@code protocol}, {@code host}, {@code port} + * number, {@code file}, and {@code handler}. Specifying + * a {@code port} number of {@code -1} indicates that * the URL should use the default port for the protocol. Specifying - * a handler of null indicates that the URL + * a {@code handler} of {@code null} indicates that the URL * should use a default stream handler for the protocol, as outlined * for: * java.net.URL#URL(java.lang.String, java.lang.String, int, * java.lang.String) * *

If the handler is not null and there is a security manager, - * the security manager's checkPermission + * the security manager's {@code checkPermission} * method is called with a - * NetPermission("specifyStreamHandler") permission. + * {@code NetPermission("specifyStreamHandler")} permission. * This may result in a SecurityException. * * No validation of the inputs is performed by this constructor. @@ -354,7 +354,7 @@ * @exception MalformedURLException if an unknown protocol is specified. * @exception SecurityException * if a security manager exists and its - * checkPermission method doesn't allow + * {@code checkPermission} method doesn't allow * specifying a stream handler explicitly. * @see java.lang.System#getProperty(java.lang.String) * @see java.net.URL#setURLStreamHandlerFactory( @@ -417,15 +417,15 @@ } /** - * Creates a URL object from the String + * Creates a {@code URL} object from the {@code String} * representation. *

* This constructor is equivalent to a call to the two-argument - * constructor with a null first argument. + * constructor with a {@code null} first argument. * - * @param spec the String to parse as a URL. + * @param spec the {@code String} to parse as a URL. * @exception MalformedURLException if no protocol is specified, or an - * unknown protocol is found, or spec is null. + * unknown protocol is found, or {@code spec} is {@code null}. * @see java.net.URL#URL(java.net.URL, java.lang.String) */ public URL(String spec) throws MalformedURLException { @@ -470,9 +470,9 @@ * For a more detailed description of URL parsing, refer to RFC2396. * * @param context the context in which to parse the specification. - * @param spec the String to parse as a URL. + * @param spec the {@code String} to parse as a URL. * @exception MalformedURLException if no protocol is specified, or an - * unknown protocol is found, or spec is null. + * unknown protocol is found, or {@code spec} is {@code null}. * @see java.net.URL#URL(java.lang.String, java.lang.String, * int, java.lang.String) * @see java.net.URLStreamHandler @@ -489,13 +489,13 @@ * occurs as with the two argument constructor. * * @param context the context in which to parse the specification. - * @param spec the String to parse as a URL. + * @param spec the {@code String} to parse as a URL. * @param handler the stream handler for the URL. * @exception MalformedURLException if no protocol is specified, or an - * unknown protocol is found, or spec is null. + * unknown protocol is found, or {@code spec} is {@code null}. * @exception SecurityException * if a security manager exists and its - * checkPermission method doesn't allow + * {@code checkPermission} method doesn't allow * specifying a stream handler. * @see java.net.URL#URL(java.lang.String, java.lang.String, * int, java.lang.String) @@ -719,9 +719,9 @@ } /** - * Gets the query part of this URL. + * Gets the query part of this {@code URL}. * - * @return the query part of this URL, + * @return the query part of this {@code URL}, * or null if one does not exist * @since 1.3 */ @@ -730,9 +730,9 @@ } /** - * Gets the path part of this URL. + * Gets the path part of this {@code URL}. * - * @return the path part of this URL, or an + * @return the path part of this {@code URL}, or an * empty string if one does not exist * @since 1.3 */ @@ -741,9 +741,9 @@ } /** - * Gets the userInfo part of this URL. + * Gets the userInfo part of this {@code URL}. * - * @return the userInfo part of this URL, or + * @return the userInfo part of this {@code URL}, or * null if one does not exist * @since 1.3 */ @@ -752,9 +752,9 @@ } /** - * Gets the authority part of this URL. + * Gets the authority part of this {@code URL}. * - * @return the authority part of this URL + * @return the authority part of this {@code URL} * @since 1.3 */ public String getAuthority() { @@ -762,7 +762,7 @@ } /** - * Gets the port number of this URL. + * Gets the port number of this {@code URL}. * * @return the port number, or -1 if the port is not set */ @@ -772,7 +772,7 @@ /** * Gets the default port number of the protocol associated - * with this URL. If the URL scheme or the URLStreamHandler + * with this {@code URL}. If the URL scheme or the URLStreamHandler * for the URL do not define a default port number, * then -1 is returned. * @@ -784,35 +784,35 @@ } /** - * Gets the protocol name of this URL. + * Gets the protocol name of this {@code URL}. * - * @return the protocol of this URL. + * @return the protocol of this {@code URL}. */ public String getProtocol() { return protocol; } /** - * Gets the host name of this URL, if applicable. + * Gets the host name of this {@code URL}, if applicable. * The format of the host conforms to RFC 2732, i.e. for a * literal IPv6 address, this method will return the IPv6 address - * enclosed in square brackets ('[' and ']'). + * enclosed in square brackets ({@code '['} and {@code ']'}). * - * @return the host name of this URL. + * @return the host name of this {@code URL}. */ public String getHost() { return host; } /** - * Gets the file name of this URL. + * Gets the file name of this {@code URL}. * The returned file portion will be * the same as getPath(), plus the concatenation of * the value of getQuery(), if any. If there is * no query portion, this method and getPath() will * return identical results. * - * @return the file name of this URL, + * @return the file name of this {@code URL}, * or an empty string if one does not exist */ public String getFile() { @@ -821,10 +821,10 @@ /** * Gets the anchor (also known as the "reference") of this - * URL. + * {@code URL}. * * @return the anchor (also known as the "reference") of this - * URL, or null if one does not exist + * {@code URL}, or null if one does not exist */ public String getRef() { return ref; @@ -834,7 +834,7 @@ * Compares this URL for equality with another object.

* * If the given object is not a URL then this method immediately returns - * false.

+ * {@code false}.

* * Two URL objects are equal if they have the same protocol, reference * equivalent hosts, have the same port number on the host, and the same @@ -848,12 +848,12 @@ * Since hosts comparison requires name resolution, this operation is a * blocking operation.

* - * Note: The defined behavior for equals is known to + * Note: The defined behavior for {@code equals} is known to * be inconsistent with virtual hosting in HTTP. * * @param obj the URL to compare against. - * @return true if the objects are the same; - * false otherwise. + * @return {@code true} if the objects are the same; + * {@code false} otherwise. */ public boolean equals(Object obj) { if (!(obj instanceof URL)) @@ -869,7 +869,7 @@ * The hash code is based upon all the URL components relevant for URL * comparison. As such, this operation is a blocking operation.

* - * @return a hash code for this URL. + * @return a hash code for this {@code URL}. */ public synchronized int hashCode() { if (hashCode != -1) @@ -882,21 +882,21 @@ /** * Compares two URLs, excluding the fragment component.

* - * Returns true if this URL and the - * other argument are equal without taking the + * Returns {@code true} if this {@code URL} and the + * {@code other} argument are equal without taking the * fragment component into consideration. * - * @param other the URL to compare against. - * @return true if they reference the same remote object; - * false otherwise. + * @param other the {@code URL} to compare against. + * @return {@code true} if they reference the same remote object; + * {@code false} otherwise. */ public boolean sameFile(URL other) { return handler.sameFile(this, other); } /** - * Constructs a string representation of this URL. The - * string is created by calling the toExternalForm + * Constructs a string representation of this {@code URL}. The + * string is created by calling the {@code toExternalForm} * method of the stream protocol handler for this object. * * @return a string representation of this object. @@ -909,8 +909,8 @@ } /** - * Constructs a string representation of this URL. The - * string is created by calling the toExternalForm + * Constructs a string representation of this {@code URL}. The + * string is created by calling the {@code toExternalForm} * method of the stream protocol handler for this object. * * @return a string representation of this object. @@ -924,7 +924,7 @@ /** * Returns a {@link java.net.URI} equivalent to this URL. - * This method functions in the same way as new URI (this.toString()). + * This method functions in the same way as {@code new URI (this.toString())}. *

Note, any URL instance that complies with RFC 2396 can be converted * to a URI. However, some URLs that are not strictly in compliance * can not be converted to a URI. @@ -984,7 +984,7 @@ * @param proxy the Proxy through which this connection * will be made. If direct connection is desired, * Proxy.NO_PROXY should be specified. - * @return a URLConnection to the URL. + * @return a {@code URLConnection} to the URL. * @exception IOException if an I/O exception occurs. * @exception SecurityException if a security manager is present * and the caller doesn't have permission to connect @@ -1022,8 +1022,8 @@ } /** - * Opens a connection to this URL and returns an - * InputStream for reading from that connection. This + * Opens a connection to this {@code URL} and returns an + * {@code InputStream} for reading from that connection. This * method is a shorthand for: * 

      *     openConnection().getInputStream()
@@ -1077,22 +1077,22 @@
     static URLStreamHandlerFactory factory;
 
     /**
-     * Sets an application's URLStreamHandlerFactory.
+     * Sets an application's {@code URLStreamHandlerFactory}.
      * This method can be called at most once in a given Java Virtual
      * Machine.
      *
-     *
 The URLStreamHandlerFactory instance is used to
+     *
 The {@code URLStreamHandlerFactory} instance is used to
      *construct a stream protocol handler from a protocol name.
      *
      * 
 If there is a security manager, this method first calls
-     * the security manager's checkSetFactory method
+     * the security manager's {@code checkSetFactory} method
      * to ensure the operation is allowed.
      * This could result in a SecurityException.
      *
      * @param      fac   the desired factory.
      * @exception  Error  if the application has already set a factory.
      * @exception  SecurityException  if a security manager exists and its
-     *             checkSetFactory method doesn't allow
+     *             {@code checkSetFactory} method doesn't allow
      *             the operation.
      * @see        java.net.URL#URL(java.lang.String, java.lang.String,
      *             int, java.lang.String)