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 方法。但不建議使用這兩個方法，因為它們允許調用者插入其鍵或值不是 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 字元 '#' 或 '!' 作為其首個非空(null)白字元；註釋行也被忽略並且不將其編碼為鍵-元素資訊。除了行結束符，此格式還將空格字元（' '，'\u0020'）、製表符（'\t'，'\u0009'）和換頁符（'\f'，'\u000C'）作為空白。

如果一個邏輯行分散在多個自然行中，則轉義行結束符序列的反斜槓、行結束符序列和後續行開始處的任何空白，對鍵或元素的值都沒有影響。後面對鍵和元素解析的討論（載入時）將假定移除行繼續符後，構成鍵和元素的所有字元都出現在單個自然行中。注意，僅檢查行結束符前面的字元，以便決定行結束符是否已轉義是不 夠的；對於要轉義的行結束符，必須有奇數個相鄰的反斜槓。由於是從左到右來處理輸入內容的，所以行結束符前（或其他位置）非零、偶數 2n 個相鄰的反斜槓在轉義處理後會被編碼成 n 個反斜槓。

鍵包含行中下列區間內的所有字元：從首個非空(null)白字元開始，直到（但不包括）首個非轉義的 '='、 ':' 或非行結束符的空白字元。所有這些鍵終止字元都可能包含在鍵中，方法是在其前面用反斜槓字元進行轉義，例如：

\:\=

將是兩字元的鍵 ":="。可以使用 \r 和 \n 轉義序列包括行結束符字元。跳過鍵後面的所有空白字元；如果鍵後的首個非空(null)白字元是 '=' 或 ':'，則忽略該字元並且跳過其後的所有空白字元。行中所有剩餘的字元都成為關聯元素字元串的一部分；如果沒有剩餘的字元，則該元素為空字元串 ""。一旦標識了組成鍵和元素的原始字元序列，則如上所述執行轉義處理。

作為一個範例，以下三行都指定了鍵 "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')、回車(Enter) ('\r') 或回車(Enter)後直接跟著換行，這些字元中的任意一個都由 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