当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

Properties (Java 2 Platform SE 5.0) - JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

java.util
类 Properties

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<Object,Object>
          java.util.Properties

所有已实现的接口：

Serializable, Cloneable, Map<Object,Object>

直接已知子类：

Provider

---

public class Properties
extends Hashtable<Object,Object>

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

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

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

load 和 store 方法按下面所指定的、简单的面向行的格式加载和存储属性。此格式使用 ISO 8859-1 字符编码。可以使用 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, 序列化表格

---

字段摘要
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	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 方法加载到 Properties 表中的格式，将此 Properties 表中的属性列表（键和元素对）写入输出流。
void	storeToXML(OutputStream os, String comment)           发出一个表示此表中包含的所有属性的 XML 文档。
void	storeToXML(OutputStream os, String comment, String encoding)           使用指定的编码发出一个表示此表中包含的所有属性的 XML 文档。

 

从类 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(InputStream inStream)
          throws IOException

从输入流中读取属性列表（键和元素对）。假定该流使用 ISO 8859-1 字符编码；也就是每个字节是一个 Latin1 字符。对于非 Latin1 的字符和某些特殊字符，可以使用与字符和字符串字面值所用的类似转义序列，以值和元素的形式来表示它们（参见《Java Language Specification》的第 3.3 节和第 3.10.6 节）。 字符和字符串所用的字符转义序列的差别有：

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

如果输入中出现了错误的 Unicode 转义序列，则抛出 IllegalArgumentException。

此方法根据行来处理输入。通过行结束符字符集（\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" 并且关联元素是空字符串 ""。

参数：

inStream - 输入流。

抛出：

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

抛出：

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

---

store

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

以适合使用 load 方法加载到 Properties 表中的格式，将此 Properties 表中的属性列表（键和元素对）写入输出流。使用 ISO 8859-1 字符编码写入该流。

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

如果 comments 变量非 null，则首先将 ASCII # 字符、注释字符串和一个行分隔符写入输出流。因此，该 comments 可用作一个标识注释。

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

然后将此 Properties 表中的所有项写入 out，一次一行。对于每个项而言，先写入键字符串，然后是一个 ASCII =，最后是关联元素字符串。检查键和元素字符串的每个字符，确定是否应将其呈现为转义序列。ASCII 字符 \、制表符、换页符、换行符和回车分别作为 \\、\t、\f、\n 和 \r 写入。小于 \u0020 和大于 \u007E 的字符作为 \uxxxx 写入，其中 xxxx 是该字符相应的十六进制值。对于键，所有写入的空白字符前面都有一个 \ 字符。对于元素，所有写入的前导空白字符（但是不嵌入或尾随空白字符）前面都有一个 \ 字符。所有写入的键和元素字符 #、!、= 和 : 前面都有反斜杠，确保能正确地加载这些字符。

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

参数：

out - 输出流。

comments - 属性列表的描述。

抛出：

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

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

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。

从以下版本开始：

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。

从以下版本开始：

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()

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

返回：

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

另请参见：

Enumeration, defaults

---

list

public void list(PrintStream out)

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

参数：

out - 输出流。

---

list

public void list(PrintWriter out)

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

参数：

out - 输出流。

从以下版本开始：

JDK1.1

---

概述  软件包   类  使用  树  已过时  索引  帮助		JavaTM 2 Platform Standard Ed. 5.0
上一个类   下一个类	框架    无框架
摘要： 嵌套 | 字段 | 构造方法 | 方法	详细信息： 字段 | 构造方法 | 方法

---

提交错误或意见
有关更多的 API 参考资料和开发人员文档，请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述，以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。