鸿蒙OS URL

URL

java.lang.Object

|---java.net.URL

public final class URL
extends Object
implements Serializable

类 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 地址的格式。 Literal IPv6 地址格式也支持 scope_ids。 此处描述了 scope_ids 的语法和用法。

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

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

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

应用程序还可以指定一个“相对 URL”，它只包含足够的信息来访问相对于另一个 URL 的资源。 相对 URL 经常在 HTML 页面中使用。 例如，如果 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/ and http://foo.com/hello%20world

将被视为彼此不相等。

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

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

构造函数摘要

构造函数	描述
URL(String spec)	从 String 表示创建一个 URL 对象。
URL(String protocol, String host, int port, String file)	从指定的协议、主机、端口号和文件创建 URL 对象。
URL(String protocol, String host, int port, String file, URLStreamHandler handler)	从指定的协议、主机、端口号、文件和处理程序创建一个 URL 对象。
URL(String protocol, String host, String file)	从指定的协议名、主机名和文件名创建 URL。
URL(URL context, String spec)	通过在指定上下文中解析给定规范来创建 URL。
URL(URL context, String spec, URLStreamHandler handler)	通过在指定上下文中使用指定处理程序解析给定规范来创建 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，不包括片段组件。
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

从指定的协议、主机、端口号和文件创建 URL 对象。

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

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

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

1. 如果应用程序之前已将 URLStreamHandlerFactory 的实例设置为流处理程序工厂，则以协议字符串作为参数调用该实例的 createURLStreamHandler 方法以创建流协议处理程序。

1. 如果还没有设置 URLStreamHandlerFactory，或者工厂的 createURLStreamHandler 方法返回 null，那么构造函数查找系统属性的值：

            java.protocol.handler.pkgs     

如果该系统属性的值不为 null，则将其解释为由垂直斜杠字符“|”分隔的包列表。 构造函数尝试加载名为：

            <package>.<protocol>.Handler     

其中 <package> 被包名替换，<protocol> 被协议名替换。 如果该类不存在，或者该类存在但不是 URLStreamHandler 的子类，则尝试列表中的下一个包。

1. 如果上一步未能找到协议处理程序，则构造函数会尝试从系统默认包加载。

            <system default package>.<protocol>.Handler     

如果该类不存在，或者该类存在但不是 URLStreamHandler 的子类，则抛出 MalformedURLException。

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

     http, https, file, and jar 

其他协议的协议处理程序也可能可用。

此构造函数不执行输入验证。

参数：

参数名称	参数描述
protocol	要使用的协议的名称。
host	主机名。
port	主机上的端口号。
file	主机上的文件

Throws:

Throw名称	Throw描述
MalformedURLException	如果指定了未知协议。

URL

public URL(String protocol, String host, String file) throws MalformedURLException

从指定的协议名、主机名和文件名创建 URL。 使用指定协议的默认端口。

该方法等效于调用四参数构造函数，参数为协议、主机、-1 和文件。 此构造函数不执行输入验证。

参数：

参数名称	参数描述
protocol	要使用的协议的名称。
host	主机名。
file	主机上的文件。

Throws:

Throw名字	Throw描述
MalformedURLException	如果指定了未知协议。

URL

public URL(String protocol, String host, int port, String file, URLStreamHandler handler) throws MalformedURLException

从指定的协议、主机、端口号、文件和处理程序创建一个 URL 对象。 指定端口号 -1 表示 URL 应使用协议的默认端口。 指定 null 处理程序表示 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 的流处理程序。

Throws:

Throw名称	Throw描述
MalformedURLException	如果指定了未知协议。
SecurityException	如果存在安全管理器并且其 checkPermission 方法不允许显式指定流处理程序。

URL

public URL(String spec) throws MalformedURLException

从 String 表示创建一个 URL 对象。

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

参数：

参数名称	参数描述
spec	要解析为 URL 的字符串。

Throws:

Throw名称	Throw描述
MalformedURLException	如果未指定协议，或发现未知协议，或规范为空。

URL

public URL(URL context, String spec) throws MalformedURLException

通过在指定上下文中解析给定规范来创建 URL。 新 URL 是从给定的上下文 URL 和规范参数创建的，如 RFC2396 “统一资源标识符：通用 * 语法”中所述：

          <scheme>://<authority><path>?<query>#<fragment> 

引用被解析为方案、权限、路径、查询和片段部分。如果路径组件为空且方案、权限和查询组件未定义，则新 URL 是对当前文档的引用。否则，规范中存在的片段和查询部分将在新 URL 中使用。

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

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

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

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

参数：

参数名称	参数描述
context	解析规范的上下文。
spec	要解析为 URL 的字符串。

Throws:

Throw名称	Throw描述
MalformedURLException	如果未指定协议，或发现未知协议，或规范为空。

URL

public URL(URL context, String spec, URLStreamHandler handler) throws MalformedURLException

通过在指定上下文中使用指定处理程序解析给定规范来创建 URL。 如果处理程序为空，则解析与两个参数构造函数一样发生。

参数：

参数名称	参数描述
context	解析规范的上下文。
spec	要解析为 URL 的字符串。
handler	URL 的流处理程序。

Throws:

Throw名称	Throw描述
MalformedURLException	如果未指定协议，或发现未知协议，或规范为空。
SecurityException	如果存在安全管理器并且其 checkPermission 方法不允许指定流处理程序。

方法详情

getQuery

public String getQuery()

获取此 URL 的查询部分。

返回：

此 URL 的查询部分，如果不存在则为 null

getPath

public String getPath()

获取此 URL 的路径部分。

返回：

此 URL 的路径部分，如果不存在则为空字符串

getUserInfo

public String getUserInfo()

获取此 URL 的 userInfo 部分。

返回：

此 URL 的 userInfo 部分，如果不存在则为 null

getAuthority

public String getAuthority()

获取此 URL 的权限部分。

返回：

此 URL 的权限部分

getPort

public int getPort()

获取此 URL 的端口号。

返回：

端口号，如果未设置端口，则为 -1

getDefaultPort

public int getDefaultPort()

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

返回：

端口号

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 中的虚拟主机不一致。

覆盖：

类 Object 中的等于

参数：

参数名称	参数描述
obj	要比较的 URL。

返回：

如果对象相同，则为 true； 否则为false。

hashCode

public int hashCode()

创建一个适合哈希表索引的整数。

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

覆盖：

类 Object 中的 hashCode

返回：

此 URL 的哈希码。

sameFile

public boolean sameFile(URL other)

比较两个 URL，不包括片段组件。

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

参数：

参数名称	参数描述
other	要比较的 URL。

返回:

如果它们引用相同的远程对象，则为 true； 否则为false。

toString

public String toString()

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

覆盖：

类 Object 中的 toString

返回：

此对象的字符串表示形式。

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 实例。

Throws:

Throw名称	Throw描述
URISyntaxException	如果此 URL 未严格按照 RFC2396 格式化并且无法转换为 URI。

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。

返回:

链接到 URL 的 URLConnection。

Throws:

Throw名称	Throw描述
IOException	如果发生 I/O 异常。

openConnection

public URLConnection openConnection(Proxy proxy) throws IOException

与 openConnection() 相同，只是连接将通过指定的代理进行； 不支持代理的协议处理程序将忽略代理参数并建立正常连接。 调用此方法会抢占系统的默认 ProxySelector 设置。

参数：

参数名称	参数描述
proxy	建立此连接的代理。 如果需要直接连接，则应指定 Proxy.NO_PROXY。

返回：

到 URL 的 URLConnection。

Throws:

Throw名称	Throw描述
IOException	如果发生 I/O 异常。
SecurityException	如果存在安全管理器并且调用者无权连接到代理。
IllegalArgumentException	如果 proxy 为 null，或者 proxy 的类型错误，将被抛出
UnsupportedOperationException	如果实现协议处理程序的子类不支持此方法。

openStream

public InputStream openStream() throws IOException

打开到此 URL 的连接并返回一个 InputStream 以从该连接中读取。 此方法是以下的简写：

     openConnection().getInputStream() 

返回：

用于从 URL 连接读取的输入流。

Throws:

Throw名称	Throw描述
IOException	如果发生 I/O 异常。

getContent

public Object getContent() throws IOException

获取此 URL 的内容。 此方法是以下的简写：

     openConnection().getContent() 

返回：

此 URL 的内容。

Throws:

Throw名称	Throw描述
IOException	如果发生 I/O 异常。

getContent

public Object getContent(Class[] classes) throws IOException

获取此 URL 的内容。 此方法是以下的简写：

     openConnection().getContent(Class[]) 

参数:

参数名称	参数描述
classes	Java 类型的数组

返回：

此 URL 的内容对象，它是 classes 数组中指定的类型的第一个匹配项。 如果不支持任何请求的类型，则为 null。

Throws:

Throw名称	Throw描述
IOException	如果发生 I/O 异常。

setURLStreamHandlerFactory

public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)

设置应用程序的 URLStreamHandlerFactory。 此方法在给定的 Java 虚拟机中最多可以调用一次。

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

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

参数：

参数名称	参数描述
fac	想要的工厂

Throws:

Throw名称	Throw描述
Error	如果应用程序已经设置了工厂。
SecurityException	如果存在安全管理器并且其 checkSetFactory 方法不允许该操作。