JavaTM Platform
Standard Ed. 6

java.net
类 URL

java.lang.Object
  继承者 java.net.URL
所有已实现的接口:
Serializable

public final class URL
     
extends Object
implements Serializable

URL 代表一个统一资源定位符,它是指向互联网“资源”的指针。资源可以是简单的文件或目录,也可以是对更为复杂的对象的引用,例如对数据库或搜索引擎的查询。有关 URL 的类型和格式的更多信息,可从以下位置找到:

http://www.socs.uts.edu.au/MosaicDocs-old/url-primer.html

通常,URL 可分成几个部分。上面的 URL 示例指示使用的协议为 http (超文本传输协议)并且该信息驻留在一台名为 www.socs.uts.edu.au 的主机上。主机上的信息名称为 /MosaicDocs-old/url-primer.html。主机上此名称的准确含义取决于协议和主机。该信息一般存储在文件中,但可以随时生成。该 URL 的这一部分称为路径 部分。

URL 可选择指定一个“端口”,它是用于建立到远程主机 TCP 连接的端口号。如果未指定该端口号,则使用协议默认的端口。例如,http 协议的默认端口为 80。还可以指定一个备用端口,如下所示:

     http://www.socs.uts.edu.au:80/MosaicDocs-old/url-primer.html
 

URL 的语法由此文档定义:RFC 2396:Uniform Resource Identifiers (URI):Generic Syntax;在此文件中对其内容又进行了修正:RFC 2732:Format for Literal IPv6 Addresses in URLs。字面值 IPv6 地址格式还支持 scope_id。scope_id 的语法和用法在此处进行了描述。

URL 后面可能还跟有一个“片段”,也称为“引用”。该片段由井字符 "#" 指示,后面跟有更多的字符。例如,

     http://java.sun.com/index.html#chapter1
 

从技术角度来讲,URL 并不需要包含此片段。但是,使用此片段的目的在于表明,在获取到指定的资源后,应用程序需要使用文档中附加有 chapter1 标记的部分。标记的含义特定于资源。

应用程序也可以指定一个“相对 URL”,它只包含到达相对于另一个 URL 的资源的足够信息。HTML 页面中经常使用相对 URL。例如,假设 URL 的内容是:

     http://java.sun.com/index.html
 
其中包含的相对 URL:
     FAQ.html
 
为以下形式的缩写:
     http://java.sun.com/FAQ.html
 

相对 URL 不需要指定 URL 的所有组成部分。如果缺少协议、主机名称或端口号,这些值将从完整指定的 URL 中继承。但是,必须指定文件部分。可选的片段部分不继承。

URL 类自身并不根据 RFC2396 中定义的转义机制编码或解码任何 URL 部分。由调用方对任何需要在调用 URL 前进行转义的字段进行编码,并对从 URL 返回的任何经过转义的字段进行解码。进一步而言,由于 URL 不懂 URL 转义,所以它不会识别同一 URL 的对等编码和解码形式。例如,对于这两个 URL:

    http://foo.com/hello world/ 和 http://foo.com/hello%20world
将被视为互不相等。

注意,URI 类在某些特定情况下对其组成字段执行转义。建议使用 URI 管理 URL 的编码和解码,并使用 toURI()URI.toURL() 实现这两个类之间的转换。

也可以使用 URLEncoderURLDecoder 类,但是只适用于 HTML 形式的编码,它与 RFC2396 中定义的编码机制不同。

从以下版本开始:
JDK1.0
另请参见:
序列化表格

构造方法摘要
URL(String spec)
          根据 String 表示形式创建 URL 对象。
URL(String protocol, String host, int port, String file)
          根据指定 protocolhostport 号和 file 创建 URL 对象。
URL(String protocol, String host, int port, String file, URLStreamHandler handler)
          根据指定的 protocolhostport 号、filehandler 创建 URL 对象。
URL(String protocol, String host, String file)
          根据指定的 protocol 名称、host 名称和 file 名称创建 URL。
URL(URL context, String spec)
          通过在指定的上下文中对给定的 spec 进行解析创建 URL。
URL(URL context, String spec, URLStreamHandler handler)
          通过在指定的上下文中用指定的处理程序对给定的 spec 进行解析来创建 URL。
 
方法摘要
 boolean equals(Object obj)
          比较此 URL 是否等于另一个对象。
 String getAuthority()
          获取此 URL 的授权部分。
 Object getContent()
          获取此 URL 的内容。
 Object getContent(Class[] classes)
          获取此 URL 的内容。
 int getDefaultPort()
          获取与此 URL 关联协议的默认端口号。
 String getFile()
          获取此 URL 的文件名。
 String getHost()
          获取此 URL 的主机名(如果适用)。
 String getPath()
          获取此 URL 的路径部分。
 int getPort()
          获取此 URL 的端口号。
 String getProtocol()
          获取此 URL 的协议名称。
 String getQuery()
          获取此 URL 的查询部分。
 String getRef()
          获取此 URL 的锚点(也称为“引用”)。
 String getUserInfo()
          获取此 URL 的 userInfo 部分。
 int hashCode()
          创建一个适合哈希表索引的整数。
 URLConnection openConnection()
          返回一个 URLConnection 对象,它表示到 URL 所引用的远程对象的连接。
 URLConnection openConnection(Proxy proxy)
          与 openConnection() 类似,所不同是连接通过指定的代理建立;不支持代理方式的协议处理程序将忽略该代理参数并建立正常的连接。
 InputStream openStream()
          打开到此 URL 的连接并返回一个用于从该连接读入的 InputStream
 boolean sameFile(URL other)
          比较两个 URL,不包括片段部分。
protected  void set(String protocol, String host, int port, String file, String ref)
          设置 URL 的字段。
protected  void set(String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)
          设置 URL 的指定的 8 个字段。
static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
          设置应用程序的 URLStreamHandlerFactory
 String toExternalForm()
          构造此 URL 的字符串表示形式。
 String toString()
          构造此 URL 的字符串表示形式。
 URI toURI()
          返回与此 URL 等效的 URI
 
从类 java.lang.Object 继承的方法
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

构造方法详细信息

URL

public URL(String protocol,
           String host,
           int port,
           String file)
    throws MalformedURLException
根据指定 protocolhostport 号和 file 创建 URL 对象。

host 可用主机名或字面值 IP 地址表示。如果使用 IPv6 字面值地址,则应将其括在方括号('['']')中,如 RFC 2732 中指定的那样;但是,在以下文档中定义的字面值 IPv6 地址格式也可以接受:RFC 2373:IP Version 6 Addressing Architecture

指定 port 号为 -1 指示 URL 应使用协议的默认端口。

如果这是用指定协议创建的第一个 URL 对象,则还会为该协议创建一个流协议处理程序 对象(类 URLStreamHandler 的一个实例):

  1. 如果该应用程序已经预先设置了一个 URLStreamHandlerFactory 的实例作为流处理程序工厂,则将调用该实例的 createURLStreamHandler 方法(协议字符串为其中的一个参数)以创建流协议处理程序。
  2. 如果尚未建立 URLStreamHandlerFactory,或者该工厂的 createURLStreamHandler 方法返回 null,则该构造方法将查找如下系统属性的值:
             java.protocol.handler.pkgs
         
    如果该系统属性的值为非 null,则它被转换为一个由垂直线字符 '|'分隔的包列表。构造方法尝试加载如下名称的类:
             <package>.<protocol>.Handler
         
    其中,<package> 用包的名称替换,<protocol> 用协议的名称替换。如果不存在此类,或者此类存在但它不是 URLStreamHandler 的子类,则尝试列表中的下一个包。
  3. 如果上面的步骤中未找到协议处理程序,则构造方法将尝试从系统默认包加载。
             <system default package>.<protocol>.Handler
         
    如果不存在此类,或者该类存在但它不是 URLStreamHandler 的子类,则抛出 MalformedURLException

应确保搜索路径中包含以下协议的协议处理程序:

http、https、ftp、file 和 jar
 
还可以有其他协议的协议处理程序。

此构造方法不执行对输入的验证。

参数:
protocol - 要使用的协议名称。
host - 主机名称。
port - 主机端口号。
file - 主机上的文件
抛出:
MalformedURLException - 如果指定了未知协议。
另请参见:
System.getProperty(java.lang.String), setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), URLStreamHandler, URLStreamHandlerFactory.createURLStreamHandler( java.lang.String)

URL

public URL(String protocol,
           String host,
           String file)
    throws MalformedURLException
根据指定的 protocol 名称、 host 名称和 file 名称创建 URL。使用指定协议的默认端口。

此方法等同于调用带四个参数的构造方法,四个参数为 protocolhost-1file。 此构造方法不执行对输入的验证。

参数:
protocol - 要使用的协议名称。
host - 主机名称。
file - 主机上的文件。
抛出:
MalformedURLException - 如果指定了未知协议。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String)

URL

public URL(String protocol,
           String host,
           int port,
           String file,
           URLStreamHandler handler)
    throws MalformedURLException
根据指定的 protocolhostport 号、 filehandler 创建 URL 对象。指定 port 号为 -1 指示 URL 应使用协议的默认端口。指定 handlernull 指示 URL 应使用协议的默认流处理程序,大致如下:java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)

如果处理程序为非 null,并且有安全管理器,则使用 NetPermission("specifyStreamHandler") 权限调用安全管理器的 checkPermission 方法。结果可能是一个 SecurityException 异常。 此构造方法不执行对输入的验证。

参数:
protocol - 要使用的协议名称。
host - 主机名称。
port - 主机端口号。
file - 主机上的文件
handler - URL 的流处理程序。
抛出:
MalformedURLException - 如果指定了未知协议。
SecurityException - 如果安全管理器存在并且其 checkPermission 方法不允许显式指定流处理程序。
另请参见:
System.getProperty(java.lang.String), setURLStreamHandlerFactory( java.net.URLStreamHandlerFactory), URLStreamHandler, URLStreamHandlerFactory.createURLStreamHandler( java.lang.String), SecurityManager.checkPermission(java.security.Permission), NetPermission

URL

public URL(String spec)
    throws MalformedURLException
根据 String 表示形式创建 URL 对象。

此构造方法等同于调用两个参数的构造方法,其中,第一个参数为 null

参数:
spec - 将作为 URL 解析的 String
抛出:
MalformedURLException - 如果字符串指定未知协议。
另请参见:
URL(java.net.URL, java.lang.String)

URL

public URL(URL context,
           String spec)
    throws MalformedURLException
通过在指定的上下文中对给定的 spec 进行解析创建 URL。 新的 URL 从给定的上下文 URL 和 spec 参数创建,这在以下文档中进行了描述:RFC2396 "Uniform Resource Identifiers : Generic * Syntax":
          <scheme>://<authority><path>?<query>#<fragment>
 
该引用被解析为方案、授权、路径、查询和片段部分。如果路径部分为空,方案、授权和查询部分未定义,则新的 URL 为对当前文档的引用。否则,新的 URL 中将使用 spec 中出现的片段和查询部分。

如果给定的 spec 中定义了方案部分,但与上下文的方案不匹配,则只根据 spec 创建新的绝对 URL。否则,方案部分从上下文 URL 继承。

如果 spec 中有授权部分,则将该 spec 视为绝对的,并用 spec 的授权和路径替换上下文授权和路径。如果 spec 中没有授权部分,则新的 URL 的授权将从上下文继承。

如果 spec 的路径部分以斜线字符 "/" 开始,则将该路径视为绝对的,并用 spec 的路径替换上下文路径。

否则,如 RFC2396 中所述,该路径将被视为相对路径,并被添加到上下文路径中。此外,在这种情况下,还将通过删除由 ".." 和 "." 产生的目录更改对路径进行规范化处理。

有关 URL 解析的更详细的描述,请参考 RFC2396。

参数:
context - 要在其中解析规范的上下文。
spec - 将作为 URL 解析的 String
抛出:
MalformedURLException - 如果未指定任何协议,或者找到了未知协议。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler, URLStreamHandler.parseURL(java.net.URL, java.lang.String, int, int)

URL

public URL(URL context,
           String spec,
           URLStreamHandler handler)
    throws MalformedURLException
通过在指定的上下文中用指定的处理程序对给定的 spec 进行解析来创建 URL。如果处理程序为 null,则使用两参数构造方法进行解析。

参数:
context - 要在其中解析规范的上下文。
spec - 将作为 URL 解析的 String
handler - URL 的流处理程序。
抛出:
MalformedURLException - 如果未指定任何协议,或者找到了未知协议。
SecurityException - 如果安全管理器存在并且其 checkPermission 方法不允许指定流处理程序。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler, URLStreamHandler.parseURL(java.net.URL, java.lang.String, int, int)
方法详细信息

set

protected void set(String protocol,
                   String host,
                   int port,
                   String file,
                   String ref)
设置 URL 的字段。这不是一个公共方法,所以只有 URLStreamHandler 才能修改 URL 字段。其他情况下,URL 为常量。

参数:
protocol - 要使用的协议名称
host - 主机名称
port - 主机端口号
file - 主机上的文件
ref - URL 中的内部引用

set

protected void set(String protocol,
                   String host,
                   int port,
                   String authority,
                   String userInfo,
                   String path,
                   String query,
                   String ref)
设置 URL 的指定的 8 个字段。这不是一个公共方法,所以只有 URLStreamHandler 才能修改 URL 字段。其他情况下,URL 为常量。

参数:
protocol - 要使用的协议名称
host - 主机名称
port - 主机上的端口号
authority - url 的授权部分
userInfo - 用户名和密码
path - 主机上的文件
ref - URL 中的内部引用
query - 此 URL 的查询部分
从以下版本开始:
1.3

getQuery

public String getQuery()
获取此 URL 的查询部分。

返回:
URL 的查询,如果没有查询,则返回 null
从以下版本开始:
1.3

getPath

public String getPath()
获取此 URL 的路径部分。

返回:
URL 的路径部分,如果没有路径,则返回一个空字符串
从以下版本开始:
1.3

getUserInfo

public String getUserInfo()
获取此 URL 的 userInfo 部分。

返回:
URL 的 userInfo 部分,如果没有用户信息,则返回 null
从以下版本开始:
1.3

getAuthority

public String getAuthority()
获取此 URL 的授权部分。

返回:
URL 的授权部分
从以下版本开始:
1.3

getPort

public int getPort()
获取此 URL 的端口号。

返回:
端口号,如果未设置端口号,则返回 -1

getDefaultPort

public int getDefaultPort()
获取与此 URL 关联协议的默认端口号。如果 URL 方案或 URL 的 URLStreamHandler 未定义默认的端口号,则返回 -1。

返回:
端口号
从以下版本开始:
1.4

getProtocol

public String getProtocol()
获取此 URL 的协议名称。

返回:
URL 的协议。

getHost

public String getHost()
获取此 URL 的主机名(如果适用)。主机的格式遵守 RFC 2732,即对于一个字面值 IPv6 地址,该方法将返回括在方括号 ( '['']') 中的 IPv6 地址。

返回:
URL 的主机名称。

getFile

public String getFile()
获取此 URL 的文件名。返回的文件部分将与 getPath() 相同,再加上 getQuery() 值的规范化形式(如果有)。如果没有查询部分,此方法和 getPath() 将返回相同的结果。

返回:
URL 的文件名,如果没有文件名,则返回一个空字符串

getRef

public String getRef()
获取此 URL 的锚点(也称为“引用”)。

返回:
URL 的锚点(也称为“引用”),如果没有锚点,则返回 null

equals

public boolean equals(Object obj)
比较此 URL 是否等于另一个对象。

如果给定的对象不是一个 URL,则此方法立即返回 false

如果两个 URL 具有相同的协议,引用相同的主机,主机上具有相同的端口号,文件相同,片段也都相同,则这两个 URL 对象相等。

如果两个主机名可解析为同一 IP 地址,则认为两个主机相同;如果有一个主机名无法解析,但两个主机名相等(不区分大小写),或者两个主机名都为 null,则也认为这两个主机相同。

由于主机比较需要进行名称解析,所以此操作为阻塞操作。

注:equals 定义的行为已知与 HTTP 的虚拟主机行为不一致。

覆盖:
Object 中的 equals
参数:
obj - 要与其比较的 URL。
返回:
如果对象相同,则返回 true;否则,返回 false
另请参见:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
创建一个适合哈希表索引的整数。

哈希码基于所有与 URL 比较相关的 URL 部分。因此,此操作为阻塞操作。

覆盖:
Object 中的 hashCode
返回:
URL 的哈希码。
另请参见:
Object.equals(java.lang.Object), Hashtable

sameFile

public boolean sameFile(URL other)
比较两个 URL,不包括片段部分。

如果此 URLother 参数相等,则返回 true,不考虑片段部分。

参数:
other - 要与其比较的 URL
返回:
如果它们引用相同的远程对象,则返回 true;否则返回 false

toString

public String toString()
构造此 URL 的字符串表示形式。字符串是通过调用此对象的流协议处理程序的 toExternalForm 方法创建的。

覆盖:
Object 中的 toString
返回:
此对象的字符串表示形式。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler.toExternalForm(java.net.URL)

toExternalForm

public String toExternalForm()
构造此 URL 的字符串表示形式。字符串是通过调用此对象的流协议处理程序的 toExternalForm 方法创建的。

返回:
此对象的字符串表示形式。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandler.toExternalForm(java.net.URL)

toURI

public URI toURI()
          throws URISyntaxException
返回与此 URL 等效的 URI。此方法的作用与 new URI (this.toString()) 相同。

注意,任何 URL 实例只要遵守 RFC 2396 就可以转化为 URI。但是,有些未严格遵守该规则的 URL 将无法转化为 URI。

返回:
与此 URL 等效的 URI 实例。
抛出:
URISyntaxException - 如果由于该 URL 格式未严格遵守 RFC2396 而无法转化为 URI。
从以下版本开始:
1.5

openConnection

public URLConnection openConnection()
                             throws IOException
返回一个 URLConnection 对象,它表示到 URL 所引用的远程对象的连接。

每次调用此 URL 的协议处理程序的 openConnection 方法都打开一个新的连接。

如果 URL 的协议(例如,HTTP 或 JAR)存在属于以下包或其子包之一的公共、专用 URLConnection 子类:java.lang、java.io、java.util、java.net,返回的连接将为该子类的类型。例如,对于 HTTP,将返回 HttpURLConnection,对于 JAR,将返回 JarURLConnection。

返回:
到该 URL 的 URLConnection
抛出:
IOException - 如果发生 I/O 异常。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLConnection, URLStreamHandler.openConnection(java.net.URL)

openConnection

public URLConnection openConnection(Proxy proxy)
                             throws IOException
与 openConnection() 类似,所不同是连接通过指定的代理建立;不支持代理方式的协议处理程序将忽略该代理参数并建立正常的连接。 调用此方法会提示系统的默认 ProxySelector 设置。

参数:
proxy - 进行此连接所需的代理。如果希望使用直接连接,则应指定 Proxy.NO_PROXY。
返回:
到该 URL 的 URLConnection
抛出:
IOException - 如果发生 I/O 异常。
SecurityException - 如果有安全管理器并且调用方没有连接到代理的权限。
IllegalArgumentException - 如果代理为 null,或代理的类型错误
UnsupportedOperationException - 如果实现该协议处理程序的子类不支持此方法。
从以下版本开始:
1.5
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLConnection, URLStreamHandler.openConnection(java.net.URL, java.net.Proxy)

openStream

public final InputStream openStream()
                             throws IOException
打开到此 URL 的连接并返回一个用于从该连接读入的 InputStream。此方法是下面方法的缩写:
     openConnection().getInputStream()
 

返回:
从 URL 连接读入的输入流。
抛出:
IOException - 如果发生 I/O 异常。
另请参见:
openConnection(), URLConnection.getInputStream()

getContent

public final Object getContent()
                        throws IOException
获取此 URL 的内容。此方法是下面方法的缩写:
     openConnection().getContent()
 

返回:
此 URL 的内容。
抛出:
IOException - 如果发生 I/O 异常。
另请参见:
URLConnection.getContent()

getContent

public final Object getContent(Class[] classes)
                        throws IOException
获取此 URL 的内容。此方法是下面方法的缩写:
     openConnection().getContent(Class[])
 

参数:
classes - Java 类型的数组
返回:
此 URL 的内容对象,它为 classes 数组中指定的类型的第一个匹配项。如果所有请求类型都不受支持,则返回 null。
抛出:
IOException - 如果发生 I/O 异常。
从以下版本开始:
1.3
另请参见:
URLConnection.getContent(Class[])

setURLStreamHandlerFactory

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
设置应用程序的 URLStreamHandlerFactory。在一个给定的 Java 虚拟机中,此方法最多只能调用一次。

URLStreamHandlerFactory 实例用于从协议名称构造流协议处理程序。

如果有安全管理器,此方法首先调用安全管理器的 checkSetFactory 方法以确保允许该操作。这可能会导致 SecurityException 异常。

参数:
fac - 需要的工厂。
抛出:
Error - 如果应用程序已经设置了工厂。
SecurityException - 如果安全管理器存在并且其 checkSetFactory 方法不允许进行此操作。
另请参见:
URL(java.lang.String, java.lang.String, int, java.lang.String), URLStreamHandlerFactory, SecurityManager.checkSetFactory()

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策