Module java.base
Package java.net

Class URL

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

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

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

上面的URL表示要使用的协议是 http（超文本传输协议），信息驻留在名为 www.example.com 的主机上。该主机上的信息被命名为 /docs/resource1.html。该名称在主机上的确切含义既取决于协议又取决于主机。该URL的这一部分称为 路径 组件。

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

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

URL 的语法由 RFC 2396: 统一资源标识符（URI）：通用语法 定义，由 RFC 2732: URL中文字面IPv6地址的格式 修改。文字面IPv6地址格式还支持 scope_ids。有关 scope_ids 的语法和用法，请参见 这里。

URL可能附加一个“片段”，也称为“ref”或“引用”。片段由井号字符“#”后跟更多字符表示。例如,

     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/ 和 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 实例的直接字符串表示构造或解析 URL。

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

URL或URI的某些组件，如 userinfo，可能被滥用以构造误导性的URL或URI。处理URL或URI的应用程序应考虑 RFC3986，第7节，安全注意事项 中建议的建议。

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

自版本:
1.0
外部规范
参见:

  • Constructor Details

    • URL

      @Deprecated(since="20") public URL(String protocol, String host, int port, String file) throws MalformedURLException
      Deprecated.
      Use URI.toURL() to construct an instance of URL. See the note on constructor deprecation for more details.
      从指定的protocol、host、port号和file创建一个URL对象。

      host可以表示为主机名或字面IP地址。如果使用IPv6字面地址，应该用方括号（'['和']'）括起来，如RFC 2732所述；但也接受RFC 2373: IP Version 6 Addressing Architecture中定义的字面IPv6地址格式。

      指定port号为-1表示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
      Deprecated.
      Use URI.toURL() to construct an instance of URL. See the note on constructor deprecation for more details.
      从指定的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
      Deprecated.
      Use of(URI, URLStreamHandler) to construct an instance of URL associated with a custom protocol handler. See the note on constructor deprecation for more details.
      从指定的protocol、host、port号、file和handler创建一个URL对象。指定port号为-1表示URL应使用协议的默认端口。指定handler为null表示URL应使用协议的默认流处理程序，如URL(java.lang.String, java.lang.String, int, java.lang.String)所述。

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

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

    • URL

      @Deprecated(since="20") public URL(String spec) throws MalformedURLException
      Deprecated.
      Use URI.toURL() to construct an instance of URL. See the note on constructor deprecation for more details.
      创建一个URL对象，从String表示中解析。

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

      参数:
      spec - 要解析为URL的String。
      抛出:
      MalformedURLException - 如果未指定协议，或找到未知协议，或spec为null，或解析的URL不符合相关协议的特定语法，或底层流处理程序的parseURL方法抛出IllegalArgumentException
      参见:

    • URL

      @Deprecated(since="20") public URL(URL context, String spec) throws MalformedURLException
      Deprecated.
      Use URI.toURL() to construct an instance of URL. See the note on constructor deprecation for more details.
      通过在指定上下文中解析给定的规范来创建URL。根据RFC2396“统一资源标识符：通用语法”中描述的方法，从给定的上下文URL和规范参数创建新URL： 
                <scheme>://<authority><path>?<query>#<fragment>
      引用被解析为方案、权限、路径、查询和片段部分。如果路径组件为空，并且方案、权限和查询组件未定义，则新URL是对当前文档的引用。否则，规范中存在的片段和查询部分将用于新URL。

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

      如果规范中存在权限组件，则规范将被视为绝对的，并且规范的权限和路径将替换上下文的权限和路径。如果规范中不存在权限组件，则新URL的权限将从上下文继承。

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

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

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

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

    • URL

      @Deprecated(since="20") public URL(URL context, String spec, URLStreamHandler handler) throws MalformedURLException
      Deprecated.
      Use of(URI, URLStreamHandler) to construct an instance of URL associated with a custom protocol handler. See the note on constructor deprecation for more details.
      通过在指定上下文中使用指定处理程序解析给定规范来创建URL。如果处理程序为null，则解析将与两参数构造函数一样进行。
      实现要求:
      解析URL包括在所选处理程序上调用parseURL方法。
      参数:
      context - 解析规范的上下文。
      spec - 要解析为URL的String。
      handler - URL的流处理程序。
      抛出:
      MalformedURLException - 如果未指定协议，或找到未知协议，或spec为null，或解析的URL不符合相关协议的特定语法，或底层流处理程序的parseURL方法抛出IllegalArgumentException
      SecurityException - 如果存在安全管理器且其checkPermission方法不允许指定流处理程序。
      参见:

  • Method Details

    • 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创建的新URL实例，并与给定的URLStreamHandler关联（如果有）。
      抛出:
      NullPointerException - 如果uri为null
      IllegalArgumentException - 如果未指定协议（uri方案为null），或者如果URLStreamHandler不为null且无法为给定协议设置
      MalformedURLException - 如果找到未知协议，或给定的URI不符合相关协议的特定语法，或底层流处理程序的parseURL方法抛出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地址，则认为两个主机是等效的；否则，如果任一主机名无法解析，则主机名必须相等，而不考虑大小写；或者两个主机名都等于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
      返回表示与URL引用的远程对象的连接的URLConnection实例。

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

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

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

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

    • 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
      参见：

    • 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方法不允许该操作。
      参见: