模块  java.base
软件包  java.util

Class 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方法的调用将失败。

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

    load(Reader) / store(Writer, String)方法以下面指定的简单面向行的格式从基于字符的流加载和存储属性。 除了输入/输出流以ISO 8859-1字符编码进行编码外， load(InputStream) / store(OutputStream, String)方法与加载（Reader）/存储（Writer，String）对的工作方式相同。 无法在此编码中直接表示的字符可以使用Unicode转义编写，如The Java™ Language Specification的第3.3节中所定义; 在转义序列中只允许一个'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）; 它只是作为一个字符串来唯一标识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 Note:
    Properties类不从其超类 Hashtable继承加载因子的概念。
    从以下版本开始：
    1.0
    另请参见：
    Serialized Form

    • 字段详细信息

      • defaults

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

    • 构造方法详细信息

      • Properties

        public Properties()
        创建一个没有默认值的空属性列表。
        Implementation Note:
        未指定使用此构造函数创建的 Properties对象的初始容量。

      • Properties

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

      • Properties

        public Properties​(Properties defaults)
        创建具有指定默认值的空属性列表。
        Implementation Note:
        未指定使用此构造函数创建的 Properties对象的初始容量。
        参数
        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' ）是白色的空间。

        如果逻辑行分布在多个自然行中，则反转行终止符序列的反斜杠，行终止符序列以及后续行开头的任何空格都不会影响键或元素值。 关键和元素解析（加载时）的讨论的其余部分将假设构成键和元素的所有字符在删除行连续字符后出现在单个自然行上。 请注意，这是不够的，只检查字符行终止序列之前，以决定是否行结束逃脱; 必须有奇数个连续的反斜杠才能对行终止符进行转义。 由于输入是从左到右处理的，因此在行终止符（或其他地方）之前的非零偶数个2 n个连续反斜杠在转义处理后编码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" ，关联元素为空字符串"" 。

        键和元素中的字符可以用与字符和字符串文字相似的转义序列表示（请参阅The Java™ Language Specification的3.3和3.10.6 节 ）。 与用于字符和字符串的字符转义序列和Unicode转义的区别是：

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

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

        参数
        reader - 输入字符流。
        异常
        IOException - 如果从输入流中读取时发生错误。
        IllegalArgumentException - 如果输入中出现格式错误的Unicode转义 IllegalArgumentException 。
        NullPointerException - 如果 reader为空。
        从以下版本开始：
        1.6

      • load

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

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

        参数
        inStream - 输入流。
        异常
        IOException - 如果从输入流中读取时发生错误。
        IllegalArgumentException - 如果输入流包含格式错误的Unicode转义序列。
        NullPointerException - 如果 inStream为空。
        从以下版本开始：
        1.2

      • save

        @Deprecated
public void save​(OutputStream out,
                 String comments)
        Deprecated.
        This method does not throw an IOException if an I/O error occurs while saving the property list. The preferred way to save a properties list is via the store(OutputStream out, String comments) method or the storeToXML(OutputStream os, String comment) method.
        调用 store(OutputStream out, String comments)方法并禁止抛出的IOExceptions。
        参数
        out - 输出流。
        comments - 属性列表的描述。
        异常
        ClassCastException - 如果此 Properties对象包含任何非 Strings键或值。

      • store

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

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

        如果comments参数不为null，则首先将ASCII #字符，注释字符串和行分隔符写入输出流。 因此， comments可以作为识别注释。 换行符（'\ n'），回车符（'\ r'）或回车后面的回车符中的任何一个都会被Writer生成的行分隔符Writer ，如果是下一个字符在注释中不是字符#或字符!然后在该行分隔符后写出ASCII # 。

        接下来，始终写入注释行，包括ASCII #字符，当前日期和时间（如果由当前时间的Date的toString方法生成），以及由Writer生成的行分隔符。

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

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

        参数
        writer - 输出字符流 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表（如果有）的默认表中的属性。

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

        • 使用ISO 8859-1字符编码写入流。
        • 注释中不在Latin-1中的字符被写为\u xxxx，用于它们适当的unicode十六进制值xxxx 。
        • 字符小于\u0020和大于字符\u007E在属性键或值被写为\u XXXX为适当的十六进制值XXXX。

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

        参数
        out - 输出流。
        comments - 属性列表的描述。
        异常
        IOException - 如果将此属性列表写入指定的输出流，则抛出 IOException 。
        ClassCastException - 如果此 Properties对象包含任何不是 Strings键或值。
        NullPointerException - 如果 out为空。
        从以下版本开始：
        1.2

      • storeToXML

        public void storeToXML​(OutputStream os,
                       String comment)
                throws IOException
        发出表示此表中包含的所有属性的XML文档。

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

        参数
        os - 要在其上发出XML文档的输出流。
        comment - 属性列表的描述，如果不需要注释， null 。
        异常
        IOException - 如果写入指定的输出流，则会产生 IOException 。
        NullPointerException - 如果 os为空。
        ClassCastException - 如果此 Properties对象包含任何不是 Strings键或值。
        从以下版本开始：
        1.5
        另请参见：
        loadFromXML(InputStream)

      • 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 - charset
        异常
        IOException - 如果写入指定的输出流，则会产生 IOException 。
        NullPointerException - 如果 os或 charset是 null 。
        ClassCastException - 如果此 Properties对象包含任何不是 Strings键或值。
        从以下版本开始：
        10
        另请参见：
        loadFromXML(InputStream) ， Character Encoding in Entities

      • 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类型的String将被省略。

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

        结果
        此属性列表中的一组不可修改的键，其中键及其对应的值是字符串，包括默认属性列表中的键。
        从以下版本开始：
        1.6
        另请参见：
        defaults

      • list

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

      • list

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