模块 java.base
包 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 ，所以 put 和 putAll 方法可以应用于 Properties 对象。强烈建议不要使用它们，因为它们允许调用者插入其键或值不是 Strings 的条目。应该改用 setProperty 方法。如果在包含非 String 键或值的“受损”Properties 对象上调用 store 或 save 方法，调用将失败。同样，如果在包含非 String 密钥的“受损”Properties 对象上调用 propertyNames 或 list 方法，调用将失败。

此类的“集合视图”（即 entrySet()、keySet() 和 values()）的 iterator 方法返回的迭代器可能不会快速失败（与 Hashtable 实现不同）。这些迭代器保证只遍历一次构造时存在的元素，并且可能（但不保证）反映构造后的任何修改。

load(Reader) / store(Writer, String) 方法以下面指定的简单的面向行的格式从基于字符的流加载和存储属性。 load(InputStream) / store(OutputStream, String) 方法与 load(Reader)/store(Writer, String) 对的工作方式相同，只是输入/输出流采用 ISO 8859-1 字符编码。不能直接用这种编码表示的字符可以使用 Unicode 转义符编写，如第 3.3 节中所定义Java 语言规范;转义序列中只允许使用单个“u”字符。

loadFromXML(InputStream) 和 storeToXML(OutputStream, String, 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) 是not导出或导入属性时访问；它仅用作唯一标识 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 对象而不需要外部同步。

API 注意：
Properties 类不从其超类 Hashtable 继承负载因子的概念。
自从：
1.0
参见：

  • 字段详细信息

    • defaults

      protected volatile Properties  defaults
      包含此属性列表中未找到的任何键的默认值的属性列表。

  • 构造方法详细信息

    • Properties

      public Properties()
      创建一个没有默认值的空属性列表。
      实现注意事项：
      使用此构造函数创建的 Properties 对象的初始容量未指定。

    • Properties

      public Properties(int initialCapacity)
      创建一个没有默认值的空属性列表，其初始大小可容纳指定数量的元素，而无需动态调整大小。
      参数：
      initialCapacity - Properties 的大小将适应这么多元素
      抛出：
      IllegalArgumentException - 如果初始容量小于零。

    • Properties

      public Properties(Properties  defaults)
      创建具有指定默认值的空属性列表。
      实现注意事项：
      使用此构造函数创建的 Properties 对象的初始容量未指定。
      参数：
      defaults - 默认值。

  • 方法详情

    • setProperty

      public Object  setProperty(String  key, String  value)
      调用 Hashtable 方法 put 。提供与 getProperty 方法的并行性。强制使用字符串作为属性键和值。返回的值是 Hashtable 调用 put 的结果。
      参数：
      key - 要放入此属性列表中的键。
      value - 对应于 key 的值。
      返回：
      此属性列表中指定键的先前值，如果没有则为 null。
      自从：
      1.2
      参见：

    • load

      public void load(Reader  reader) throws IOException
      以简单的面向行的格式从输入字符流中读取属性列表（键和元素对）。

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

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

      如果逻辑行分布在多个自然行中，则转义行终止符序列的反斜杠、行终止符序列以及下一行开头的任何空格对键或元素值没有影响。键和元素解析（加载时）的其余讨论将假设构成键和元素的所有字符在行继续字符被删除后出现在单个自然行上。请注意，它是not仅检查行终止符序列之前的字符就足以确定行终止符是否被转义；要转义的行终止符必须有奇数个连续的反斜杠。由于输入是从左到右处理的，因此非零偶数 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"
      注意，每个\前都有一个空格，所以最终结果中每个逗号后都会有一个空格；续行上的 \ 、行终止符和前导空格仅被丢弃并且是not替换为一个或多个其他字符。

      作为第三个示例，该行：

      cheeses
      指定键为 "cheeses"，关联元素为空字符串 ""。

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

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

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

      参数：
      reader - 输入字符流。
      抛出：
      IOException - 如果从输入流读取时发生错误。
      IllegalArgumentException - 如果输入中出现格式错误的 Unicode 转义符。
      NullPointerException - 如果 reader 为空。
      自从：
      1.6

    • load

      public void load(InputStream  inStream) throws IOException
      从输入字节流中读取属性列表（键和元素对）。输入流采用load(Reader) 中指定的简单的面向行的格式，并假定使用 ISO 8859-1 字符编码；即每个字节是一个 Latin1 字符。不在 Latin1 中的字符和某些特殊字符使用 Unicode 转义符在键和元素中表示，如第 3.3 节中所定义Java 语言规范.

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

      参数：
      inStream - 输入流。
      抛出：
      IOException - 如果从输入流读取时发生错误。
      IllegalArgumentException - 如果输入流包含格式错误的 Unicode 转义序列。
      NullPointerException - 如果 inStream 为空。
      自从：
      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 对象包含任何不是 Strings 的键或值。

    • store

      public void store(Writer  writer, String  comments) throws IOException
      以适合使用 load(Reader) 方法的格式将此 Properties 表中的此属性列表（键和元素对）写入输出字符流。

      此 Properties 表（如果有）的默认表中的属性是not用这种方法写出来。

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

      如果 java.properties.date 在命令行上设置且非空（由 String.isEmpty 确定），则写入注释行如下。首先，写入一个 # 字符，然后是属性的内容，然后是行分隔符。系统属性值中的任何行终止符的处理方式与上述注释参数相同。如果系统属性未设置或为空，则注释行如下所示。首先，写入一个 # 字符，然后是使用 Date.toString 方法格式化的当前日期和时间，然后是行分隔符。

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

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

      实现要求：
      键和元素以 entrySet() 中键的自然排序顺序写入，除非 entrySet() 被子类覆盖以返回与 super.entrySet() 不同的值。
      参数：
      writer - 输出字符流编写器。
      comments - 属性列表的描述。
      抛出：
      IOException - 如果将此属性列表写入指定的输出流会抛出 IOException。
      ClassCastException - 如果此 Properties 对象包含任何不是 Strings 的键或值。
      NullPointerException - 如果 writer 为空。
      自从：
      1.6

    • store

      public void store(OutputStream  out, String  comments) throws IOException
      将此 Properties 表中的此属性列表（键和元素对）以适合使用 load(InputStream) 方法加载到 Properties 表中的格式写入输出流。

      此 Properties 表（如果有）的默认表中的属性是not用这种方法写出来。

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

      • 该流是使用 ISO 8859-1 字符编码编写的。
      • 注释中不是 Latin-1 的字符写为 \uxxxx为他们适当的 unicode 十六进制值xxxx.
      • 属性键或值中小于\u0020的字符和大于\u007E的字符写为\uxxxx为适当的十六进制值xxxx.

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

      参数：
      out - 输出流。
      comments - 属性列表的描述。
      抛出：
      IOException - 如果将此属性列表写入指定的输出流会抛出 IOException。
      ClassCastException - 如果此 Properties 对象包含任何不是 Strings 的键或值。
      NullPointerException - 如果 out 为空。
      自从：
      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 属性。

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

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

      参数：
      in - 从中读取 XML 文档的输入流。
      抛出：
      IOException - 如果从指定的输入流读取结果为 IOException 。
      UnsupportedEncodingException - 如果可以读取文档的编码声明并且它指定了不支持的编码
      InvalidPropertiesFormatException - 输入流中的数据不构成具有强制文档类型的有效 XML 文档。
      NullPointerException - 如果 in 为空。
      自从：
      1.5
      参见：

    • 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 为空。
      ClassCastException - 如果此 Properties 对象包含任何不是 Strings 的键或值。
      自从：
      1.5
      参见：

    • 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，那么文档中将不会存储任何评论。

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

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

      此方法的行为与 storeToXML(OutputStream os, String comment, Charset charset) 相同，只是它将 查看字符集 使用给定的编码名称。

      参数：
      os - 在其上发出 XML 文档的输出流。
      comment - 属性列表的描述，如果不需要注释，则为 null。
      encoding - 受支持的 字符编码 的名称
      抛出：
      IOException - 如果写入指定的输出流导致 IOException 。
      UnsupportedEncodingException - 如果实现不支持编码。
      NullPointerException - 如果 os 是 null，或者如果 encoding 是 null。
      ClassCastException - 如果此 Properties 对象包含任何不是 Strings 的键或值。
      自从：
      1.5
      参见：

    • storeToXML

      public void storeToXML(OutputStream  os, String  comment, Charset  charset) throws IOException
      使用指定的编码发出表示此表中包含的所有属性的 XML 文档。

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

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

      如果指定的评论是null，那么文档中将不会存储任何评论。

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

      指定字符集的不可映射字符将被编码为数字字符引用。

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

      参数：
      os - 在其上发出 XML 文档的输出流。
      comment - 属性列表的描述，如果不需要注释，则为 null。
      charset - 字符集
      抛出：
      IOException - 如果写入指定的输出流导致 IOException 。
      NullPointerException - 如果 os 或 charset 是 null。
      ClassCastException - 如果此 Properties 对象包含任何不是 Strings 的键或值。
      自从：
      10
      参见：

    • getProperty

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

    • getProperty

      public String  getProperty(String  key, String  defaultValue)
      在此属性列表中搜索具有指定键的属性。如果在此属性列表中未找到键，则递归地检查默认属性列表及其默认值。如果未找到该属性，该方法将返回默认值参数。
      参数：
      key - 哈希表键。
      defaultValue - 默认值。
      返回：
      此属性列表中具有指定键值的值。
      参见：

    • propertyNames

      public Enumeration <?> propertyNames()
      返回此属性列表中所有键的枚举，如果尚未从主属性列表中找到同名键，则包括默认属性列表中的不同键。
      返回：
      此属性列表中所有键的枚举，包括默认属性列表中的键。
      抛出：
      ClassCastException - 如果此属性列表中的任何键不是字符串。
      参见：

    • stringPropertyNames

      public Set <String > stringPropertyNames()
      从此属性列表返回一组不可修改的键，其中键及其对应的值是字符串，如果尚未从主属性列表中找到同名键，则包括默认属性列表中的不同键。键或值不是 String 类型的属性将被忽略。

      返回的集合不受此 Properties 对象的支持。对此 Properties 对象的更改不会反映在返回的集合中。

      返回：
      此属性列表中的一组不可修改的键，其中键及其对应的值是字符串，包括默认属性列表中的键。
      自从：
      1.6
      参见：

    • list

      public void list(PrintStream  out)
      将此属性列表打印到指定的输出流。此方法对调试很有用。
      参数：
      out - 输出流。
      抛出：
      ClassCastException - 如果此属性列表中的任何键不是字符串。

    • list

      public void list(PrintWriter  out)
      将此属性列表打印到指定的输出流。此方法对调试很有用。
      参数：
      out - 输出流。
      抛出：
      ClassCastException - 如果此属性列表中的任何键不是字符串。
      自从：
      1.1