public class Properties
extends Hashtable<Object, Object>
java.lang.Object | |||
↳ | java.util.Dictionary<java.lang.Object, java.lang.Object> | ||
↳ | java.util.Hashtable<java.lang.Object, java.lang.Object> | ||
↳ | java.util.Properties |
Known Direct Subclasses |
Known Indirect Subclasses |
Properties
类表示一组持久属性。 Properties
可以保存到流或从流加载。 属性列表中的每个键及其相应的值都是一个字符串。
属性列表可以包含另一个属性列表作为其“默认值”; 如果在原始属性列表中找不到属性键,则搜索此第二个属性列表。
由于Properties
继承自Hashtable
,因此可以将put
和putAll
方法应用于Properties
对象。 强烈建议不要使用它们,因为它们允许调用者插入其键或值不是Strings
。 应该使用setProperty
方法。 如果在包含非String
密钥或值的“受损” Properties
对象上调用store
或save
方法,则调用将失败。 同样,如果在包含非String
密钥的“受损” Properties
对象上调用对propertyNames
或list
方法的调用,它将失败。
load(Reader)
/ store(Writer, String)
方法以简单的面向行的格式从以下指定的字符流加载和存储属性。 load(InputStream)
/ store(OutputStream, String)
方法的工作方式与加载(Reader)/存储(Writer,String)对相同,除了输入/输出流使用ISO 8859-1字符编码进行编码。 不能直接用这种编码表示的字符可以使用Unicode转义符写入,如The Java™ Language Specification的 3.3节所定义; 在转义序列中只允许一个'u'字符。 native2ascii工具可用于将属性文件转换为其他字符编码并将其转换为其他字符编码。
loadFromXML(InputStream)
和storeToXML(OutputStream, String, String)
方法以简单的XML格式加载和存储属性。 默认情况下使用UTF-8字符编码,但是如果需要可以指定特定的编码。 XML属性文档具有以下DOCTYPE声明:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">Note that the system URI (http://java.sun.com/dtd/properties.dtd) is not accessed when exporting or importing properties; it merely serves as a string to uniquely identify the DTD, which is:
<?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对象,而不需要外部同步。
Fields |
|
---|---|
protected Properties |
defaults 包含此属性列表中找不到的任何键的默认值的属性列表。 |
Public constructors |
|
---|---|
Properties() 创建一个没有默认值的空属性列表。 |
|
Properties(Properties defaults) 用指定的默认值创建一个空的属性列表。 |
Public methods |
|
---|---|
String |
getProperty(String key, String defaultValue) 使用此属性列表中的指定键搜索属性。 |
String |
getProperty(String key) 使用此属性列表中的指定键搜索属性。 |
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) 此方法在API级别1中已弃用。如果在保存属性列表时发生I / O错误,此方法不会抛出IOException。 保存属性列表的首选方法是通过 |
Object |
setProperty(String key, String value) 调用 Hashtable方法 |
void |
store(OutputStream out, String comments) 将此 |
void |
store(Writer writer, String comments) 将此 |
void |
storeToXML(OutputStream os, String comment, String encoding) 使用指定的编码发出表示包含在此表中的所有属性的XML文档。 |
void |
storeToXML(OutputStream os, String comment) 发出表示此表中包含的所有属性的XML文档。 |
Set<String> |
stringPropertyNames() 返回此属性列表中的一组键,其中键和其对应的值是字符串,如果尚未从主属性列表中找到相同名称的键,则其中包括默认属性列表中的不同键。 |
Inherited methods |
|
---|---|
From class java.util.Hashtable
|
|
From class java.util.Dictionary
|
|
From class java.lang.Object
|
|
From interface java.util.Map
|
Properties (Properties defaults)
用指定的默认值创建一个空的属性列表。
Parameters | |
---|---|
defaults |
Properties : the defaults. |
String getProperty (String key, String defaultValue)
使用此属性列表中的指定键搜索属性。 如果在此属性列表中未找到该键,则会递归检查默认属性列表及其默认值。 如果找不到该属性,该方法将返回默认值参数。
Parameters | |
---|---|
key |
String : the hashtable key. |
defaultValue |
String : a default value. |
Returns | |
---|---|
String |
the value in this property list with the specified key value. |
String getProperty (String key)
使用此属性列表中的指定键搜索属性。 如果在此属性列表中未找到该键,则会递归检查默认属性列表及其默认值。 如果找不到该属性,则该方法返回null
。
Parameters | |
---|---|
key |
String : the property key. |
Returns | |
---|---|
String |
the value in this property list with the specified key value. |
void list (PrintStream out)
将此属性列表打印到指定的输出流。 这个方法对调试很有用。
Parameters | |
---|---|
out |
PrintStream : an output stream. |
Throws | |
---|---|
ClassCastException |
if any key in this property list is not a string. |
void list (PrintWriter out)
将此属性列表打印到指定的输出流。 这个方法对调试很有用。
Parameters | |
---|---|
out |
PrintWriter : an output stream. |
Throws | |
---|---|
ClassCastException |
if any key in this property list is not a string. |
void load (InputStream inStream)
从输入字节流中读取属性列表(键和元素对)。 输入流采用简单的面向行的格式,如load(Reader)
,并假定使用ISO 8859-1字符编码; 即每个字节是一个Latin1字符。 Latin1中的字符和某些特殊字符在使用Unicode转义的键和元素中表示,如The Java™ Language Specification的 3.3节中定义的 。
此方法返回后,指定的流将保持打开状态。
Parameters | |
---|---|
inStream |
InputStream : the input stream. |
Throws | |
---|---|
IOException |
if an error occurred when reading from the input stream. |
IllegalArgumentException |
if the input stream contains a malformed Unicode escape sequence. |
void load (Reader reader)
以简单的面向行的格式从输入字符流中读取属性列表(键和元素对)。
属性按行来处理。 有两种线, 自然线和逻辑线 。 自然行被定义为由一组行结束符字符( \n
或\r
或\r\n
)或在流尾部结束的一行字符。 自然线可以是空行或注释行,也可以是全部或部分键元素对。 一条逻辑线包含一个键元素对的所有数据,这些数据可能通过用反斜线字符\
转义线结束符序列而散布在几个相邻的自然线上。 注意注释行不能以这种方式扩展; 每条评论的自然线都必须有自己的评论指标,如下所述。 从输入读取行,直到到达流的末尾。
只包含空白字符的自然线被认为是空白的并被忽略。 注释行有一个ASCII '#'
或'!'
作为其第一个非空白字符; 注释行也被忽略,不对密钥元素信息进行编码。 除了线终止子,此格式考虑字符空间( ' '
, '\u0020'
),标签( '\t'
, '\u0009'
),和形式进料( '\f'
, '\u000C'
)是白色的空间。
如果逻辑行分布在多个自然行上,则反斜杠会转义行结束符序列,行终止符序列以及下一行开始处的任何空格,不会影响键或元素值。 对键和元素解析的讨论(加载时)的其余部分将假定构成键和元素的所有字符在删除行连续字符后出现在单个自然线上。 请注意,这是不够的,只检查字符行终止序列之前,以决定是否行结束逃脱; 必须有一个奇数的连续反斜线才能被转义出来。 由于输入从左加工成右,非零行终止(或其它地方)之前偶数的2个n个连续的反斜杠转义处理后编码成n个反斜杠。
关键包含了所有的从第一个非空格字符以及高达行的字符,但不包括第一个转义'='
, ':'
,或大于行结束符等空白字符。 所有这些关键的终止字符都可以通过用前一个反斜杠字符转义来包含在密钥中; 例如,
\:\=
将是两个字符的键":="
。 可以使用\r
和\n
转义序列包含行结束符字符。 跳过密钥后的任何空格; 如果密钥之后的第一个非空白字符是'='
或':'
,那么它将被忽略,并且其后的所有空白字符也会被跳过。 该行上的所有剩余字符都成为关联元素字符串的一部分; 如果没有剩余字符,则元素为空字符串""
。 一旦识别了构成密钥和元素的原始字符序列,则如上所述执行转义处理。
例如,以下三行中的每一行都指定密钥 "Truth"
和关联的元素值 "Beauty"
:
Truth = Beauty Truth:Beauty Truth :BeautyAs another example, the following three lines specify a single property:
fruits apple, banana, pear, \ cantaloupe, watermelon, \ kiwi, mangoThe key is
"fruits"
and the associated element is:
"apple, banana, pear, cantaloupe, watermelon, kiwi, mango"Note that a space appears before each
\
so that a space will appear after each comma in the final result; the
\
, line terminator, and leading white space on the continuation line are merely discarded and are
not replaced by one or more other characters.
作为第三个例子,该行:
cheesesspecifies that the key is
"cheeses"
and the associated element is the empty string
""
.
键和元素中的字符可以用与字符和字符串文字相似的转义序列表示(请参阅The Java™ Language Specification的第3.3节和第3.10.6 节 )。 与用于字符和字符串的字符转义序列和Unicode转义不同之处在于:
\b
does not represent a backspace character. \
, before a non-valid escape character as an error; the backslash is silently dropped. For example, in a Java string the sequence "\z"
would cause a compile time error. In contrast, this method silently drops the backslash. Therefore, this method treats the two character sequence "\b"
as equivalent to the single character 'b'
. 此方法返回后,指定的流将保持打开状态。
Parameters | |
---|---|
reader |
Reader : the input character stream. |
Throws | |
---|---|
IOException |
if an error occurred when reading from the input stream. |
IllegalArgumentException |
if a malformed Unicode escape appears in the input. |
void loadFromXML (InputStream in)
将指定输入流上由XML文档表示的所有属性加载到此属性表中。
XML文档必须具有以下DOCTYPE声明:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">Furthermore, the document must satisfy the properties DTD described above.
此方法返回后,指定的流将关闭。
Parameters | |
---|---|
in |
InputStream : the input stream from which to read the XML document. |
Throws | |
---|---|
IOException |
if reading from the specified input stream results in an IOException. |
InvalidPropertiesFormatException |
Data on input stream does not constitute a valid XML document with the mandated document type. |
NullPointerException |
if in is null. |
Enumeration<?> propertyNames ()
返回此属性列表中所有键的枚举,如果尚未从主属性列表中找到相同名称的键,则返回默认属性列表中的不同键。
Returns | |
---|---|
Enumeration<?> |
an enumeration of all the keys in this property list, including the keys in the default property list. |
Throws | |
---|---|
ClassCastException |
if any key in this property list is not a string. |
void save (OutputStream out, String comments)
此方法在API级别1中已弃用。
如果在保存属性列表时发生I / O错误,此方法不会抛出IOException。 保存属性列表的首选方法是通过store(OutputStream out, String comments)
方法或storeToXML(OutputStream os, String comment)
方法。
调用 store(OutputStream out, String comments)
方法并抑制抛出的IOException。
Parameters | |
---|---|
out |
OutputStream : an output stream. |
comments |
String : a description of the property list. |
Throws | |
---|---|
ClassCastException |
if this Properties object contains any keys or values that are not Strings . |
Object setProperty (String key, String value)
调用Hashtable方法put
。 提供与getProperty方法的并行性。 强制使用字符串作为属性键和值。 返回的值是Hashtable调用put
的结果。
Parameters | |
---|---|
key |
String : the key to be placed into this property list. |
value |
String : the value corresponding to key. |
Returns | |
---|---|
Object |
the previous value of the specified key in this property list, or null if it did not have one. |
也可以看看:
void store (OutputStream out, String comments)
将此 Properties
表中的属性列表(键和元素对)写入输出流,格式适合使用 load(InputStream)
方法加载到 Properties
表中。
此 Properties
表(如果有)的默认值表中的属性 不会通过此方法写出。
此方法以与 store(Writer)
指定的格式相同的格式输出注释,属性键和值,但有以下区别:
\u
xxxx for their appropriate unicode hexadecimal value xxxx. \u0020
and characters greater than \u007E
in property keys or values are written as \u
xxxx for the appropriate hexadecimal value xxxx. 输入完成后,输出流将被刷新。 此方法返回后,输出流将保持打开状态。
Parameters | |
---|---|
out |
OutputStream : an output stream. |
comments |
String : a description of the property list. |
Throws | |
---|---|
IOException |
if writing this property list to the specified output stream throws an IOException. |
ClassCastException |
if this Properties object contains any keys or values that are not Strings . |
NullPointerException |
if out is null. |
void store (Writer writer, String comments)
将此 Properties
表中的属性列表(键和元素对)写入输出字符流,格式适合使用 load(Reader)
方法。
此 Properties
表(如果有)的默认值表中的属性 不会通过此方法写出。
如果comments参数不为空,则首先将ASCII #
字符,注释字符串和行分隔符写入输出流。 因此, comments
可以作为识别评论。 任何一个换行符('\ n'),一个回车符('\ r')或一个回车符后面的换行符都会被Writer
生成的行分隔符Writer
,如果下一个字符在注释中不是字符#
或字符!
则在该行分隔符#
写出ASCII #
。
接下来,总是写一条注释行,其中包含ASCII #
字符,当前日期和时间(就像由当前时间的 toString
方法 Date
生成一样)以及由 Writer
生成的行分隔符。
然后写出此Properties
表中的每个条目,每行一个。 对于每个条目,写入关键字符串,然后是ASCII =
,然后是关联的元素字符串。 对于关键字,所有空格字符都用前面的\
字符写入。 对于元素,前导空格字符,但不包含嵌入或尾随空格字符,用前面的\
字符编写。 键和元素字符#
, !
, =
,和:
写入加上正斜杠,以确保它们被正确装载。
输入完成后,输出流将被刷新。 此方法返回后,输出流将保持打开状态。
Parameters | |
---|---|
writer |
Writer : an output character stream writer. |
comments |
String : a description of the property list. |
Throws | |
---|---|
IOException |
if writing this property list to the specified output stream throws an IOException. |
ClassCastException |
if this Properties object contains any keys or values that are not Strings . |
NullPointerException |
if writer is null. |
void storeToXML (OutputStream os, String comment, String encoding)
使用指定的编码发出表示包含在此表中的所有属性的XML文档。
XML文档将具有以下DOCTYPE声明:
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
如果指定的评论是 null
则不会在文档中存储评论。
此方法返回后,指定的流将保持打开状态。
Parameters | |
---|---|
os |
OutputStream : the output stream on which to emit the XML document. |
comment |
String : a description of the property list, or null if no comment is desired. |
encoding |
String : the name of a supported character encoding |
Throws | |
---|---|
IOException |
if writing to the specified output stream results in an IOException. |
NullPointerException |
if os is null , or if encoding is null . |
ClassCastException |
if this Properties object contains any keys or values that are not Strings . |
也可以看看:
void storeToXML (OutputStream os, String comment)
发出表示此表中包含的所有属性的XML文档。
调用表单 props.storeToXML(os, comment)的这种方法的行为与调用 props.storeToXML(os, comment, "UTF-8");的行为完全相同。
Parameters | |
---|---|
os |
OutputStream : the output stream on which to emit the XML document. |
comment |
String : a description of the property list, or null if no comment is desired. |
Throws | |
---|---|
IOException |
if writing to the specified output stream results in an IOException. |
NullPointerException |
if os is null. |
ClassCastException |
if this Properties object contains any keys or values that are not Strings . |
也可以看看:
Set<String> stringPropertyNames ()
返回此属性列表中的一组键,其中键和其对应的值是字符串,如果尚未从主属性列表中找到相同名称的键,则其中包括默认属性列表中的不同键。 其键或值不是类型String的属性被省略。
返回的集合不支持Properties对象。 对此Properties的更改不会反映在该集合中,反之亦然。
Returns | |
---|---|
Set<String> |
a set of keys in this property list where the key and its corresponding value are strings, including the keys in the default property list. |
也可以看看: