模块 java.base
包 java.net

类 URL

java.lang.Object
java.net.URL
所有已实现的接口：
Serializable
public final class URL extends Object implements Serializable
类 URL 表示统一资源定位器，指向万维网上“资源”的指针。资源可以是像文件或目录这样简单的东西，也可以是对更复杂对象的引用，例如对数据库或搜索引擎的查询。有关 URL 类型及其格式的更多信息，请访问： 网址类型

一般来说，一个 URL 可以分成几个部分。考虑以下示例：

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

上面的 URL 表明要使用的协议是 http（超文本传输协议），信息驻留在名为 www.example.com 的主机上。该主机上的信息名为 /docs/resource1.html 。该名称在主机上的确切含义既取决于协议又取决于主机。信息通常驻留在文件中，但也可以即时生成。 URL 的这个组成部分称为path组件.

URL 可以选择性地指定一个“端口”，这是在远程主机上建立 TCP 连接的端口号。如果未指定端口，则使用协议的默认端口。例如，http 的默认端口是 80。可以将替代端口指定为：

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

URL 的语法由 RFC 2396：统一资源标识符 (URI)：通用语法 定义，由 RFC 2732：URL 中文字 IPv6 地址的格式 修改。 Literal IPv6 地址格式也支持 scope_ids。 这里 描述了 scope_ids 的语法和用法。

URL 可能附加了一个“片段”，也称为“ref”或“reference”。该片段由尖锐的符号字符“#”表示，后跟更多字符。例如，

   http://www.example.com/index.html#chapter1

此片段在技术上不是 URL 的一部分。相反，它表示在检索到指定资源后，应用程序对文档中附加了标记 chapter1 的那部分特别感兴趣。标签的含义是特定于资源的。

应用程序还可以指定一个“相对 URL”，它只包含足以到达相对于另一个 URL 的资源的信息。相对 URL 经常在 HTML 页面中使用。例如，如果 URL 的内容：

   http://www.example.com/index.html
其中包含相对 URL： 
   FAQ.html
这将是以下内容的简写： 
   http://www.example.com/FAQ.html

相对 URL 不需要指定 URL 的所有组件。如果缺少协议、主机名或端口号，则该值将从完全指定的 URL 继承。必须指定文件组件。可选片段不被继承。

构建 URL 的实例

java.net.URL 构造函数已弃用。鼓励开发人员使用 java.net.URI 来解析或构建 URL。在需要 java.net.URL 的实例来打开连接的情况下，URI 可用于构造或解析 URL 字符串，可能调用 URI.parseServerAuthority() 来验证权限组件是否可以解析为基于服务的权限，然后调用 URI.toURL() 来创建 URL 实例。

URL 构造函数被指定为抛出 MalformedURLException 但实际执行的解析/验证取决于实现。一些解析/验证可能会延迟到稍后调用底层 流处理器的实现 时。能够构造 URL 的实例并不能保证它符合 URL 语法规范。

URL 类本身不会根据 RFC2396 中定义的转义机制对任何 URL 组件进行编码或解码。调用者有责任对在调用 URL 之前需要转义的任何字段进行编码，并对从 URL 返回的任何转义字段进行解码。此外，由于 URL 不知道 URL 转义，它无法识别同一 URL 的编码或解码形式之间的等价性。例如，这两个网址：

  http://foo.com/hello world/ and http://foo.com/hello%20world
将被视为彼此不相等。

请注意，URI 类在某些情况下会执行其组件字段的转义。管理 URL 编码和解码的推荐方法是使用 URI ，并使用 toURI() 和 URI.toURL() 在这两个类之间进行转换。

URLEncoder 和 URLDecoder 类也可以使用，但仅限于 HTML 表单编码，这与 RFC2396 中定义的编码方案不同。

API 注意：
使用文件路径和文件 URI 的应用程序应该非常小心地使用适当的方法在两者之间进行转换。 Path.of(URI) 工厂方法和 File(URI) 构造函数可用于从文件 URI 创建 Path 或 File 对象。 Path.toUri() 和 File.toURI() 可用于从文件路径创建 URI ，可使用 URI.toURL() 将其转换为 URL。应用程序永远不应尝试从 File 或 Path 实例的直接字符串表示中 构造 或 parse a URL。

在从 URI 构造 URL 之前，根据所涉及的协议，应用程序应考虑验证 URI 授权是否为 可以解析为基于服务的 。

URL 或 URI 的某些组成部分，例如用户信息, 可能会被滥用来构建误导性的 URL 或 URI。处理 URL 或 URI 的应用程序应考虑 RFC3986，第 7 节，安全注意事项 中建议的建议。

所有 URL 构造函数都可能抛出 MalformedURLException 。特别是，如果底层 URLStreamHandler 实现拒绝或已知拒绝任何参数，则可能会抛出 MalformedURLException 。通常，如果该方法的底层流处理程序实现抛出 IllegalArgumentException，则调用流处理程序的 解析网址方法 的构造函数可能会抛出 MalformedURLException。但是，流处理程序执行或不执行哪些检查取决于实现，调用者不应依赖此类检查来进行完整的 URL 验证。

自从：
1.0
参见：

  • 构造方法详细信息

    • URL

      @Deprecated (since ="20") public URL(String  protocol, String  host, int port, String  file) throws MalformedURLException
      已弃用。
      使用 URI.toURL() 构造 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      从指定的 protocol、host、port 编号和 file 创建一个 URL 对象。

      host 可以表示为主机名或文字 IP 地址。如果使用 IPv6 文字地址，则应按照 RFC 2732 的规定将其括在方括号（'[' 和 ']' ）中；但是，RFC 2373：IP 版本 6 寻址架构 中定义的文字 IPv6 地址格式也被接受。

      指定 -1 的 port 数字表示 URL 应使用协议的默认端口。

      如果这是使用指定协议创建的第一个 URL 对象，则流协议处理器对象，类 URLStreamHandler 的实例，是为该协议创建的：

      1. 如果应用程序先前已将 URLStreamHandlerFactory 实例设置为流处理程序工厂，则调用该实例的 createURLStreamHandler 方法，并将协议字符串作为参数来创建流协议处理程序。
      2. 如果尚未设置URLStreamHandlerFactory，或者如果工厂的createURLStreamHandler方法返回null，则ServiceLoader机制用于使用系统类加载器定位URLStreamHandlerProvider实现。提供者定位的顺序是特定于实现的，并且实现可以自由缓存定位的提供者。如果遇到从 createURLStreamHandler 抛出的 ServiceConfigurationError、Error 或 RuntimeException，将传播到调用线程。每个提供者的 createURLStreamHandler 方法（如果已实例化）将使用协议字符串调用，直到提供者返回非空值或所有提供者都已用尽。
      3. 如果上一步未能找到协议处理程序，构造方法将读取系统属性的值：
        java.protocol.handler.pkgs
        如果该系统属性的值不是 null ，则它被解释为由垂直斜杠字符“|”分隔的包列表。构造函数尝试加载名为的类：
        <package>.<protocol>.Handler
        其中 <package> 替换为包的名称，<protocol> 替换为协议的名称。如果此类不存在，或者如果该类存在但它不是 URLStreamHandler 的子类，则尝试列表中的下一个包。
      4. 如果上一步未能找到协议处理程序，则构造函数会尝试加载内置协议处理程序。如果此类不存在，或者如果该类存在但它不是 URLStreamHandler 的子类，则抛出 MalformedURLException。

      保证以下协议的协议处理程序存在于搜索路径上：

      • http
      • https
      • file
      • jar
      附加协议的协议处理程序也可能可用。一些协议处理程序，例如那些用于加载平台类或类路径上的类的处理程序，可能不会被重写。此类限制的详细信息以及这些限制何时适用（例如在运行时初始化期间）是特定于实现的，因此未指定

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

      参数：
      protocol - 要使用的协议的名称。
      host - 主机名。
      port - 主机上的端口号。
      file - 主机上的文件
      抛出：
      MalformedURLException - 如果未知协议或端口是除 -1 以外的负数，或者如果底层流处理程序实现拒绝或已知拒绝，则 URL
      参见：

    • URL

      @Deprecated (since ="20") public URL(String  protocol, String  host, String  file) throws MalformedURLException
      已弃用。
      使用 URI.toURL() 构造 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      从指定的 protocol 名称、host 名称和 file 名称创建 URL。使用指定协议的默认端口。

      此构造方法等同于四参数构造方法，唯一的区别是使用指定协议的默认端口。此构造方法不执行输入验证。

      参数：
      protocol - 要使用的协议的名称。
      host - 主机名。
      file - 主机上的文件。
      抛出：
      MalformedURLException - 如果指定了未知协议，或者如果底层流处理程序实现拒绝或已知拒绝，则 URL
      参见：

    • URL

      @Deprecated (since ="20") public URL(String  protocol, String  host, int port, String  file, URLStreamHandler  handler) throws MalformedURLException
      已弃用。
      使用 of(URI, URLStreamHandler) 构造与自定义协议处理程序关联的 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      从指定的 protocol、host、port 编号、file 和 handler 创建一个 URL 对象。指定 -1 的 port 数字表示 URL 应使用协议的默认端口。指定 null 的 handler 表示 URL 应该使用协议的默认流处理程序，如概述：URL(java.lang.String, java.lang.String, int, java.lang.String)

      如果处理程序不为 null 并且存在安全管理器，则使用 NetPermission("specifyStreamHandler") 权限调用安全管理器的 checkPermission 方法。这可能会导致 SecurityException。此构造函数不执行输入验证。

      参数：
      protocol - 要使用的协议的名称。
      host - 主机名。
      port - 主机上的端口号。
      file - 主机上的文件
      handler - URL 的流处理程序。
      抛出：
      MalformedURLException - 如果未知协议或端口是除 -1 以外的负数，或者如果底层流处理程序实现拒绝或已知拒绝，则 URL
      SecurityException - 如果安全管理器存在且其 checkPermission 方法不允许明确指定流处理程序。
      参见：

    • URL

      @Deprecated (since ="20") public URL(String  spec) throws MalformedURLException
      已弃用。
      使用 URI.toURL() 构造 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      从 String 表示创建一个 URL 对象。

      此构造函数等效于使用 null 第一个参数调用双参数构造函数。

      参数：
      spec - 要解析为 URL 的 String。
      抛出：
      MalformedURLException - 如果没有指定协议，或者发现未知协议，或者 spec 是 null ，或者解析的 URL 不符合相关协议的特定语法，或者底层流处理程序的 解析网址方法 抛出 IllegalArgumentException
      参见：

    • URL

      @Deprecated (since ="20") public URL(URL  context, String  spec) throws MalformedURLException
      已弃用。
      使用 URI.toURL() 构造 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      通过在指定上下文中解析给定规范来创建 URL。新 URL 是根据给定的上下文 URL 和规范参数创建的，如 RFC2396“统一资源标识符：通用语法”中所述： 
           <scheme>://<authority><path>?<query>#<fragment>
      引用被解析为方案、权限、路径、查询和片段部分。如果路径部分为空，并且未定义方案、权限和查询部分，则新 URL 是对当前文档的引用。否则，规范中存在的片段和查询部分将用于新 URL。

      如果方案组件在给定的规范中定义并且与上下文的方案不匹配，则新 URL 将创建为仅基于规范的绝对 URL。否则，方案组件是从上下文 URL 继承的。

      如果权限组件存在于规范中，那么规范将被视为绝对的，规范权限和路径将替换上下文权限和路径。如果规范中没有权限组件，那么新 URL 的权限将从上下文中继承。

      如果规范的路径组件以斜杠字符“/”开头，则该路径将被视为绝对路径，并且规范路径会替换上下文路径。

      否则，路径将被视为相对路径并附加到上下文路径，如 RFC2396 中所述。此外，在这种情况下，路径通过删除因出现“..”和“.”而造成的目录更改而规范化。

      有关 URL 解析的更详细说明，请参阅 RFC2396。

      实现要求：
      解析 URL 包括在选定的处理程序上调用 parseURL 方法。
      参数：
      context - 解析规范的上下文。
      spec - 要解析为 URL 的 String。
      抛出：
      MalformedURLException - 如果没有指定协议，或者发现未知协议，或者 spec 是 null ，或者解析的 URL 不符合相关协议的特定语法，或者底层流处理程序的 解析网址方法 抛出 IllegalArgumentException
      参见：

    • URL

      @Deprecated (since ="20") public URL(URL  context, String  spec, URLStreamHandler  handler) throws MalformedURLException
      已弃用。
      使用 of(URI, URLStreamHandler) 构造与自定义协议处理程序关联的 URL 实例。有关详细信息，请参阅 构造函数弃用 上的说明。
      通过在指定上下文中使用指定处理程序解析给定规范来创建 URL。如果处理程序为 null，则解析与双参数构造方法一样发生。
      实现要求：
      解析 URL 包括在选定的处理程序上调用 parseURL 方法。
      参数：
      context - 解析规范的上下文。
      spec - 要解析为 URL 的 String。
      handler - URL 的流处理程序。
      抛出：
      MalformedURLException - 如果没有指定协议，或者发现未知协议，或者 spec 是 null ，或者解析的 URL 不符合相关协议的特定语法，或者底层流处理程序的 解析网址方法 抛出 IllegalArgumentException
      SecurityException - 如果安全管理器存在且其 checkPermission 方法不允许指定流处理程序。
      参见：

  • 方法详情

    • of

      public static URL  of(URI  uri, URLStreamHandler  handler) throws MalformedURLException
      从 URI 创建一个 URL，就像通过调用 uri.toURL() 一样，但如果允许的话，将它与给定的 URLStreamHandler 相关联。
      API 注意：
      应用程序应考虑在构建URL 和打开连接之前执行额外的完整性检查。请参阅类级别 API 文档中的 API 说明。
      实现要求：
      此方法的实现包括在选定的处理程序上调用 parseURL 方法。
      参数：
      uri - 应从中构建返回的 URL 的 URI
      handler - 返回的 URL 的自定义协议流处理程序。可以是 null ，在这种情况下，将使用协议的默认流处理程序（如果有）。
      返回：
      从给定的 URI 创建并与给定的 URLStreamHandler 关联的新 URL 实例（如果有）
      抛出：
      NullPointerException - 如果 uri 是 null
      IllegalArgumentException - 如果没有指定协议（uri方案 是 null ），或者如果 URLStreamHandler 不是 null 并且不能为给定协议设置
      MalformedURLException - 如果发现未知协议，或者给定的 URI 不符合相关协议的特定语法，或者底层流处理程序的 解析网址方法 抛出 IllegalArgumentException
      SecurityException - 如果安全管理器存在且其 checkPermission 方法不允许指定流处理程序
      自从：
      20
      参见：

    • 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 对象具有相同的协议、引用等效主机、在主机上具有相同的端口号以及相同的文件和文件片段，则它们是相等的。

      如果两个主机名都可以解析为相同的 IP 地址，则认为两个主机是等价的； else 如果无法解析任何一个主机名，则主机名必须相等而不考虑大小写；或两个主机名都等于 null。

      由于主机比较需要名称解析，因此此操作是阻塞操作。

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

      重写：
      equals 在类 Object 中
      参数：
      obj - 要比较的 URL。
      返回：
      true 如果对象相同； false否则。
      参见：

    • hashCode

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

      哈希码基于与 URL 比较相关的所有 URL 组件。因此，此操作是阻塞操作。

      重写：
      hashCode 在类 Object 中
      返回：
      这个 URL 的哈希码。
      参见：

    • sameFile

      public boolean sameFile(URL  other)
      比较两个 URL，不包括片段组件。

      如果此 URL 和 other 参数相等而不考虑片段组件，则返回 true。

      参数：
      other - 要比较的 URL。
      返回：
      true 如果它们引用相同的远程对象； false否则。

    • toString

      public String  toString()
      构造此 URL 的字符串表示形式。该字符串是通过调用此对象的流协议处理程序的 toExternalForm 方法创建的。
      重写：
      toString 在类 Object 中
      返回：
      此对象的字符串表示形式。
      参见：

    • toExternalForm

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

    • toURI

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

      请注意，任何符合 RFC 2396 的 URL 实例都可以转换为 URI。但是，有些不严格合规的 URL 无法转换为 URI。

      返回：
      与此 URL 等效的 URI 实例。
      抛出：
      URISyntaxException - 如果此 URL 未严格按照 RFC2396 格式化并且无法转换为 URI。
      自从：
      1.5

    • openConnection

      public URLConnection  openConnection() throws IOException
      返回一个 URLConnection 实例，表示与 URL 引用的远程对象的连接。

      每次为此 URL 调用协议处理程序的 URLStreamHandler.openConnection(URL) 方法时，都会创建一个新的 URLConnection 实例。

      应该注意的是，URLConnection 实例在创建时不会建立实际的网络连接。这只会在调用 URLConnection.connect() 时发生。

      如果对于 URL 的协议（如 HTTP 或 JAR），存在一个公共的、专门的 URLConnection 子类，属于以下包之一或其子包之一：java.lang、java.io、java.util、java.net、返回的连接将属于该子类。例如，对于 HTTP，将返回一个 HttpURLConnection，对于 JAR，将返回一个 JarURLConnection。

      返回：
      URLConnection 链接到 URL。
      抛出：
      IOException - 如果发生 I/O 异常。
      参见：

    • openConnection

      public URLConnection  openConnection(Proxy  proxy) throws IOException
      与 openConnection() 相同，只是连接将通过指定的代理进行；不支持代理的协议处理程序将忽略代理参数并建立正常连接。调用此方法会抢占系统的默认 ProxySelector 设置。
      参数：
      proxy - 将通过其建立此连接的代理。如果需要直接连接，则应指定 Proxy.NO_PROXY。
      返回：
      一个 URLConnection 到 URL。
      抛出：
      IOException - 如果发生 I/O 异常。
      SecurityException - 如果存在安全管理器并且调用者没有连接到代理的权限。
      IllegalArgumentException - 如果 proxy 为 null 或 proxy 类型错误，将被抛出
      UnsupportedOperationException - 如果实现协议处理程序的子类不支持此方法。
      自从：
      1.5
      参见：

    • openStream

      public final InputStream  openStream() throws IOException
      打开与此 URL 的连接并返回一个 InputStream 以从该连接读取。此方法是以下内容的简写： 
         openConnection().getInputStream()
      返回：
      用于从 URL 连接读取的输入流。
      抛出：
      IOException - 如果发生 I/O 异常。
      参见：

    • getContent

      public final Object  getContent() throws IOException
      获取此 URL 的内容。此方法是以下内容的简写： 
         openConnection().getContent()
      返回：
      此 URL 的内容。
      抛出：
      IOException - 如果发生 I/O 异常。
      参见：

    • getContent

      public final Object  getContent(Class <?>[] classes) throws IOException
      获取此 URL 的内容。此方法是以下内容的简写： 
         openConnection().getContent(classes)
      参数：
      classes - Java 类型数组
      返回：
      此 URL 的内容对象，它是类数组中指定类型的第一个匹配项。如果不支持任何请求的类型，则为 null。
      抛出：
      IOException - 如果发生 I/O 异常。
      自从：
      1.3
      参见：

    • setURLStreamHandlerFactory

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

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

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

      参数：
      fac - 所需的工厂。
      抛出：
      Error - 如果应用程序已经设置了工厂。
      SecurityException - 如果安全管理器存在且其 checkSetFactory 方法不允许该操作。
      参见：