--- 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 <code>URL</code> 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 @@
* </pre></blockquote>
* <p>
* The URL above indicates that the protocol to use is
- * <code>http</code> (HyperText Transfer Protocol) and that the
+ * {@code http} (HyperText Transfer Protocol) and that the
* information resides on a host machine named
- * <code>www.example.com</code>. The information on that host
- * machine is named <code>/docs/resource1.html</code>. 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
- * <code>http</code> is <code>80</code>. An alternative port could be
+ * {@code http} is {@code 80}. An alternative port could be
* specified as:
* <blockquote><pre>
* http://www.example.com:1080/docs/resource1.html
* </pre></blockquote>
* <p>
- * The syntax of <code>URL</code> is defined by <a
+ * The syntax of {@code URL} is defined by <a
* href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC 2396: Uniform
* Resource Identifiers (URI): Generic Syntax</i></a>, amended by <a
* href="http://www.ietf.org/rfc/rfc2732.txt"><i>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 <code>chapter1</code> attached to it. The
+ * document that has the tag {@code chapter1} attached to it. The
* meaning of a tag is resource specific.
* <p>
* An application can also specify a "relative URL",
@@ -170,8 +170,8 @@
private int port = -1;
/**
- * The specified file name on that host. <code>file</code> is
- * defined as <code>path[?query]</code>
+ * 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 <code>URL</code> object from the specified
- * <code>protocol</code>, <code>host</code>, <code>port</code>
- * number, and <code>file</code>.<p>
+ * Creates a {@code URL} object from the specified
+ * {@code protocol}, {@code host}, {@code port}
+ * number, and {@code file}.<p>
*
- * <code>host</code> 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 (<tt>'['</tt> and <tt>']'</tt>), as
+ * enclosed in square brackets ({@code '['} and {@code ']'}), as
* specified by <a
* href="http://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>;
* However, the literal IPv6 address format defined in <a
* href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC 2373: IP
* Version 6 Addressing Architecture</i></a> is also accepted.<p>
*
- * Specifying a <code>port</code> number of <code>-1</code>
+ * Specifying a {@code port} number of {@code -1}
* indicates that the URL should use the default port for the
* protocol.<p>
*
* If this is the first URL object being created with the specified
* protocol, a <i>stream protocol handler</i> object, an instance of
- * class <code>URLStreamHandler</code>, is created for that protocol:
+ * class {@code URLStreamHandler}, is created for that protocol:
* <ol>
* <li>If the application has previously set up an instance of
- * <code>URLStreamHandlerFactory</code> as the stream handler factory,
- * then the <code>createURLStreamHandler</code> 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.
- * <li>If no <code>URLStreamHandlerFactory</code> has yet been set up,
- * or if the factory's <code>createURLStreamHandler</code> method
- * returns <code>null</code>, then the constructor finds the
+ * <li>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:
* <blockquote><pre>
* java.protocol.handler.pkgs
* </pre></blockquote>
- * If the value of that system property is not <code>null</code>,
+ * 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 '<code>|</code>'. The constructor tries to load
+ * slash character '{@code |}'. The constructor tries to load
* the class named:
* <blockquote><pre>
* <<i>package</i>>.<<i>protocol</i>>.Handler
@@ -263,7 +263,7 @@
* where <<i>package</i>> is replaced by the name of the package
* and <<i>protocol</i>> 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 <code>URLStreamHandler</code>, then the next package
+ * a subclass of {@code URLStreamHandler}, then the next package
* in the list is tried.
* <li>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 @@
* <<i>system default package</i>>.<<i>protocol</i>>.Handler
* </pre></blockquote>
* If this class does not exist, or if the class exists but it is not a
- * subclass of <code>URLStreamHandler</code>, then a
- * <code>MalformedURLException</code> is thrown.
+ * subclass of {@code URLStreamHandler}, then a
+ * {@code MalformedURLException} is thrown.
* </ol>
*
* <p>Protocol handlers for the following protocols are guaranteed
@@ -304,13 +304,13 @@
}
/**
- * Creates a URL from the specified <code>protocol</code>
- * name, <code>host</code> name, and <code>file</code> 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.
* <p>
* This method is equivalent to calling the four-argument
- * constructor with the arguments being <code>protocol</code>,
- * <code>host</code>, <code>-1</code>, and <code>file</code>.
+ * 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 <code>URL</code> object from the specified
- * <code>protocol</code>, <code>host</code>, <code>port</code>
- * number, <code>file</code>, and <code>handler</code>. Specifying
- * a <code>port</code> number of <code>-1</code> 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 <code>handler</code> of <code>null</code> 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)
*
* <p>If the handler is not null and there is a security manager,
- * the security manager's <code>checkPermission</code>
+ * the security manager's {@code checkPermission}
* method is called with a
- * <code>NetPermission("specifyStreamHandler")</code> 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
- * <code>checkPermission</code> 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 <code>URL</code> object from the <code>String</code>
+ * Creates a {@code URL} object from the {@code String}
* representation.
* <p>
* This constructor is equivalent to a call to the two-argument
- * constructor with a <code>null</code> first argument.
+ * constructor with a {@code null} first argument.
*
- * @param spec the <code>String</code> 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 <tt>spec</tt> is <tt>null</tt>.
+ * 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 <code>String</code> 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 <tt>spec</tt> is <tt>null</tt>.
+ * 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 <code>String</code> 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 <tt>spec</tt> is <tt>null</tt>.
+ * unknown protocol is found, or {@code spec} is {@code null}.
* @exception SecurityException
* if a security manager exists and its
- * <code>checkPermission</code> 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 <code>URL</code>.
+ * Gets the query part of this {@code URL}.
*
- * @return the query part of this <code>URL</code>,
+ * @return the query part of this {@code URL},
* or <CODE>null</CODE> if one does not exist
* @since 1.3
*/
@@ -730,9 +730,9 @@
}
/**
- * Gets the path part of this <code>URL</code>.
+ * Gets the path part of this {@code URL}.
*
- * @return the path part of this <code>URL</code>, 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 <code>URL</code>.
+ * Gets the userInfo part of this {@code URL}.
*
- * @return the userInfo part of this <code>URL</code>, or
+ * @return the userInfo part of this {@code URL}, or
* <CODE>null</CODE> if one does not exist
* @since 1.3
*/
@@ -752,9 +752,9 @@
}
/**
- * Gets the authority part of this <code>URL</code>.
+ * Gets the authority part of this {@code URL}.
*
- * @return the authority part of this <code>URL</code>
+ * @return the authority part of this {@code URL}
* @since 1.3
*/
public String getAuthority() {
@@ -762,7 +762,7 @@
}
/**
- * Gets the port number of this <code>URL</code>.
+ * 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 <code>URL</code>. 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 <code>URL</code>.
+ * Gets the protocol name of this {@code URL}.
*
- * @return the protocol of this <code>URL</code>.
+ * @return the protocol of this {@code URL}.
*/
public String getProtocol() {
return protocol;
}
/**
- * Gets the host name of this <code>URL</code>, 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 (<tt>'['</tt> and <tt>']'</tt>).
+ * enclosed in square brackets ({@code '['} and {@code ']'}).
*
- * @return the host name of this <code>URL</code>.
+ * @return the host name of this {@code URL}.
*/
public String getHost() {
return host;
}
/**
- * Gets the file name of this <code>URL</code>.
+ * Gets the file name of this {@code URL}.
* The returned file portion will be
* the same as <CODE>getPath()</CODE>, plus the concatenation of
* the value of <CODE>getQuery()</CODE>, if any. If there is
* no query portion, this method and <CODE>getPath()</CODE> will
* return identical results.
*
- * @return the file name of this <code>URL</code>,
+ * @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
- * <code>URL</code>.
+ * {@code URL}.
*
* @return the anchor (also known as the "reference") of this
- * <code>URL</code>, or <CODE>null</CODE> if one does not exist
+ * {@code URL}, or <CODE>null</CODE> if one does not exist
*/
public String getRef() {
return ref;
@@ -834,7 +834,7 @@
* Compares this URL for equality with another object.<p>
*
* If the given object is not a URL then this method immediately returns
- * <code>false</code>.<p>
+ * {@code false}.<p>
*
* 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. <p>
*
- * Note: The defined behavior for <code>equals</code> 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 <code>true</code> if the objects are the same;
- * <code>false</code> 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.<p>
*
- * @return a hash code for this <code>URL</code>.
+ * @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.<p>
*
- * Returns <code>true</code> if this <code>URL</code> and the
- * <code>other</code> 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 <code>URL</code> to compare against.
- * @return <code>true</code> if they reference the same remote object;
- * <code>false</code> 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 <code>URL</code>. The
- * string is created by calling the <code>toExternalForm</code>
+ * 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 <code>URL</code>. The
- * string is created by calling the <code>toExternalForm</code>
+ * 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 <code>new URI (this.toString())</code>.
+ * This method functions in the same way as {@code new URI (this.toString())}.
* <p>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 <code>URLConnection</code> 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 <code>URL</code> and returns an
- * <code>InputStream</code> 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:
* <blockquote><pre>
* openConnection().getInputStream()
@@ -1077,22 +1077,22 @@
static URLStreamHandlerFactory factory;
/**
- * Sets an application's <code>URLStreamHandlerFactory</code>.
+ * Sets an application's {@code URLStreamHandlerFactory}.
* This method can be called at most once in a given Java Virtual
* Machine.
*
- *<p> The <code>URLStreamHandlerFactory</code> instance is used to
+ *<p> The {@code URLStreamHandlerFactory} instance is used to
*construct a stream protocol handler from a protocol name.
*
* <p> If there is a security manager, this method first calls
- * the security manager's <code>checkSetFactory</code> 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
- * <code>checkSetFactory</code> 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)