鸿蒙OS URLConnection

URLConnection

java.lang.Object

|—java.net.URLConnection

public abstract class URLConnection
extends Object

抽象类 URLConnection 是表示应用程序和 URL 之间的通信链接的所有类的超类。 此类的实例可用于读取和写入 URL 引用的资源。 通常，创建到 URL 的连接是一个多步骤的过程：—————————-> 时间

1. 连接对象是通过在 URL 上调用 openConnection 方法来创建的。
2. 设置参数和一般请求属性被操纵。
3. 与远程对象的实际连接是使用 connect 方法建立的。
4. 远程对象变为可用。 可以访问远程对象的标头字段和内容。

使用以下方法修改设置参数：

• setAllowUserInteraction
• setDoInput
• setDoOutput
• setIfModifiedSince
• setUseCaches

并使用以下方法修改通用请求属性：

• setRequestProperty

可以使用 setDefaultAllowUserInteraction 和 setDefaultUseCaches 方法设置 AllowUserInteraction 和 UseCaches 参数的默认值。

上面的每个 set 方法都有一个对应的 get 方法来检索参数或通用请求属性的值。 适用的特定参数和一般请求属性是特定于协议的。

以下方法用于在与远程对象建立连接后访问标头字段和内容：

• getContent
• getHeaderField
• getInputStream
• getOutputStream

某些标题字段被频繁访问。 方法：

• getContentEncoding
• getContentLength
• getContentType
• getDate
• getExpiration
• getLastModifed

提供对这些字段的方便访问。 getContentType方法被getContent方法用来判断远程对象的类型； 子类可能会发现重写 getContentType 方法很方便。

在常见情况下，可以忽略所有预连接参数和一般请求属性：预连接参数和请求属性默认为合理值。 对于这个接口的大多数客户端来说，只有两个有趣的方法：getInputStream 和 getContent，它们通过便利方法镜像到 URL 类中。

有关 http 连接的请求属性和标头字段的更多信息，请参见：

 http://www.ietf.org/rfc/rfc2616.txt 

在请求之后对 URLConnection 的 InputStream 或 OutputStream 调用 close() 方法可能会释放与此实例关联的网络资源，除非特定的协议规范为其指定了不同的行为。

字段摘要

构造函数摘要

方法总结

字段详细信息

allowUserInteraction

protected boolean allowUserInteraction

如果为 true，则在允许用户交互（如弹出身份验证对话框）有意义的上下文中检查此 URL。 如果为 false，则不允许用户交互。

该字段的值可以通过 setAllowUserInteraction 方法设置。 它的值由 getAllowUserInteraction 方法返回。 它的默认值是最后一次调用 setDefaultAllowUserInteraction 方法时的参数值。

connected

protected boolean connected

如果为 false，则此连接对象尚未创建到指定 URL 的通信链接。 如果为true，则通信链路已建立。

doInput

protected boolean doInput

此变量由 setDoInput 方法设置。 它的值由 getDoInput 方法返回。

URL 连接可用于输入和/或输出。 将 doInput 标志设置为 true 表示应用程序打算从 URL 连接读取数据。

此字段的默认值为 true。

doOutput

protected boolean doOutput

此变量由 setDoOutput 方法设置。 它的值由 getDoOutput 方法返回。

URL 连接可用于输入和/或输出。 将 doOutput 标志设置为 true 表示应用程序打算将数据写入 URL 连接。

此字段的默认值为 false。

ifModifiedSince

protected long ifModifiedSince

一些协议支持跳过对象的获取，除非对象在某个时间之后被修改过。

非零值给出的时间是自格林威治标准时间 1970 年 1 月 1 日以来的毫秒数。 仅当对象的修改时间比该时间更新时才获取该对象。

此变量由 setIfModifiedSince 方法设置。 它的值由 getIfModifiedSince 方法返回。

该字段的默认值为 0，表示必须始终进行提取。

url

protected URL url

URL 代表万维网上打开此连接的远程对象。

该字段的值可以通过 getURL 方法访问。

此变量的默认值是 URLConnection 构造函数中 URL 参数的值。

useCaches

protected boolean useCaches

如果为 true，则允许协议尽可能使用缓存。 如果为 false，则协议必须始终尝试获取对象的新副本。

该字段由 setUseCaches 方法设置。 它的值由 getUseCaches 方法返回。

它的默认值是在最后一次调用 setDefaultUseCaches 方法时给出的值。

构造函数详细信息

URLConnection

protected URLConnection(URL url)

构造到指定 URL 的 URL 连接。 未创建与 URL 引用的对象的连接。

参数：

方法详情

getFileNameMap

public static FileNameMap getFileNameMap()

从数据文件加载文件名映射（一个 mimetable）。 它将首先尝试加载由“content.types.user.table”属性定义的用户特定表。 如果失败，它会尝试加载默认的内置表。

返回:

文件名映射

setFileNameMap

public static void setFileNameMap(FileNameMap map)

设置 FileNameMap。

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

参数:

Throws:

connect

public abstract void connect() throws IOException

如果此类连接尚未建立，则打开指向此 URL 引用的资源的通信链接。

如果在连接已经打开时调用 connect 方法（由值为 true 的 connected 字段指示），则忽略该调用。

URLConnection 对象经历两个阶段：首先它们被创建，然后它们被连接。 在创建之后和连接之前，可以指定各种选项（例如，doInput 和 UseCaches）。 连接后，尝试设置它们是错误的。 如果需要，依赖于连接的操作（如 getContentLength）将隐式执行连接。

Throws:

setConnectTimeout

public void setConnectTimeout(int timeout)

设置一个指定的超时值，以毫秒为单位，在打开到此 URLConnection 引用的资源的通信链接时使用。 如果在建立连接之前超时到期，则会引发 java.net.SocketTimeoutException。 超时为零被解释为无限超时。

此方法的一些非标准实现可能会忽略指定的超时。 要查看连接超时设置，请调用 getConnectTimeout()。

参数：

Throws:

getConnectTimeout

public int getConnectTimeout()

返回连接超时的设置。

0 返回意味着该选项被禁用（即，无限超时）。

返回:

以毫秒为单位指示连接超时值的 int

setReadTimeout

public void setReadTimeout(int timeout)

将读取超时设置为指定的超时，以毫秒为单位。 当与资源建立连接时，非零值指定从输入流读取时的超时。 如果在有数据可供读取之前超时到期，则会引发 java.net.SocketTimeoutException。 超时为零被解释为无限超时。

此方法的一些非标准实现会忽略指定的超时。 要查看读取超时设置，请调用 getReadTimeout()。

参数：

Throws:

getReadTimeout

public int getReadTimeout()

返回读取超时的设置。 0 返回意味着该选项被禁用（即，无限超时）。

返回:

以毫秒为单位指示读取超时值的 int

getURL

public URL getURL()

返回此 URLConnection 的 URL 字段的值。

返回:

此 URLConnection 的 URL 字段的值。

getContentLength

public int getContentLength()

返回内容长度标头字段的值。

注意： getContentLengthLong() 应该优先于这个方法，因为它返回一个 long ，因此更便携。

返回:

此连接的 URL 引用的资源的内容长度，如果内容长度未知，或者内容长度大于 Integer.MAX_VALUE，则为 -1。

getContentLengthLong

public long getContentLengthLong()

以 long 形式返回 content-length 标头字段的值。

返回:

此连接的 URL 引用的资源的内容长度，如果内容长度未知，则为 -1。

getContentType

public String getContentType()

返回内容类型标头字段的值。

返回:

URL 引用的资源的内容类型，如果不知道，则返回 null。

getContentEncoding

public String getContentEncoding()

返回内容编码标头字段的值。

返回:

URL 引用的资源的内容编码，如果未知，则返回 null。

getExpiration

public long getExpiration()

返回 expires 标头字段的值。

返回:

此 URL 引用的资源的到期日期，如果未知，则为 0。 该值是自 1970 年 1 月 1 日 GMT 以来的毫秒数。

getDate

public long getDate()

返回日期标题字段的值。

返回:

URL 引用的资源的发送日期，如果不知道，则为 0。 返回的值是自 1970 年 1 月 1 日 GMT 以来的毫秒数。

getLastModified

public long getLastModified()

返回最后修改的标头字段的值。 结果是自 1970 年 1 月 1 日 GMT 以来的毫秒数。

返回:

此 URLConnection 引用的资源上次修改的日期，如果未知，则为 0。

getHeaderField

public String getHeaderField(String name)

返回命名标头字段的值。

如果在多次使用可能不同的值设置相同标头的连接上调用，则仅返回最后一个值。

参数：

返回:

命名的标头字段的值，如果标头中没有此类字段，则为 null。

getHeaderFields

public MapString,ListString getHeaderFields()

返回标头字段的不可修改的 Map。 Map 键是表示响应标头字段名称的字符串。 每个 Map 值都是一个不可修改的字符串列表，表示相应的字段值。

返回:

标题字段映射

getHeaderFieldInt

public int getHeaderFieldInt(String name, int Default)

返回解析为数字的命名字段的值。

存在这种形式的 getHeaderField 是因为某些连接类型（例如 http-ng）具有预解析的标头。 该连接类型的类可以覆盖此方法并使解析短路。

参数：

返回:

命名字段的值，解析为整数。 如果字段丢失或格式错误，则返回默认值。

getHeaderFieldLong

public long getHeaderFieldLong(String name, long Default)

返回解析为数字的命名字段的值。

存在这种形式的 getHeaderField 是因为某些连接类型（例如 http-ng）具有预解析的标头。 该连接类型的类可以覆盖此方法并使解析短路。

参数：

返回:

命名字段的值，解析为 long。 如果字段丢失或格式错误，则返回默认值。

getHeaderFieldDate

public long getHeaderFieldDate(String name, long Default)

返回解析为日期的命名字段的值。 结果是命名字段表示的自 1970 年 1 月 1 日 GMT 以来的毫秒数。

存在这种形式的 getHeaderField 是因为某些连接类型（例如 http-ng）具有预解析的标头。 该连接类型的类可以覆盖此方法并使解析短路。

参数:

返回:

字段的值，解析为日期。 如果字段丢失或格式错误，则返回 Default 参数的值。

getHeaderFieldKey

public String getHeaderFieldKey(int n)

返回第 n 个标头字段的键。 如果少于 n+1 个字段，则返回 null。

参数：

返回:

第 n 个标头字段的键，如果少于 n+1 个字段，则返回 null。

getHeaderField

public String getHeaderField(int n)

返回第 n 个标头字段的值。 如果少于 n+1 个字段，则返回 null。

此方法可以与 getHeaderFieldKey 方法结合使用，以遍历消息中的所有标头。

参数：

返回:

第 n 个头字段的值，如果少于 n+1 个字段，则为 null

getContent

public Object getContent() throws IOException

检索此 URL 连接的内容。

该方法首先通过调用 getContentType 方法确定对象的内容类型。 如果这是应用程序第一次看到该特定内容类型，则为该内容类型创建一个内容处理程序：

1. 如果应用程序已经使用 setContentHandlerFactory 方法设置了一个内容处理程序工厂实例，那么该实例的 createContentHandler 方法会以内容类型作为参数被调用； 结果是该内容类型的内容处理程序。

1. 如果尚未设置内容处理程序工厂，或者工厂的 createContentHandler 方法返回 null，则应用程序加载名为：

            sun.net.www.content.<contentType>     

其中 <contentType> 是通过获取内容类型字符串、将所有斜杠字符替换为句点 (‘.’) 以及所有其他非字母数字字符替换为下划线字符 ‘_’ 来形成的。 字母数字字符具体是 26 个大写 ASCII 字母“A”到“Z”、26 个小写 ASCII 字母“a”到“z”和 10 个 ASCII 数字“0”到“9”。 如果指定的类不存在，或者不是 ContentHandler 的子类，则抛出 UnknownServiceException。

返回：

获取的对象。 instanceof 运算符应用于确定返回的特定对象类型。

Throws:

getContent

public Object getContent(Class[] classes) throws IOException

检索此 URL 连接的内容。

参数：

返回：

获取的对象是类数组中指定的类型的第一个匹配项。 如果不支持任何请求的类型，则为 null。 instanceof 运算符应用于确定返回的特定对象类型。

Throws:

getPermission

public Permission getPermission() throws IOException

返回一个权限对象，该对象表示建立由该对象表示的连接所需的权限。如果建立连接不需要权限，则此方法返回 null。默认情况下，此方法返回 java.security.AllPermission。子类应覆盖此方法并返回最能代表与 URL 建立连接所需的权限的权限。例如，表示文件的 URLConnection： URL 将返回 java.io.FilePermission 对象。

返回的权限可能取决于连接的状态。例如，连接前的权限可能与连接后的权限不同。例如，一个 HTTP 服务器，比如 foo.com，可能会将连接重定向到不同的主机，比如 bar.com。连接前连接返回的权限代表连接foo.com所需的权限，连接后返回的权限是bar.com。

权限通常用于两个目的：保护通过 URLConnections 获得的对象的缓存，以及检查接收者了解特定 URL 的权限。在第一种情况下，应在获得对象后获得许可。例如，在 HTTP 连接中，这将表示连接到最终从中获取数据的主机的权限。第二种情况，需要在连接前获得许可并进行测试。

返回:

表示建立此 URLConnection 表示的连接所需的权限的权限对象。

Throws:

getInputStream

public InputStream getInputStream() throws IOException

返回从此打开的连接读取的输入流。 如果读取超时在数据可供读取之前到期，则从返回的输入流读取时可能会引发 SocketTimeoutException。

返回:

从此打开的连接中读取的输入流。

Throws:

getOutputStream

public OutputStream getOutputStream() throws IOException

返回写入此连接的输出流。

返回:

写入此连接的输出流。

Throws:

toString

public String toString()

返回此 URL 连接的字符串表示形式。

覆盖：

类 Object 中的 toString

返回:

此 URLConnection 的字符串表示形式。

setDoInput

public void setDoInput(boolean doinput)

将此 URLConnection 的 doInput 字段的值设置为指定值。

URL 连接可用于输入和/或输出。 如果您打算使用 URL 连接进行输入，请将 DoInput 标志设置为 true，否则设置为 false。 默认值为true。

参数：

Throws:

getDoInput

public boolean getDoInput()

返回此 URLConnection 的 doInput 标志的值。

返回：

此 URLConnection 的 doInput 标志的值。

setDoOutput

public void setDoOutput(boolean dooutput)

将此 URLConnection 的 doOutput 字段的值设置为指定值。

URL 连接可用于输入和/或输出。 如果您打算使用 URL 连接进行输出，请将 DoOutput 标志设置为 true，否则设置为 false。 默认值为false。

参数：

Throws:

getDoOutput

public boolean getDoOutput()

返回此 URLConnection 的 doOutput 标志的值。

返回：

此 URLConnection 的 doOutput 标志的值。

setAllowUserInteraction

public void setAllowUserInteraction(boolean allowuserinteraction)

设置此 URLConnection 的 allowUserInteraction 字段的值。

参数：

Throws:

getAllowUserInteraction

public boolean getAllowUserInteraction()

返回此对象的 allowUserInteraction 字段的值。

返回：

此对象的 allowUserInteraction 字段的值。

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean defaultallowuserinteraction)

将所有未来 URLConnection 对象的 allowUserInteraction 字段的默认值设置为指定值。

参数：

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()

返回 allowUserInteraction 字段的默认值。

默认值为“sticky”，是所有 URLConnections 静态状态的一部分。 此标志适用于创建的下一个和所有后续 URLConnection。

返回:

allowUserInteraction 字段的默认值。

setUseCaches

public void setUseCaches(boolean usecaches)

将此 URLConnection 的 useCaches 字段的值设置为指定值。

一些协议会缓存文档。 有时，重要的是能够“通过”并忽略缓存（例如，浏览器中的“重新加载”按钮）。 如果连接上的 UseCaches 标志为true，则允许连接使用它可以使用的任何缓存。 如果为 false，缓存将被忽略。 默认值来自DefaultUseCaches，默认为true。

参数：

Throws:

getUseCaches

public boolean getUseCaches()

返回此 URLConnection 的 useCaches 字段的值。

返回:

此 URLConnection 的 useCaches 字段的值。

setIfModifiedSince

public void setIfModifiedSince(long ifmodifiedsince)

将此 URLConnection 的 ifModifiedSince 字段的值设置为指定值。

参数：

Throws:

getIfModifiedSince

public long getIfModifiedSince()

返回此对象的 ifModifiedSince 字段的值。

返回:

此对象的 ifModifiedSince 字段的值。

getDefaultUseCaches

public boolean getDefaultUseCaches()

返回 URLConnection 的 useCaches 标志的默认值。

默认值为“sticky”，是所有 URLConnections 静态状态的一部分。 此标志适用于创建的下一个和所有后续 URLConnection。

返回:

URLConnection 的 useCaches 标志的默认值。

setDefaultUseCaches

public void setDefaultUseCaches(boolean defaultusecaches)

将 useCaches 字段的默认值设置为指定值。

参数：

setRequestProperty

public void setRequestProperty(String key, String value)

设置一般请求属性。 如果具有键的属性已存在，则用新值覆盖其值。

注意：HTTP 要求所有可以合法地具有多个具有相同键的实例的请求属性使用逗号分隔的列表语法，该语法允许将多个属性附加到单个属性中。

参数：

Throws:

addRequestProperty

public void addRequestProperty(String key, String value)

添加由键值对指定的通用请求属性。 此方法不会覆盖与同一键关联的现有值。

参数：

Throws:

getRequestProperty

public String getRequestProperty(String key)

返回此连接的命名常规请求属性的值。

参数：

返回:

此连接的命名常规请求属性的值。 如果 key 为 null，则返回 null。

Throws:

getRequestProperties

public MapString,ListString getRequestProperties()

返回此连接的一般请求属性的不可修改 Map。 Map 键是表示请求标头字段名称的字符串。 每个 Map 值都是一个不可修改的字符串列表，表示相应的字段值。

返回:

此连接的一般请求属性的映射。

Throws:

setDefaultRequestProperty

@Deprecated public static void setDefaultRequestProperty(String key, String value)

已弃用。 在获得适当的 URLConnection 实例后，应使用实例特定的 setRequestProperty 方法。 调用此方法将无效。

设置一般请求属性的默认值。 创建 URLConnection 时，会使用这些属性对其进行初始化。

参数：

getDefaultRequestProperty

@Deprecated public static String getDefaultRequestProperty(String key)

已弃用。 在获得适当的 URLConnection 实例后，应使用实例特定的 getRequestProperty 方法。

返回默认请求属性的值。 为每个连接设置默认请求属性。

参数：

返回:

指定键的默认请求属性的值。

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory fac)

设置应用程序的 ContentHandlerFactory。 应用程序最多可以调用一次。

ContentHandlerFactory 实例用于从内容类型构造内容处理程序

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

参数：

Throws:

guessContentTypeFromName

public static String guessContentTypeFromName(String fname)

尝试根据 URL 的指定“文件”组件确定对象的内容类型。 这是覆盖 getContentType 方法的子类可以使用的便捷方法。

参数：

返回:

根据文件名猜测对象的内容类型是什么。

guessContentTypeFromStream

public static String guessContentTypeFromStream(InputStream is) throws IOException

尝试根据输入流开头的字符确定输入流的类型。 覆盖 getContentType 方法的子类可以使用此方法。

理想情况下，不需要此例程。 但是很多 http 服务器返回了不正确的内容类型； 此外，还有很多非标准的扩展。 直接检查字节以确定内容类型通常比相信 http 服务器声明的内容类型更准确。

参数：

返回:

对内容类型的猜测，如果无法确定，则为 null。

Throws: