类Properties

extends Hashtable<Object,Object>

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

一个属性列表可包含另一个属性列表作为它的“默认值”；如果未能在原有的属性列表中搜索到属性键，则搜索第二个属性列表。

因为 Properties 继承于 Hashtable，所以可对 Properties 对象应用 put 和 putAll 方法。但不建议使用这两个方法，因为它们允许调用者插入其键或值不是 String 的项。相反，应该使用 setProperty 方法。如果在“不安全”的 Properties 对象（即包含非 String 的键或值）上调用 store 或 save 方法，则该调用将失败。类似地，如果在“不安全”的 Properties 对象（即包含非 String 的键）上调用 propertyNames 或 list 方法，则该调用将失败。

load(Reader) / store(Writer, String) 方法按下面所指定的、简单的面向行的格式在基于字符的流中加载和存储属性。除了输入/输出流使用 ISO 8859-1 字符编码外，load(InputStream) / store(OutputStream, String) 方法与 load(Reader)/store(Writer, String) 对的工作方式完全相同。可以使用 Unicode 转义来编写此编码中无法直接表示的字符；转义序列中只允许单个 'u' 字符。可使用 native2ascii 工具对属性文件和其他字符编码进行相互转换。

loadFromXML(InputStream) 和 storeToXML(OutputStream, String, String) 方法按简单的 XML 格式加载和存储属性。默认使用 UTF-8 字符编码，但如果需要，可以指定某种特定的编码。XML 属性文档具有以下 DOCTYPE 声明：

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

注意，导入或导出属性时不 访问系统 URI (http://java.sun.com/dtd/properties.dtd)；该系统 URI 仅作为一个唯一标识 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>
 

从以下版本开始：

JDK1.0

另请参见：

native2ascii tool for Solaris, native2ascii tool for Windows

此类是线程安全的：多个线程可以共享单个 Properties 对象而无需进行外部同步。, 序列化表格

---

字段摘要
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) 方法加载到 Properties 表中的格式，将此 Properties 表中的属性列表（键和元素对）写入输出流。
void	store(Writer writer, String comments) 以适合使用 load(Reader) 方法的格式，将此 Properties 表中的属性列表（键和元素对）写入输出字符。
void	storeToXML(OutputStream os, String comment) 发出一个表示此表中包含的所有属性的 XML 文档。
void	storeToXML(OutputStream os, String comment, String encoding) 使用指定的编码发出一个表示此表中包含的所有属性的 XML 文档。
Set<String>	stringPropertyNames() 返回此属性列表中的键集，其中该键及其对应值是字符串，如果在主属性列表中未找到同名的键，则还包括默认属性列表中不同的键。

从类 java.util.Hashtable 继承的方法

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, 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 方法提供并行性。强制要求为属性的键和值使用字符串。返回值是 Hashtable 调用 put 的结果。

参数：

key - 要置于属性列表中的键。

value - 对应于 key 的值。

返回：

属性列表中指定键的旧值，如果没有值，则为 null。

从以下版本开始：

1.2

另请参见：

getProperty(java.lang.String)

---

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 Language Specification 的 §3.3 节 和 §3.10.6 节）。 字符和字符串所用的字符转义序列和 Unicode 转义的差别有：

• 不识别八进制转义。
• 字符序列 \b 不表示退格字符。
• 该方法并不将无效转义字符前的反斜杠字符 \ 视为错误；只是将反斜杠丢弃。例如，在 Java 字符串中，序列 "\z" 将导致编译时错误。相反，此方法会丢弃该反斜杠。因此，此方法将两字符序列 "\b" 与单字符 'b' 视为等同。
• 转义对于单引号和双引号而言不是必需的；但是根据上面的规则，前面有反斜杠的单引号和双引号字符仍旧分别生成单引号和双引号字符。
• Uniocde 转义序列中只允许单个 'u' 字符。

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

参数：

reader - 输入字符流。

抛出：

IOException - 如果从输入流读取时发生错误。

IllegalArgumentException - 如果输入中出现了错误的 Unicode 转义。

从以下版本开始：

1.6

---

load

public void load(InputStream inStream)
          throws IOException

从输入流中读取属性列表（键和元素对）。输入流按 load(Reader) 中所指定的、简单的面向行的格式，并假定使用 ISO 8859-1 字符编码；即每个字节都是 Latin1 字符。对于非 Latin1 的字符和某些特殊字符，可以使用 Unicode 转义以键和元素的形式来表示它们。

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

参数：

inStream - 输入流。

抛出：

IOException - 如果读取输入流时发生错误。

IllegalArgumentException - 如果输入流包含错误的 Unicode 转义序列。

从以下版本开始：

1.2

---

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 - 属性列表的描述。

抛出：

ClassCastException - 如果此 Properties 对象包含任意非 String 的键或值。

---

store

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

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

对于取自此 Properties 表默认表（如果有的话）的属性，此方法不 将其写入 out。

如果 comments 变量非 null，则首先将 ASCII # 字符、注释字符串和一个行分隔符写入输出流。因此，该 comments 可用作一个标识注释。注释中换行 ('\n')、回车 ('\r') 或回车后直接跟着换行，这些字符中的任意一个都由 Writer 生成的行分隔符替换，如果注释中下一个字符不是 # 字符或 ! 字符，则在该行分隔符后写出 ASCII #。

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

然后将此 Properties 表中的所有项写入 out，一次一行。对于每个项而言，先写入键字符串，然后是一个 ASCII =，最后是关联元素字符串。对于键，所有写入的空白字符前面都有一个 \ 字符。对于元素，所有写入的前导空白字符（但是不嵌入或尾随空白字符）前面都有一个 \ 字符。所有写入的键和元素字符 #、!、= 和 : 前面都有反斜杠，确保能正确地加载这些字符。

写入各个项后，刷新输出流。此方法返回后，输出流仍保持打开状态。

参数：

writer - 输出字符流 writer。

comments - 属性列表的描述。

抛出：

IOException - 如果将此属性列表写入指定的输出流时抛出 IOException。

ClassCastException - 如果此 Properties 对象包含任何不是 String 的键或值。

NullPointerException - 如果 writer 为 null。

从以下版本开始：

1.6

---

store

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

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

此方法未 编写此 Properties 表默认表的属性（如果有）。

此方法以 store(Writer) 中指定的相同格式输出注释、属性键和值，注意以下几点不同：

• 使用 ISO 8859-1 字符编码写入该流。
• 注释中不是 Latin-1 的字符针对其适当的十六进制值 xxxx 以 \uxxxx 的形式写入。
• 属性键或值中小于 \u0020 的字符和大于 \u007E 的字符针对适当的十六进制值 xxxx 以 \uxxxx 的形式写入。

写入各个项后，刷新输出流。此方法返回后，输出流仍保持打开状态。

参数：

out - 输出流。

comments - 属性列表的描述。

抛出：

IOException - 如果将此属性列表写入指定的输出流时，抛出 IOException。

ClassCastException - 如果此 Properties 对象包含任意非 String 的键或值。

NullPointerException - 如果 out 为 null。

从以下版本开始：

1.2

---

loadFromXML

public void loadFromXML(InputStream in)
                 throws IOException,
                        InvalidPropertiesFormatException

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

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

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

而且该文档还必须满足上述属性 DTD 的要求。

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

参数：

in - 从中读取 XML 文档的输入流。

抛出：

IOException - 如果读取指定的输入流导致 IOException。

InvalidPropertiesFormatException - 输入流中的数据没有按要求的文档类型组成有效的 XML 文档。

NullPointerException - 如果 in 为 null。

从以下版本开始：

1.5

另请参见：

storeToXML(OutputStream, String, String)

---

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。

抛出：

IOException - 如果写入指定的输出流导致一个 IOException。

NullPointerException - 如果 os 为 null。

ClassCastException - 如果此 Properties 对象包含任何不是 String 的键或值。

从以下版本开始：

1.5

另请参见：

loadFromXML(InputStream)

---

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">
 

如果指定的注释为 null，则没有注释存储在该文档中。

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

参数：

os - 根据其内容发出 XML 文档的输出流。

comment - 属性列表的描述，如果没有所需的注释，则为 null。

抛出：

IOException - 如果写入指定的输出流导致一个 IOException。

NullPointerException - 如果 os 为 null，或者 encoding 为 null。

ClassCastException - 如果 Properties 对象包含任何不是 String 的键或值。

从以下版本开始：

1.5

另请参见：

loadFromXML(InputStream)

---

getProperty

public String getProperty(String key)

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

参数：

key - 属性键。

返回：

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

另请参见：

setProperty(java.lang.String, java.lang.String), defaults

---

getProperty

public String getProperty(String key,
                          String defaultValue)

用指定的键在属性列表中搜索属性。如果在属性列表中未找到该键，则接着递归检查默认属性列表及其默认值。如果未找到属性，则此方法返回默认值变量。

参数：

key - 哈希表键。

defaultValue - 默认值。

返回：

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

另请参见：

setProperty(java.lang.String, java.lang.String), defaults

---

propertyNames

public Enumeration<?> propertyNames()

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

返回：

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

抛出：

ClassCastException - 如果此属性列表中的任何键不是一个字符串。

另请参见：

Enumeration, defaults, stringPropertyNames()

---

stringPropertyNames

public Set<String> stringPropertyNames()

返回此属性列表中的键集，其中该键及其对应值是字符串，如果在主属性列表中未找到同名的键，则还包括默认属性列表中不同的键。其键或值不是 String 类型的属性被忽略。

返回的 set 不受 Properties 对象支持。对此 Properties 的改变不能在该 set 中反映出来，反之亦然。

返回：

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

从以下版本开始：

1.6

另请参见：

defaults

---

list

public void list(PrintStream out)

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

参数：

out - 输出流。

抛出：

ClassCastException - 如果此属性列表中的任何键不是字符串。

---

list

public void list(PrintWriter out)

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

参数：

out - 输出流。

抛出：

ClassCastException - 如果此属性列表中的任何键不是字符串。

从以下版本开始：

JDK1.1