java.util.prefs
類別 Preferences

java.lang.Object
  java.util.prefs.Preferences

直接已知子類別：

AbstractPreferences

public abstract class Preferences
extends Object

首選項資料的層次結構 collection 中的節點。此類別允許應用程序存儲和獲取使用者和系統首選項以及配置資料。此資料持久存儲在依賴於實作的內部存儲中。典型實作包括純文本檔案、特定於作業系統的註冊表、目錄伺服器和 SQL 資料庫。此類別的使用者無需關注內部存儲的細節。

有兩個獨立的首選項節點階層樹，一個用於使用者首選項，一個用於系統首選項。每個使用者都有一個單獨的使用者首選項階層樹，而在給定系統中，所有使用者都共享同一系統首選項階層樹。對“使用者”和“系統”的精確描述因實作而異。使用者首選項階層樹中存儲的典型資訊可能包括特定應用程序的字體選擇、顏色選擇和首選視窗的位置及大小。系統首選項階層樹中存儲的典型資訊可能包括應用程序的安裝配置資料。

使用類似的方式將首選項階層樹中的節點命名為層次結構檔案系統中的目錄。首選項階層樹的每個節點都具有一個節點名（不必是唯一的）、一個唯一的絕對路徑名 和一個相對於 每個祖先（包括它自己）的路徑名。

根節點的節點名為空字元串 ("")。每個其他節點的節點名可以在創建時任意指定。此名稱的唯一限制是，它不能是空字元串，也不能包含斜槓字元 ('/')。

根節點的絕對路徑名為 "/"。根節點的子節點的絕對路徑名是 "/" + <節點名>。所有其他節點的絕對路徑名是<父節點的絕對路徑名> + "/" + <節點名>。注意，所有絕對路徑名的第一個字元都是斜槓。

節點 n 相對於其祖先 a 的路徑名只是為了形成 n 的絕對路徑名，而必須添加到 a 的絕對路徑名的字元串，同時移除開頭的斜槓字元（如果存在）。注意：

• 任何相對路徑名的第一個字元都不能是斜槓。
• 每個節點相對於自身的路徑名都是空字元串。
• 每個節點相對於父節點的路徑名就是其節點名（根節點除外，因為它沒有父節點）。
• 每個節點相對於根的路徑名都是其移除開頭斜槓的絕對路徑名。

最後注意：

• 任何路徑名均不能包含多個連續的斜槓字元。
• 任何路徑名均不能以斜槓字元結尾，根的絕對路徑名除外。
• 所有符合這兩條規則的字元串都是有效的路徑名。

修改首選項資料的所有方法都允許進行非同步操作；它們可能立即返回，但是更改最終將傳播到持久內部存儲中，其延遲取決於實作。可以使用 flush 方法同步地將更新強制同步到內部存儲中。Java 虛擬機器的正常終止不會 導致掛起更新的丟失，即在終止時不 需要進行顯式 flush 調用來使掛起更新變得持久。

從 Preferences 物件讀取首選項的所有方法都要求調用者提供一個預設值。如果以前沒有設置任何值或者內部存儲不可用，則會返回預設值。此預設值的目的是，即使內部存儲不可用，應用程序也可以運行，只是功能稍微下降一點。在內部存儲不可用的情況下，多個方法（如 flush）均包含阻止應用程序操作的語義。普通應用程序不必調用這些方法中的任何一個，它們可能以拋出 BackingStoreException 而告終。

單個 JVM 中的多個執行緒可以同時調用此類別中的方法，無需進行外部同步，其結果等效於某些順序執行。如果在同一個內部存儲中存儲其首選項資料的多個 JVM 同時使用此類別，則資料存儲也不會遭到破壞，但首選項資料的一致性難以得到保證。

此類別包含導出/導入設施，允許將首選項“導出”到 XML 文檔，將表示首選項的 XML 文檔再“導入”回系統。可以使用此設施備份全部或部分首選項階層樹，並在以後從備份中還原。

XML 文檔具有以下 DOCTYPE 宣告：

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

注意，導入或導出首選項時不 存取系統 URI (http://java.sun.com/dtd/preferences.dtd)；該系統 URI 僅作為一個唯一標識 DTD 的字元串：

    <?xml version="1.0" encoding="UTF-8"?>

    <!-- DTD for a Preferences tree. -->

    <!-- The preferences element is at the root of an XML document
         representing a Preferences tree. -->
    <!ELEMENT preferences (root)>
  
    <!-- The preferences element contains an optional version attribute,
          which specifies version of DTD. -->
    <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >  

    <!-- The root element has a map representing the root's preferences
         (if any), and one node for each child of the root (if any). -->
    <!ELEMENT root (map, node*) >

    <!-- Additionally, the root contains a type attribute, which
         specifies whether it's the system or user root. -->
    <!ATTLIST root
              type (system|user) #REQUIRED >

    <!-- Each node has a map representing its preferences (if any),
         and one node for each child (if any). -->
    <!ELEMENT node (map, node*) >

    <!-- Additionally, each node has a name attribute -->
    <!ATTLIST node
              name CDATA #REQUIRED >

    <!-- A map represents the preferences stored at a node (if any). -->
    <!ELEMENT map (entry*) >

    <!-- An entry represents a single preference, which is simply
          a key-value pair. -->
    <!ELEMENT entry EMPTY >
    <!ATTLIST entry
              key   CDATA #REQUIRED
              value CDATA #REQUIRED >
 

每個 Preferences 實作都必須具有一個關聯的 PreferencesFactory 實作。每個 Java(TM) SE 實作都必須提供一些方式，來指定將哪個 PreferencesFactory 實作用於產生根首選項節點。這允許管理員使用替代實作替換預設首選項實作。

實作注意事項：在 Sun 的 JRE 中，PreferencesFactory 實作的位置如下：

1. 如果定義了系統屬性 java.util.prefs.PreferencesFactory，則該屬性名就會用作實作 PreferencesFactory 介面的類別的完全限定名。載入並實例化該類別；如果此進程失敗，則拋出未指定的錯誤。

2. 如果在對系統類別載入器可見的 jar 檔案中安裝了 PreferencesFactory 實作類別檔案，並且該 jar 檔案在資源目錄 META-INF/services 中包含名為 java.util.prefs.PreferencesFactory 的提供者配置檔案，則採用在該檔案中指定的第一個類別名稱。如果提供了一個以上這樣的 jar 檔案，則使用找到的第一個檔案。載入並實例化該類別；如果此進程失敗，則拋出未指定的錯誤。

3. 最後，如果既沒有提供上述系統屬性也沒有提供擴展 jar 檔案，則載入和實例化底層平臺的系統級預設 PreferencesFactory 實作。

從以下版本開始：

1.4

欄位摘要

static int	MAX_KEY_LENGTH 允許作為鍵的字元串最大長度（80 個字元）。
static int	MAX_NAME_LENGTH 節點名的最大長度（80 個字元）。
static int	MAX_VALUE_LENGTH 允許作為值的字元串最大長度（8192 個字元）。

建構子摘要

protected

Preferences() 單獨的建構子。

方法摘要

abstract String	absolutePath() 返回此首選項節點的絕對路徑名。
abstract void	addNodeChangeListener(NodeChangeListener ncl) 註冊指定偵聽器以接收此節點的節點更改事件。
abstract void	addPreferenceChangeListener(PreferenceChangeListener pcl) 註冊指定偵聽器以接收此首選項節點的首選項更改事件。
abstract String[]	childrenNames() 返回此首選項節點相對於此節點的子節點名稱。
abstract void	clear() 移除此首選項節點中的所有首選項（鍵-值關聯）。
abstract void	exportNode(OutputStream os) 在指定輸出串流上發出表示此節點（不是其子節點）中包含的所有首選項的 XML 文檔。
abstract void	exportSubtree(OutputStream os) 發出表示此節點及其所有子節點中包含的全部首選項的 XML 文檔。
abstract void	flush() 強制進行從此首選項節點及其子節點到持久存儲的內容更改。
abstract String	get(String key, String def) 返回與此首選項節點中指定鍵相關聯的值。
abstract boolean	getBoolean(String key, boolean def) 返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 boolean 值。
abstract byte[]	getByteArray(String key, byte[] def) 返回與此首選項節點中指定鍵相關聯的、由字元串表示的位元組陣列。
abstract double	getDouble(String key, double def) 返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 double 值。
abstract float	getFloat(String key, float def) 返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 float 值。
abstract int	getInt(String key, int def) 返回與此首選項節點中與指定鍵相關聯的、由字元串表示的 int 值。
abstract long	getLong(String key, long def) 返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 long 值。
static void	importPreferences(InputStream is) 導入指定輸入串流中由 XML 文檔表示的所有首選項。
abstract boolean	isUserNode() 如果此首選項節點位於使用者首選項階層樹中，則返回 true；如果其位於系統首選項階層樹中，則返回 false。
abstract String[]	keys() 返回在此首選項節點中具有關聯值的所有鍵。
abstract String	name() 返回此首選項節點相對於父節點的名稱。
abstract Preferences	node(String pathName) 將指定首選項節點返回到此節點所在的同一階層樹中，如果此節點及其祖先已經不存在，則創建它們。
abstract boolean	nodeExists(String pathName) 如果此節點所在的階層樹中存在指定首選項節點，則返回 true。
abstract Preferences	parent() 返回此首選項節點的父節點；如果此為根，則返回 null。
abstract void	put(String key, String value) 將指定值與此首選項節點中的指定鍵相關聯。
abstract void	putBoolean(String key, boolean value) 將表示指定 boolean 值的字元串與此首選項節點中的指定鍵相關聯。
abstract void	putByteArray(String key, byte[] value) 將表示指定位元組陣列的字元串與此首選項節點中的指定鍵相關聯。
abstract void	putDouble(String key, double value) 將表示指定 double 值的字元串與此首選項節點中的指定鍵相關聯。
abstract void	putFloat(String key, float value) 將表示指定 float 值的字元串與此首選項節點中的指定鍵相關聯。
abstract void	putInt(String key, int value) 將表示指定 int 值的字元串與此首選項節點中的指定鍵相關聯。
abstract void	putLong(String key, long value) 將表示指定 long 值的字元串與此首選項節點中的指定鍵相關聯。
abstract void	remove(String key) 移除與此首選項節點中與指定鍵相關聯的值（如果有）。
abstract void	removeNode() 移除此首選項節點及其所有子節點，移除的節點中所包含的全部首選項都將失效。
abstract void	removeNodeChangeListener(NodeChangeListener ncl) 移除指定 NodeChangeListener，使其不再接收更改事件。
abstract void	removePreferenceChangeListener(PreferenceChangeListener pcl) 移除指定首選項更改偵聽器，使其不再接收首選項更改事件。
abstract void	sync() 確保在調用 sync 之前從此首選項節點及其子節點進行的後續讀取能反映出提交到持久存儲（從任何 VM）的所有更改。
static Preferences	systemNodeForPackage(Class<?> c) 從系統首選項階層樹（根據約定，它與指定類別的套件相關聯）返回首選項節點。
static Preferences	systemRoot() 返回系統的根首選項節點。
abstract String	toString() 返回此首選項節點的字元串表示形式，與通過表達式：(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 計算的結果一樣。
static Preferences	userNodeForPackage(Class<?> c) 從調用使用者首選項階層樹（根據約定，它與指定類別的套件相關聯）返回首選項節點。
static Preferences	userRoot() 返回調用使用者的根首選項節點。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

欄位詳細資訊

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH

允許作為鍵的字元串最大長度（80 個字元）。

另請參見：

常數欄位值

MAX_VALUE_LENGTH

public static final int MAX_VALUE_LENGTH

允許作為值的字元串最大長度（8192 個字元）。

另請參見：

常數欄位值

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH

節點名的最大長度（80 個字元）。

另請參見：

常數欄位值

建構子詳細資訊

Preferences

protected Preferences()

單獨的建構子。（由子類別建構子調用，通常是隱式的）。

方法詳細資訊

userNodeForPackage

public static Preferences userNodeForPackage(Class<?> c)

從調用使用者首選項階層樹（根據約定，它與指定類別的套件相關聯）返回首選項節點。約定如下：節點的絕對路徑名就是完全限定的套件名，開頭使用一個斜槓 ('/')，並將其中的每一個句點 ('.') 都替換為斜槓。例如，與類別 com.acme.widget.Foo 關聯的節點絕對路徑名是 /com/acme/widget。

此約定不適用於未命名的套件，未命名套件的關聯首選項節點是 <unnamed>。此節點只是為了方便程序的早期開發（而非長期使用）而存在的，它不屬於任何包，只用於“一次性”程序。在此節點中不應該存儲有價值的資料，因為使用它的所有程序都可以共享它。

希望存取與其包有關的首選項類別 Foo 可以獲得以下首選項節點：

    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
 

此語句消除了使用字元串描述首選項節點的需求，從而降低了發生運行時故障的可能性。（如果類別名稱拼寫錯誤，則通常會導致編譯時錯誤。）

調用此方法將導致返回節點及其祖先的創建（如果它們不存在）。如果在此調用之前返回的節點不存在，那麼在對返回節點（或者其某個祖先或子節點）調用 flush 方法之前，不能保證由此調用所創建的節點及其所有祖先是永久性的。

參數：

c - 使用者首選項節點需要其套件的類別。

返回：

與 c 成員所屬包相關聯的使用者首選項節點。

拋出：

NullPointerException - 如果 c 為 null。

SecurityException - 如果安全管理器存在並且拒絕 RuntimePermission("preferences")。

另請參見：

RuntimePermission

systemNodeForPackage

public static Preferences systemNodeForPackage(Class<?> c)

從系統首選項階層樹（根據約定，它與指定類別的套件相關聯）返回首選項節點。約定如下：節點的絕對路徑名就是完全限定的套件名，開頭使用一個斜槓 ('/')，並將其中的每一個句點 ('.') 都替換為斜槓。例如，與類別 com.acme.widget.Foo 關聯的節點絕對路徑名是 /com/acme/widget。

此約定不適用於未命名的套件，未命名套件的關聯首選項節點是 <unnamed>。此節點只是為了方便程序的早期開發（而非長期使用）而存在的，它不屬於任何包，只用於“一次性”程序。在此節點中不應該存儲有價值的資料，因為使用它的所有程序都可以共享它。

希望存取與其包有關的首選項類別 Foo 可以獲得以下首選項節點：

  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
 

此語句消除了使用字元串描述首選項節點的需求，從而降低了發生運行時故障的可能性。（如果類別名稱拼寫錯誤，則通常會導致編譯時錯誤。）

調用此方法將導致返回節點及其祖先的創建（如果它們不存在）。如果在此調用之前返回的節點不存在，那麼在對返回節點（或者其某個祖先或子節點）調用 flush 方法之前，不能保證由此調用所創建的節點及其所有祖先是永久性的。

參數：

c - 系統首選項節點需要其套件的類別。

返回：

與 c 成員所屬包相關聯的使用者首選項節點。

拋出：

NullPointerException - 如果 c 為 null。

SecurityException - 如果安全管理器存在並且拒絕 RuntimePermission("preferences")。

另請參見：

RuntimePermission

userRoot

public static Preferences userRoot()

返回調用使用者的根首選項節點。

返回：

調用使用者的根首選項節點。

拋出：

SecurityException - 如果安全管理器存在並且拒絕 RuntimePermission("preferences")。

另請參見：

RuntimePermission

systemRoot

public static Preferences systemRoot()

返回系統的根首選項節點。

返回：

系統的根首選項節點。

拋出：

SecurityException - 如果安全管理器存在並且拒絕 RuntimePermission("preferences")。

另請參見：

RuntimePermission

put

public abstract void put(String key,
                         String value)

將指定值與此首選項節點中的指定鍵相關聯。

參數：

key - 指定的 value 將要關聯的鍵。

value - 指定的 key 將要關聯的值。

拋出：

NullPointerException - 如果 key 或 value 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH 或者 value.length 超過 MAX_VALUE_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

get

public abstract String get(String key,
                           String def)

返回與此首選項節點中指定鍵相關聯的值。如果不存在與該鍵相關聯的值或者內部存儲不可存取，則返回指定的預設值。

有些實作可能將預設值存儲在其內部存儲中。如果不存在與指定鍵相關聯的值，而只有存儲的預設值，則系統優先返回存儲的預設值（而不是指定的預設值）。

參數：

key - 要返回其相關值的鍵。

def - 此首選項節點不具有與 key 相關聯的值時所要返回的值。

返回：

與 key 相關聯的值；如果沒有與 key 相關聯的值或者內部存儲不可用，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。（值 null 用於 def 是 允許的。）

remove

public abstract void remove(String key)

移除與此首選項節點中與指定鍵相關聯的值（如果有）。

如果此實作支持存儲的預設值，並且指定的首選項存在這樣的預設值，則此調用將“公開”存儲的預設值，這表示對 get 的後續調用將返回它。

參數：

key - 從首選項節點中移除其映射關係的鍵。

拋出：

NullPointerException - 如果 key 為 null。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

clear

public abstract void clear()
                    throws BackingStoreException

移除此首選項節點中的所有首選項（鍵-值關聯）。此調用對此節點的所有子節點均沒有影響。

如果此實作支持存儲的預設值，並且首選項層次結構中的這一節點包含這樣的預設值，則此調用將“公開”存儲的預設值，這表示對 get 的後續調用將返回它。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

removeNode()

putInt

public abstract void putInt(String key,
                            int value)

將表示指定 int 值的字元串與此首選項節點中的指定鍵相關聯。關聯字元串是將 int 值傳遞給 Integer.toString(int) 時將返回的字元串。此方法與 getInt(java.lang.String, int) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getInt(String,int)

getInt

public abstract int getInt(String key,
                           int def)

返回與此首選項節點中與指定鍵相關聯的、由字元串表示的 int 值。該字元串由 Integer.parseInt(String) 轉換為整數。如果不存在與該鍵相關聯的值，內部存儲不可用，或者傳遞關聯值時 Integer.parseInt(String) 拋出 NumberFormatException，則返回指定的預設值。此方法與 putInt(java.lang.String, int) 一起使用。

如果該實作支持存儲的預設值，並且這樣的預設值存在且可存取，而且可以使用 Integer.parseInt 將其轉換為 int，則優先返回此 int（而不是指定預設值）。

參數：

key - 要作為 int 返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為 int 或者內部存儲不可存取時要返回的值。

返回：

與此首選項節點的 key 相關聯的字元串所表示的 int 值；如果該關聯值不存在或無法被解釋為 int，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。

另請參見：

putInt(String,int), get(String,String)

putLong

public abstract void putLong(String key,
                             long value)

將表示指定 long 值的字元串與此首選項節點中的指定鍵相關聯。關聯字元串是將 long 值傳遞給 Long.toString(long) 時將返回的字元串。此方法與 getLong(java.lang.String, long) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getLong(String,long)

getLong

public abstract long getLong(String key,
                             long def)

返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 long 值。該字元串由 Long.parseLong(String) 轉換為 long。如果不存在與該鍵相關聯的值，內部存儲不可用，或者傳遞關聯值時 Long.parseLong(String) 拋出 NumberFormatException，則返回指定的預設值。此方法與 putLong(java.lang.String, long) 一起使用。

如果該實作支持存儲的預設值，這樣的預設值存在且可存取，並且可以使用 Long.parseLong 轉換為 long，則優先返回此 long（而不是指定預設值）。

參數：

key - 要作為 long 返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為 long 或者內部存儲不可存取時要返回的值。

返回：

返回與此首選項節點的 key 相關聯的字元串所表示的 long 值；如果關聯值不存在或者無法將其解釋為 long，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。

另請參見：

putLong(String,long), get(String,String)

putBoolean

public abstract void putBoolean(String key,
                                boolean value)

將表示指定 boolean 值的字元串與此首選項節點中的指定鍵相關聯。如果該值為 true，則關聯字元串為 "true"；如果其為 false，則關聯字元串為 "false"。此方法與 getBoolean(java.lang.String, boolean) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getBoolean(String,boolean), get(String,String)

getBoolean

public abstract boolean getBoolean(String key,
                                   boolean def)

返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 boolean 值。有效字元串是 "true"（表示真）和 "false"（表示假）。不區分大小寫，例如，"TRUE" 和 "False" 也是有效的。此方法與 putBoolean(java.lang.String, boolean) 一起使用。

如果不存在與該鍵相關聯的值或者內部存儲不可存取或者關聯值是 "true" 或 "false"（不區分大小寫）之外的其他值，則返回指定預設值。

如果該實作支持存儲的預設值，這樣的預設值存在且可存取，則優先使用存儲的預設值（而不是指定預設值）；但如果存儲的預設值是 "true" 或 "false"（不區分大小寫）之外的其他值，在這種情況下，則使用指定預設值。

參數：

key - 要作為 boolean 返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為 boolean 或者內部存儲不可存取時要返回的值。

返回：

與此首選項節點的 key 相關聯的字元串所表示的 boolean 值；如果該關聯值不存在或無法被解釋為 boolean，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。

另請參見：

get(String,String), putBoolean(String,boolean)

putFloat

public abstract void putFloat(String key,
                              float value)

將表示指定 float 值的字元串與此首選項節點中的指定鍵相關聯。關聯字元串是將 float 值傳遞給 Float.toString(float) 時將返回的字元串。此方法與 getFloat(java.lang.String, float) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getFloat(String,float)

getFloat

public abstract float getFloat(String key,
                               float def)

返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 float 值。該字元串由 Float.parseFloat(String) 轉換為整數。如果不存在與該鍵相關聯的值，內部存儲不可用，或者傳遞關聯值時 Float.parseFloat(String) 拋出 NumberFormatException，則返回指定的預設值。此方法與 putFloat(java.lang.String, float) 一起使用。

如果該實作支持存儲的預設值，這樣的預設值存在且可存取，並且可以使用 Float.parseFloat 轉換為 float，則優先返回此 float（而不是指定預設值）。

參數：

key - 要作為 float 返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為 float 或者內部存儲不可存取時要返回的值。

返回：

與此首選項節點的 key 相關聯的字元串所表示的 float 值；如果該關聯值不存在或無法被解釋為 float，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。

另請參見：

putFloat(String,float), get(String,String)

putDouble

public abstract void putDouble(String key,
                               double value)

將表示指定 double 值的字元串與此首選項節點中的指定鍵相關聯。關聯字元串是將 double 值傳遞給 Double.toString(double) 時將返回的字元串。此方法與 getDouble(java.lang.String, double) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getDouble(String,double)

getDouble

public abstract double getDouble(String key,
                                 double def)

返回與此首選項節點中指定的鍵相關聯的、由字元串表示的 double 值。該字元串由 Double.parseDouble(String) 轉換為整數。如果不存在與該鍵相關聯的值，內部存儲不可用，或者傳遞關聯值時 Double.parseDouble(String) 拋出 NumberFormatException，則返回指定的預設值。此方法與 putDouble(java.lang.String, double) 一起使用。

如果該實作支持存儲的預設值，這樣的預設值存在且可存取，並且可以使用 Double.parseDouble 轉換為 double，則優先返回此 double（而不是指定預設值）。

參數：

key - 要作為 double 返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為 double 或者內部存儲不可存取時要返回的值。

返回：

與此首選項節點的 key 相關聯的字元串所表示的 double 值；如果該關聯值不存在或無法被解釋為 double，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。

另請參見：

putDouble(String,double), get(String,String)

putByteArray

public abstract void putByteArray(String key,
                                  byte[] value)

將表示指定位元組陣列的字元串與此首選項節點中的指定鍵相關聯。正如 RFC 2045，第 6.8 節中定義的那樣，該關聯字元串是 Base64 編碼的位元組陣列，其中有一處小的改動：該字元串僅由 Base64 Alphabet 中的字元構成；它不包含任何新行符。注意，該位元組陣列的最大長度限制是 MAX_VALUE_LENGTH 的四分之三，因此，Base64 編碼的 String 的長度不能超過 MAX_VALUE_LENGTH。此方法與 getByteArray(java.lang.String, byte[]) 一起使用。

參數：

key - 要與字元串形式的 value 相關聯的鍵。

value - 要與 key 相關聯的字元串形式的值。

拋出：

NullPointerException - 如果 key 或 value 為 null。

IllegalArgumentException - 如果 key.length() 超過 MAX_KEY_LENGTH 或者 value.length 超過 MAX_VALUE_LENGTH*3/4。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

getByteArray(String,byte[]), get(String,String)

getByteArray

public abstract byte[] getByteArray(String key,
                                    byte[] def)

返回與此首選項節點中指定鍵相關聯的、由字元串表示的位元組陣列。正如 RFC 2045，第 6.8 節中定義的那樣，有效的字元串是 Base64 編碼的二進制資料，其中有一處小的改動：該字元串必須僅包含 Base64 Alphabet 中的字元；不允許使用任何新行符或額外字元。此方法與 putByteArray(java.lang.String, byte[]) 一起使用。

如果沒有與該鍵相關聯的值或者內部存儲不可存取或者關聯值不是有效的 Base64 編碼位元組陣列（根據上面的定義），則返回指定預設值。

如果該實作支持存儲的預設值，這樣的預設值存在且可存取，則優先使用存儲的預設值（而不是指定預設值）；但如果存儲的預設值不是有效的 Base64 編碼的位元組陣列（根據上面的定義），在這種情況下，則使用指定預設值。

參數：

key - 要作為位元組陣列返回其關聯值的鍵。

def - 此首選項節點不具有與 key 相關聯的值或者無法將該關聯值解釋為位元組陣列或者內部存儲不可存取時要返回的值。

返回：

與此首選項節點的 key 相關聯的字元串所表示的位元組陣列值；如果該關聯值不存在或無法被解釋為位元組陣列，則返回 def。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

NullPointerException - 如果 key 為 null。（值 null 用於 def 是 允許的。）

另請參見：

get(String,String), putByteArray(String,byte[])

keys

public abstract String[] keys()
                       throws BackingStoreException

返回在此首選項節點中具有關聯值的所有鍵。（如果此節點不具有任何首選項，則返回陣列的大小將為 0。）

如果該實作支持存儲的預設值，此節點中存在這樣的預設值並且沒有被顯式首選項覆寫，則在陣列中除了返回所有顯式首選項外，還返回預設值。

返回：

在此首選項節點中具有關聯值的鍵陣列。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

childrenNames

public abstract String[] childrenNames()
                                throws BackingStoreException

返回此首選項節點相對於此節點的子節點名稱。（如果此節點不具有任何子節點，則返回陣列的大小將為 0。）

返回：

此首選項節點的子節點名稱。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

parent

public abstract Preferences parent()

返回此首選項節點的父節點；如果此為根，則返回 null。

返回：

首選項節點的父節點。

拋出：

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

node

public abstract Preferences node(String pathName)

將指定首選項節點返回到此節點所在的同一階層樹中，如果此節點及其祖先已經不存在，則創建它們。接受相對或絕對路徑名。相對路徑名（不以斜槓字元 ('/') 開頭）是相對於此首選項節點解釋的。

如果在此調用之前返回的節點不存在，那麼在對返回節點（或者其某個祖先或子節點）調用 flush 方法之前，不能保證由此調用所創建的節點及其所有祖先是永久性的。

參數：

pathName - 要返回的首選項節點的路徑名。

返回：

指定的首選項節點。

拋出：

IllegalArgumentException - 如果路徑名無效（即它包含多個連續的斜槓字元，或者以斜槓字元結束並且大於一個 long 字元）。

NullPointerException - 如果路徑名為 null。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

flush()

nodeExists

public abstract boolean nodeExists(String pathName)
                            throws BackingStoreException

如果此節點所在的階層樹中存在指定首選項節點，則返回 true。相對路徑名（不以斜槓字元 ('/') 開頭）是相對於此首選項節點解釋的。

如果已經使用 removeNode() 方法移除了此節點（及其祖先），則調用此方法也是 合法的，只是需要使用路徑名 ""；該調用返回 false。因此，可以使用語句 p.nodeExists("") 測試 p 是否已被移除。

參數：

pathName - 要檢查其是否存在的節點路徑名。

返回：

如果指定的節點存在，則返回 true。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalArgumentException - 如果路徑名無效（即它包含多個連續的斜槓字元，或者以斜槓字元結束並且大於一個 long 字元）。

NullPointerException - 如果路徑名為 null。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先），並且 pathName 不是空字元串 ("")。

removeNode

public abstract void removeNode()
                         throws BackingStoreException

移除此首選項節點及其所有子節點，移除的節點中所包含的全部首選項都將失效。節點被移除後，針對相應 Preferences 實例嘗試使用 name()、absolutePath()、isUserNode()、flush() 或 nodeExists("") 之外的任何方法都將失敗並拋出 IllegalStateException。（節點被移除後，在該節點上仍然可以調用在 Object 上定義的方法，並且不拋出 IllegalStateException。）

在此節點（或其祖先）上調用 flush 方法之前移除操作不保證是持久的。

如果此實作支持存儲的預設值，則移除節點將公開此節點的或此節點下的所有存儲的預設值。因此，對此節點的路徑名後續調用 nodeExists 將返回 true，而對此路徑名後續調用 node 則返回表示首選項和/或子首選項的非空(null) collection 的（不同）Preferences 實例。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

UnsupportedOperationException - 如果在根節點上調用此方法。

另請參見：

flush()

name

public abstract String name()

返回此首選項節點相對於父節點的名稱。

返回：

此首選項節點的名稱（相對於其父節點）。

absolutePath

public abstract String absolutePath()

返回此首選項節點的絕對路徑名。

返回：

此首選項節點的絕對路徑名。

isUserNode

public abstract boolean isUserNode()

如果此首選項節點位於使用者首選項階層樹中，則返回 true；如果其位於系統首選項階層樹中，則返回 false。

返回：

如果此首選項節點位於使用者首選項階層樹中，則返回 true；如果其位於系統首選項階層樹中，則返回 false。

toString

public abstract String toString()

返回此首選項節點的字元串表示形式，與通過表達式：(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() 計算的結果一樣。

覆寫：

類別 Object 中的 toString

返回：

該物件的字元串表示形式。

flush

public abstract void flush()
                    throws BackingStoreException

強制進行從此首選項節點及其子節點到持久存儲的內容更改。此方法成功返回後，即可安全地假定調用該方法前，在以此節點為根的子階層樹中所作的全部更改都是永久性的。

實作可以在任何時間隨意將更改刷新到持久存儲中。它們無需等待此方法的調用。

對新創建的節點進行刷新後，它就變得持久了，同時其所有尚未變得持久的祖先（和子節點）也將變得持久。但是注意，不 保證其祖先中的所有首選項值的更改能變得持久。

如果在已經使用 removeNode() 方法移除的節點上調用此方法，則會在此節點（而非其他節點）上調用 flushSpi()。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

另請參見：

sync()

sync

public abstract void sync()
                   throws BackingStoreException

確保在調用 sync 之前從此首選項節點及其子節點進行的後續讀取能反映出提交到持久存儲（從任何 VM）的所有更改。另外，強制進行從此首選項節點及其子節點到持久存儲的內容更改，與對此節點調用 flush 方法一樣。

拋出：

BackingStoreException - 如果由於內部存儲的故障或未能通信而無法完成此操作。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

flush()

addPreferenceChangeListener

public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)

註冊指定偵聽器以接收此首選項節點的首選項更改事件。將首選項添加到此節點、從此節點移除首選項或者更改與首選項關聯的值時都將產生首選項更改事件。（removeNode() 方法不 產生首選項更改事件，該方法只產生節點更改事件。首選項更改事件是 由 clear 方法產生的。）

儘管有些實作可以為在 JVM 外進行的更改產生事件，但只有在已註冊偵聽器所在的 JVM 中所作的更改才能得到保證。事件可能是更改變得持久之前產生的。在此節點的子節點中修改首選項時不產生事件；需要此類別事件的調用者必須在每個子節點中註冊。

參數：

pcl - 要添加的首選項更改偵聽器。

拋出：

NullPointerException - 如果 pcl 為 null。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

removePreferenceChangeListener(PreferenceChangeListener), addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)

移除指定首選項更改偵聽器，使其不再接收首選項更改事件。

參數：

pcl - 要移除的首選項更改偵聽器。

拋出：

IllegalArgumentException - 如果 pcl 不是此節點上的已註冊首選項更改偵聽器。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

addPreferenceChangeListener(PreferenceChangeListener)

addNodeChangeListener

public abstract void addNodeChangeListener(NodeChangeListener ncl)

註冊指定偵聽器以接收此節點的節點更改事件。在此節點中添加或刪除子節點時，將產生節點更改事件。（單個 removeNode() 調用即可產生多個節點更改事件，每個都對應於以已移除節點為根的子階層樹中的一個節點。）

儘管有些實作可以為在 JVM 外進行的更改產生事件，但只有在註冊偵聽器所在的 JVM 中所作的更改才能得到保證。事件可能是更改變得持久之前產生的。添加或移除此節點的間接子節點時不產生事件；需要此類別事件的調用者必須在每個子節點中註冊。

節點的創建難以得到保證。因為節點是基於存取隱式創建的，實作無法確定存取前內部存儲中是否存在子節點（例如，內部存儲不可存取或已快取記憶體資訊過期）。在這些情形下，實作既不要求產生節點更改事件也不禁止這樣做。

參數：

ncl - 要添加的 NodeChangeListener。

拋出：

NullPointerException - 如果 ncl 為 null。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

removeNodeChangeListener(NodeChangeListener), addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)

移除指定 NodeChangeListener，使其不再接收更改事件。

參數：

ncl - 要移除的 NodeChangeListener。

拋出：

IllegalArgumentException - 如果 ncl 不是此節點上的已註冊 NodeChangeListener。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

addNodeChangeListener(NodeChangeListener)

exportNode

public abstract void exportNode(OutputStream os)
                         throws IOException,
                                BackingStoreException

在指定輸出串流上發出表示此節點（不是其子節點）中包含的所有首選項的 XML 文檔。此 XML 文檔實際上是節點的脫機備份。

該 XML 文檔具有以下 DOCTYPE 宣告：

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

使用 UTF-8 字元編碼。

此方法對一般規則而言是個例外，在此類別中共時執行多個方法將產生等效於某些順序執行的結果。如果由於調用此方法而同時修改了此節點的多個首選項，則導出的首選項由該節點所包含的首選項的“模糊快照”組成；有些共時修改可能在導出資料中得到了反映，而有些則不然。

參數：

os - 根據其內容發出 XML 文檔的輸出串流。

拋出：

IOException - 如果寫入指定的輸出串流導致 IOException。

BackingStoreException - 如果無法從內部存儲讀取首選項資料。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

importPreferences(InputStream)

exportSubtree

public abstract void exportSubtree(OutputStream os)
                            throws IOException,
                                   BackingStoreException

發出表示此節點及其所有子節點中包含的全部首選項的 XML 文檔。此 XML 文檔實際上是以該節點為根的子階層樹的脫機備份。

該 XML 文檔具有以下 DOCTYPE 宣告：

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

使用 UTF-8 字元編碼。

此方法對一般規則而言是個例外，在此類別中共時執行多個方法將產生等效於某些順序執行的結果。如果通過調用此方法同時修改了以此節點為根的子階層樹中的首選項或節點，則導出的首選項由該子階層樹的“模糊快照”組成；有些共時修改可能在導出資料中得到了反映，而有些則不然。

參數：

os - 根據其內容發出 XML 文檔的輸出串流。

拋出：

IOException - 如果寫入指定的輸出串流導致 IOException。

BackingStoreException - 如果無法從內部存儲讀取首選項資料。

IllegalStateException - 如果已經使用 removeNode() 方法移除了此節點（或其祖先）。

另請參見：

importPreferences(InputStream), exportNode(OutputStream)

importPreferences

public static void importPreferences(InputStream is)
                              throws IOException,
                                     InvalidPreferencesFormatException

導入指定輸入串流中由 XML 文檔表示的所有首選項。該文檔可能表示使用者首選項或系統首選項。如果它表示使用者首選項，則這些首選項將被導入到調用使用者的首選項階層樹（即使它們原先位於另外的使用者首選項階層樹）。如果該文檔描述的某些首選項位於不存在的首選項節點，則創建這些節點。

該 XML 文檔必須具有以下 DOCTYPE 宣告：

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

（此方法與 exportNode(OutputStream) 和 exportSubtree(OutputStream) 一起使用。

此方法對一般規則而言是個例外，在此類別中共時執行多個方法將產生等效於某些順序執行的結果。該方法好像要在此類別中其他公共方法之上實作，尤其是 node(String) 和 put(String, String)。

參數：

is - 從中讀取 XML 文檔的輸入串流。

拋出：

IOException - 如果讀取指定的輸入串流導致 IOException。

InvalidPreferencesFormatException - 輸入串流中的資料沒有按要求的文檔型別組成有效的 XML 文檔。

SecurityException - 如果安全管理器存在並且拒絕 RuntimePermission("preferences")。

另請參見：

RuntimePermission