鸿蒙OS Properties

Properties

java.lang.Object

|---java.util.Dictionary<K,V&

|---|---java.util.Hashtable<Object,Object&

|---|---|---java.util.Properties

public class Properties
extends Hashtable<Object,Object>

Properties 类表示一组持久的属性。 属性可以保存到流中或从流中加载。 属性列表中的每个键及其对应的值都是一个字符串。

一个属性列表可以包含另一个属性列表作为其“默认值”； 如果在原始属性列表中找不到属性键，则搜索第二个属性列表。

因为 Properties 继承自 Hashtable，所以 put 和 putAll 方法可以应用于 Properties 对象。 强烈建议不要使用它们，因为它们允许调用者插入键或值不是字符串的条目。 应该改用 setProperty 方法。 如果在包含非字符串键或值的“受损”属性对象上调用存储或保存方法，则调用将失败。 类似地，如果在包含非字符串键的“受损”属性对象上调用 propertyNames 或 list 方法，则调用将失败。

load(Reader) / store(Writer, String) 方法以下面指定的简单的面向行的格式从基于字符的流中加载和存储属性。 load(InputStream) / store(OutputStream, String) 方法与 load(Reader)/store(Writer, String) 对的工作方式相同，除了输入/输出流以 ISO 8859-1 字符编码进行编码。 不能用这种编码直接表示的字符可以使用《Java™ 语言规范》第 3.3 节中定义的 Unicode 转义来编写； 转义序列中只允许使用单个 'u' 字符。 native2ascii 工具可用于将属性文件与其他字符编码进行转换。

loadFromXML(java.io.InputStream) 和 storeToXML(java.io.OutputStream,java.lang.String,java.lang.String) 方法以简单的 XML 格式加载和存储属性。 默认情况下使用 UTF-8 字符编码，但是如果需要，可以指定特定的编码。 实现需要支持 UTF-8 和 UTF-16，并且可能支持其他编码。 XML 属性文档具有以下 DOCTYPE 声明：

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 

请注意，导出或导入属性时不会访问系统 URI (http://java.sun.com/dtd/properties.dtd)； 它仅用作唯一标识 DTD 的字符串，即：

    <?xml version="1.0" encoding="UTF-8"?>


    <!-- DTD for properties -->


    <!ELEMENT properties ( comment?, entry* ) >


    <!ATTLIST properties version CDATA #FIXED "1.0">


    <!ELEMENT comment (#PCDATA) >


    <!ELEMENT entry (#PCDATA) >


    <!ATTLIST entry key CDATA #REQUIRED>

此类是线程安全的：多个线程可以共享一个 Properties 对象，而无需外部同步。

嵌套类摘要

从接口 java.util.Map 继承的嵌套类/接口
Map.EntryK,V

字段摘要

修饰符和类型	字段	描述
protected Properties	defaults	一个属性列表，其中包含此属性列表中未找到的任何键的默认值。

构造函数摘要

构造函数	描述
Properties()	创建一个没有默认值的空属性列表。
Properties(Properties defaults)	创建具有指定默认值的空属性列表。

方法总结

修饰符和类型	方法	描述
String	getProperty(String key)	在此属性列表中搜索具有指定键的属性。
String	getProperty(String key, String defaultValue)	在此属性列表中搜索具有指定键的属性。
void	list(PrintStream out)	将此属性列表打印到指定的输出流。
void	list(PrintWriter out)	将此属性列表打印到指定的输出流。
void	load(InputStream inStream)	从输入字节流中读取属性列表（键和元素对）。
void	load(Reader reader)	以简单的面向行的格式从输入字符流中读取属性列表（键和元素对）。
void	loadFromXML(InputStream in)	将指定输入流上的 XML 文档表示的所有属性加载到此属性表中。
Enumeration<?>	propertyNames()	如果尚未从主属性列表中找到同名的键，则返回此属性列表中所有键的枚举，包括默认属性列表中的不同键。
void	save(OutputStream out, String comments)	已弃用。 如果在保存属性列表时发生 I/O 错误，此方法不会引发 IOException。 保存属性列表的首选方法是通过 store(OutputStream out, String comments) 方法或 storeToXML(OutputStream os, String comment) 方法。
Object	setProperty(String key, String value)	调用 Hashtable 方法 put。
void	store(OutputStream out, String comments)	将此属性表中的此属性列表（键和元素对）以适合使用 load(InputStream) 方法加载到属性表的格式写入输出流。
void	store(Writer writer, String comments)	将此属性表中的属性列表（键和元素对）以适合使用 load(Reader) 方法的格式写入输出字符流。
void	storeToXML(OutputStream os, String comment)	发出表示此表中包含的所有属性的 XML 文档。
void	storeToXML(OutputStream os, String comment, String encoding)	使用指定的编码发出表示此表中包含的所有属性的 XML 文档。
SetString	stringPropertyNames()	返回此属性列表中的一组键，其中键及其对应的值是字符串，如果尚未从主属性列表中找到同名的键，则包括默认属性列表中的不同键。

从类 java.util.Hashtable 继承的方法
clear, clone, compute, computeIfAbsent, computeIfPresent, contains, containsKey, containsValue, elements, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keys, keySet, merge, put, putAll, putIfAbsent, rehash, remove, remove, replace, replace, replaceAll, size, toString, values

从类 java.lang.Object 继承的方法
finalize, getClass, notify, notifyAll, wait, wait, wait

字段详细信息

defaults

protected Properties defaults

一个属性列表，其中包含此属性列表中未找到的任何键的默认值。

构造函数详细信息

Properties

public Properties()

创建一个没有默认值的空属性列表。

Properties

public Properties(Properties defaults)

创建具有指定默认值的空属性列表。

参数：

参数名称	参数描述
defaults	默认值。

方法详情

setProperty

public Object setProperty(String key, String value)

调用 Hashtable 方法 put。 提供与 getProperty 方法的并行性。 强制对属性键和值使用字符串。 返回的值是对 put 的 Hashtable 调用的结果。

参数：

参数名称	参数描述
key	要放入此属性列表的键。
value	键对应的值。

返回:

此属性列表中指定键的前一个值，如果没有，则返回 null。

load

public void load(Reader reader) throws IOException

以简单的面向行的格式从输入字符流中读取属性列表（键和元素对）。

属性按行处理。线有两种，自然线和逻辑线。自然行定义为由一组行终止符（\n 或 \r 或 \r\n）或流的末尾终止的字符行。自然行可以是空行、注释行，或者包含全部或部分关键元素对。逻辑行包含键元素对的所有数据，通过使用反斜杠字符转义行终止符序列，这些数据可以分布在多个相邻的自然行中。请注意，不能以这种方式扩展注释行；作为注释的每个自然行都必须有自己的注释指示符，如下所述。从输入中读取行，直到到达流的末尾。

仅包含空白字符的自然行被视为空白并被忽略。注释行有一个 ASCII '#' 或 '!'作为它的第一个非空白字符；注释行也被忽略并且不编码关键元素信息。除了行终止符之外，此格式还考虑字符空格（''、'\u0020'）、制表符（'\t'、'\u0009'）和换页符（'\f'、'\u000C'）是空白。

如果逻辑行分布在多个自然行中，则转义行终止符序列的反斜杠、行终止符序列以及下一行开头的任何空白对键或元素值没有影响。键和元素解析（加载时）的其余讨论将假定构成键和元素的所有字符在删除行继续字符后出现在单个自然行上。请注意，仅检查行终止符序列之前的字符来确定行终止符是否被转义是不够的；要转义行终止符，必须有奇数个连续的反斜杠。由于输入是从左到右处理的，因此在行终止符（或其他地方）之前的非零偶数个 2n 个连续反斜杠在转义处理之后对 n 个反斜杠进行编码。

键包含行中从第一个非空白字符开始到但不包括第一个未转义的“=”、“:”或除行终止符以外的空白字符的所有字符。所有这些键终止字符都可以包含在键中，方法是用前面的反斜杠字符转义它们；例如，

\:\=

将是两个字符的键“：=”。可以使用 \r 和 \n 转义序列包含行终止符。跳过键后的任何空格；如果键后面的第一个非空白字符是“=”或“:”，则忽略它，并且也跳过它后面的任何空白字符。该行上所有剩余的字符都成为相关元素字符串的一部分；如果没有剩余字符，则元素为空字符串“”。一旦识别出构成键和元素的原始字符序列，就如上所述执行转义处理。

例如，以下三行中的每一行都指定了键“Truth”和关联的元素值“Beauty”：

 Truth = Beauty
  Truth:Beauty
 Truth                    :Beauty

作为另一个示例，以下三行指定了一个属性：

 fruits                           apple, banana, pear, \
 *                                  cantaloupe, watermelon, \
 *                                  kiwi, mango

关键是“fruits”，相关元素是：

"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"

请注意，每个 \ 之前都会出现一个空格，因此最终结果中的每个逗号之后都会出现一个空格； 续行上的 \、行终止符和前导空格仅被丢弃，不会被一个或多个其他字符替换。

作为第三个示例，该行：

cheeses 

指定键是“cheeses”，关联元素是空字符串“”。

键和元素中的字符可以用转义序列表示，类似于用于字符和字符串文字的转义序列（参见《Java™ 语言规范》的第 3.3 和 3.10.6 节）。 与用于字符和字符串的字符转义序列和 Unicode 转义的区别是：

• 八进制转义不被识别。
• 字符序列 \b 不代表退格字符。
• 该方法不会将无效转义字符之前的反斜杠字符 \ 视为错误； 反斜杠被静默删除。 例如，在 Java 字符串中，序列“\z”会导致编译时错误。 相比之下，这种方法会默默地删除反斜杠。 因此，此方法将两个字符序列“\b”视为等效于单个字符“b”。
• 单引号和双引号不需要转义； 但是，根据上面的规则，反斜杠前面的单引号和双引号字符仍然会分别产生单引号和双引号字符。
• Unicode 转义序列中只允许使用单个 'u' 字符。

此方法返回后，指定的流保持打开状态。

参数：

参数名称	参数描述
reader	输入字符流。

Throws:

Throw名称	Throw描述
IOException	如果从输入流读取时发生错误。
IllegalArgumentException	如果输入中出现格式错误的 Unicode 转义。

load

public void load(InputStream inStream) throws IOException

从输入字节流中读取属性列表（键和元素对）。 输入流采用 load(Reader) 中指定的简单的面向行的格式，并假定使用 ISO 8859-1 字符编码； 也就是说，每个字节都是一个 Latin1 字符。 非 Latin1 中的字符和某些特殊字符，使用《Java™ 语言规范》第 3.3 节中定义的 Unicode 转义在键和元素中表示。

此方法返回后，指定的流保持打开状态。

参数：

参数名称	参数描述
inStream	输入流。

Throws:

Throw名称	Throw描述
IOException	如果从输入流读取时发生错误。
IllegalArgumentException	如果输入流包含格式错误的 Unicode 转义序列。

save

@Deprecated public void save(OutputStream out, String comments)

已弃用。 如果在保存属性列表时发生 I/O 错误，此方法不会引发 IOException。 保存属性列表的首选方法是通过 store(OutputStream out, String comments) 方法或 storeToXML(OutputStream os, String comment) 方法。

调用 store(OutputStream out, String comments) 方法并抑制抛出的 IOExceptions。

参数：

参数名称	参数描述
out	一个输出流。
comments	属性列表的描述。

Throws:

Throw名称	Throw描述
ClassCastException	如果此 Properties 对象包含任何不是字符串的键或值。

store

public void store(Writer writer, String comments) throws IOException

将此属性表中的属性列表（键和元素对）以适合使用 load(Reader) 方法的格式写入输出字符流。

此属性表的默认表中的属性（如果有）不会通过此方法写出。

如果注释参数不为空，则首先将 ASCII # 字符、注释字符串和行分隔符写入输出流。因此，评论可以用作识别评论。换行符 ('\n')、回车符 ('\r') 或在注释中紧跟换行符的回车符中的任何一个都将替换为由 Writer 生成的行分隔符，并且如果下一个字符评论中不是字符#或字符！然后在该行分隔符之后写出一个 ASCII #。

接下来，总是写入一个注释行，由一个 ASCII # 字符、当前日期和时间（就好像由 Date 的 toString 方法生成的当前时间一样）和一个由 Writer 生成的行分隔符组成。

然后写出此属性表中的每个条目，每行一个。对于每个条目，写入键字符串，然后是 ASCII =，然后是关联的元素字符串。对于键，所有空格字符都写有前面的 \ 字符。对于元素，前导空格字符，而不是嵌入或尾随空格字符，用前面的 \ 字符写入。键和元素字符 #、!、= 和 : 前面带有反斜杠，以确保它们被正确加载。

写入条目后，将刷新输出流。此方法返回后，输出流保持打开状态。

参数：

参数名称	参数描述
writer	输出字符流编写器。
comments	属性列表的描述。

Throws:

Throw名称	Throw描述
IOException	如果将此属性列表写入指定的输出流会引发 IOException。
ClassCastException	如果此 Properties 对象包含任何不是字符串的键或值。
NullPointerException	如果 writer 为空。

store

public void store(OutputStream out, String comments) throws IOException

将此属性表中的此属性列表（键和元素对）以适合使用 load(InputStream) 方法加载到属性表的格式写入输出流。

此属性表的默认表中的属性（如果有）不会通过此方法写出。

该方法输出注释、属性键和值的格式与 store(Writer) 中指定的格式相同，但有以下区别：

• 流是使用 ISO 8859-1 字符编码编写的。
• 注释中非 Latin-1 的字符被写为 \uxxxx，因为它们的相应 unicode 十六进制值 xxxx。
• 属性键或值中小于 \u0020 的字符和大于 \u007E 的字符写为 \uxxxx 以对应相应的十六进制值 xxxx。

写入条目后，将刷新输出流。 此方法返回后，输出流保持打开状态。

参数：

参数名称	参数描述
out	一个输出流。
comments	属性列表的描述。

Throws:

Throw名称	Throw描述
IOException	如果将此属性列表写入指定的输出流会引发 IOException。
ClassCastException	如果此 Properties 对象包含任何不是字符串的键或值。
NullPointerException	如果 out 为空。

loadFromXML

public void loadFromXML(InputStream in) throws IOException, InvalidPropertiesFormatException

将指定输入流上的 XML 文档表示的所有属性加载到此属性表中。

XML 文档必须具有以下 DOCTYPE 声明：

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 

此外，文档必须满足上述属性 DTD。

读取使用“UTF-8”或“UTF-16”编码的 XML 文档需要一个实现。 一个实现可能支持额外的编码。

此方法返回后关闭指定的流。

参数：

参数名称	参数描述
in	从中读取 XML 文档的输入流。

Throws:

Throw名称	Throw描述
IOException	如果从指定的输入流中读取会导致 IOException。
UnsupportedEncodingException	如果可以读取文档的编码声明并且它指定了不受支持的编码
InvalidPropertiesFormatException	输入流上的数据不构成具有强制文档类型的有效 XML 文档。
NullPointerException	如果 in 为空。

storeToXML

public void storeToXML(OutputStream os, String comment) throws IOException

发出表示此表中包含的所有属性的 XML 文档。

调用 props.storeToXML(os, comment) 形式的此方法的行为方式与调用 props.storeToXML(os, comment, "UTF-8"); 完全相同。

参数：

参数名称	参数描述
os	发出 XML 文档的输出流。
comment	属性列表的描述，如果不需要注释，则返回 null。

Throws:

Throw名称	Throw描述
IOException	如果写入指定的输出流会导致 IOException。
NullPointerException	如果 os 为空。
ClassCastException	如果此 Properties 对象包含任何不是字符串的键或值。

storeToXML

public void storeToXML(OutputStream os, String comment, String encoding) throws IOException

使用指定的编码发出表示此表中包含的所有属性的 XML 文档。

XML 文档将具有以下 DOCTYPE 声明：

 <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 

如果指定的评论为空，则文档中不会存储任何评论。

需要一个实现来支持编写使用“UTF-8”或“UTF-16”编码的 XML 文档。 一个实现可能支持额外的编码。

此方法返回后，指定的流保持打开状态。

参数：

参数名称	参数描述
os	发出 XML 文档的输出流。
comment	属性列表的描述，如果不需要注释，则返回 null。
encoding	支持的字符编码的名称

Throws:

Throw名称	Throw描述
IOException	如果写入指定的输出流会导致 IOException。
UnsupportedEncodingException	如果实现不支持编码。
NullPointerException	如果 os 为 null，或者 encoding 为 null。
ClassCastException	如果此 Properties 对象包含任何不是字符串的键或值。

getProperty

public String getProperty(String key)

在此属性列表中搜索具有指定键的属性。 如果在该属性列表中未找到该键，则递归地检查默认属性列表及其默认值。 如果未找到该属性，则该方法返回 null。

参数：

参数名称	参数描述
key	属性键。

返回:

此属性列表中具有指定键值的值。

getProperty

public String getProperty(String key, String defaultValue)

在此属性列表中搜索具有指定键的属性。 如果在该属性列表中未找到该键，则递归地检查默认属性列表及其默认值。 如果未找到该属性，该方法将返回默认值参数。

参数：

参数名称	参数描述
key	哈希表键。
defaultValue	默认值。

返回:

此属性列表中具有指定键值的值。

propertyNames

public Enumeration<?> propertyNames()

如果尚未从主属性列表中找到同名的键，则返回此属性列表中所有键的枚举，包括默认属性列表中的不同键。

返回:

此属性列表中所有键的枚举，包括默认属性列表中的键。

Throws:

Throw名称	Throw描述
ClassCastException	如果此属性列表中的任何键不是字符串。

stringPropertyNames

public SetString stringPropertyNames()

返回此属性列表中的一组键，其中键及其对应的值是字符串，如果尚未从主属性列表中找到同名的键，则包括默认属性列表中的不同键。 省略其键或值不是 String 类型的属性。

返回的集合不受 Properties 对象的支持。 对此属性的更改不会反映在集合中，反之亦然。

返回:

此属性列表中的一组键，其中键及其对应的值是字符串，包括默认属性列表中的键。

list

public void list(PrintStream out)

将此属性列表打印到指定的输出流。 此方法对调试很有用。

参数：

参数名称	参数描述
out	一个输出流。

Throws:

Throw名称	Throw描述
ClassCastException	如果此属性列表中的任何键不是字符串。

list

public void list(PrintWriter out)

将此属性列表打印到指定的输出流。 此方法对调试很有用。

参数：

参数名称	参数描述
out	一个输出流。

Throws:

Throw名称	Throw描述
ClassCastException	如果此属性列表中的任何键不是字符串。