java.util.prefs
類別 AbstractPreferences

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

public abstract class AbstractPreferences
extends Preferences

此類別提供了 Preferences 類別的骨幹實作，從而大大簡化了實作此類別的任務。

此類別僅供 Preferences 實作者使用。Preferences 設施的普通使用者無需參考此文檔。Preferences 文檔已經足夠了。

實作者必須覆寫九個抽象服務提供者介面 (SPI) 方法：getSpi(String)、putSpi(String,String)、removeSpi(String)、childSpi(String)、removeNodeSpi()、keysSpi()、childrenNamesSpi()、syncSpi() 和 flushSpi()。所有的具體方法都精確指定它們如何在這些 SPI 方法上實作。如果出於某種考慮（如性能）對預設實作不滿意，則實作者可能決定覆寫一個或多個具體方法。

SPI 方法按異常行為可分為三個組。getSpi 方法應該永遠不拋出異常，但是對性能絲毫不會產生影響，因為 get(String,String) 會攔截此方法所拋出的任何異常，並對調用者返回指定的預設值。removeNodeSpi、keysSpi、childrenNamesSpi、syncSpi 和 flushSpi 方法被指定拋出 BackingStoreException；如果實作無法執行操作，則需要拋出此經過檢查的異常。該異常向外傳播，導致相應的 API 方法失敗。

其餘的 SPI 方法 putSpi(String,String)、removeSpi(String) 和 childSpi(String) 具有更加複雜的異常行為。未指定它們拋出 BackingStoreException，因為即使內部存儲不可用，它們通常也遵守其協定。之所以這樣是因為它們不返回任何資訊，並且在進行對 Preferences.flush() 或 Preferences.sync() 的後續調用之前，不要求其結果是持久的。一般而言，這些 SPI 方法不應拋出異常。在某些實作中，可能存在這些調用甚至無法對後續處理的請求操作進行排隊的情形。即使在這些情形下，最好的做法也是忽略該調用並返回，而不是拋出異常。但是，在這些情形下，所有 flush() 和 sync 的後續調用應該返回 false，因為返回 true 意味著以前的所有操作都已成功地成為持久性操作。

有一種情況下 putSpi、removeSpi 和 childSpi 應該 拋出異常：如果調用者在底層作業系統上不具備執行請求操作的足夠權限。例如，如果非特權使用者嘗試修改系統首選項，則在大多數系統上都會發生這種情況。（這要求特權隨實作而變化。在有些實作中，需要修改檔案系統中某些目錄內容的特權；而在另外一些實作中，則需要修改註冊表中某些鍵的內容。）在上述任何情形下，通常讓程序繼續執行並不合乎需要，就好像這些操作在以後會成為持久操作一樣。雖然在這些情形下不要求實作拋出異常，但還是鼓勵這樣做。SecurityException 就是合適的選擇。

大多數 SPI 方法都要求實作在首選項節點上讀取或寫入資訊。實作者需要注意一種情況，即另一個 VM 當前可能已經從內部存儲刪除了此節點。如果該節點已經刪除了，則實作有責任重新創建它。

實作注意事項：在 Sun 的預設 Preferences 實作中，使用者的身份是從底層作業系統繼承的，在虛擬機器的生命週期中不能更改。在伺服器端的 Preferences 實作中，使用者身份可以隨請求而更改，並通過使用靜態 ThreadLocal 實例隱式傳遞給 Preferences 方法。大力 提倡這種實作的設計者在存取首選項時確定使用者（例如，使用 get(String,String) 或 put(String,String) 方法），而不是將使用者與每個 Preferences 實例永久關聯。後一種行為與通常的 Preferences 用法有衝突，將帶來很大的混亂。

從以下版本開始：

1.4

另請參見：

Preferences

欄位摘要

protected Object	lock 使用其監視器鎖定此節點的物件。
protected boolean	newNode 如果在創建此物件前內部存儲中不存在此節點，則該欄位為 true。

從類別 java.util.prefs.Preferences 繼承的欄位

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

建構子摘要

protected

AbstractPreferences(AbstractPreferences parent, String name) 用指定的父節點和與其父節點相關的指定名稱創建首選項節點。

方法摘要

String	absolutePath() 根據 Preferences.absolutePath() 中的規範實作 absolutePath 方法。
void	addNodeChangeListener(NodeChangeListener ncl) 註冊指定偵聽器以接收此節點的節點更改事件。
void	addPreferenceChangeListener(PreferenceChangeListener pcl) 註冊指定偵聽器以接收此首選項節點的首選項更改事件。
protected AbstractPreferences[]	cachedChildren() 返回此節點的所有已知未移除子節點。
String[]	childrenNames() 根據 Preferences.childrenNames() 中的規範實作 children 方法。
protected abstract String[]	childrenNamesSpi() 返回此首選項節點的子節點名稱。
protected abstract AbstractPreferences	childSpi(String name) 返回此首選項節點的指定子節點；如果該子節點尚未存在，則創建它。
void	clear() 根據 Preferences.clear() 中的規範實作 clear 方法。
void	exportNode(OutputStream os) 根據 Preferences.exportNode(OutputStream) 中的規範實作 exportNode 方法。
void	exportSubtree(OutputStream os) 根據 Preferences.exportSubtree(OutputStream) 中的規範實作 exportSubtree 方法。
void	flush() 根據 Preferences.flush() 中的規範實作 flush 方法。
protected abstract void	flushSpi() 此方法是在此節點被鎖定的情況下調用的。
String	get(String key, String def) 根據 Preferences.get(String,String) 中的規範實作 get 方法。
boolean	getBoolean(String key, boolean def) 根據 Preferences.getBoolean(String,boolean) 中的規範實作 getBoolean 方法。
byte[]	getByteArray(String key, byte[] def) 根據 Preferences.getByteArray(String,byte[]) 中的規範實作 getByteArray 方法。
protected AbstractPreferences	getChild(String nodeName) 如果指定的子節點存在，則返回該子節點；如果它不存在，則返回 null。
double	getDouble(String key, double def) 根據 Preferences.getDouble(String,double) 中的規範實作 getDouble 方法。
float	getFloat(String key, float def) 根據 Preferences.getFloat(String,float) 中的規範實作 getFloat 方法。
int	getInt(String key, int def) 根據 Preferences.getInt(String,int) 中的規範實作 getInt 方法。
long	getLong(String key, long def) 根據 Preferences.getLong(String,long) 中的規範實作 getLong 方法。
protected abstract String	getSpi(String key) 返回與此首選項節點上的指定鍵相關聯的值；如果不存在此鍵的關聯值或此時無法確定該關聯值，則返回 null。
protected boolean	isRemoved() 當且僅當已經使用 removeNode() 方法移除此節點（或其祖先）時才返回 true。
boolean	isUserNode() 根據 Preferences.isUserNode() 中的規範實作 isUserNode 方法。
String[]	keys() 根據 Preferences.keys() 中的規範實作 keys 方法。
protected abstract String[]	keysSpi() 返回在此首選項節點中具有關聯值的所有鍵。
String	name() 根據 Preferences.name() 中的規範實作 name 方法。
Preferences	node(String path) 根據 Preferences.node(String) 中的規範實作 node 方法。
boolean	nodeExists(String path) 根據 Preferences.nodeExists(String) 中的規範實作 nodeExists 方法。
Preferences	parent() 根據 Preferences.parent() 中的規範實作 parent 方法。
void	put(String key, String value) 根據 Preferences.put(String,String) 中的規範實作 put 方法。
void	putBoolean(String key, boolean value) 根據 Preferences.putBoolean(String,boolean) 中的規範實作 putBoolean 方法。
void	putByteArray(String key, byte[] value) 根據 Preferences.putByteArray(String,byte[]) 中的規範實作 putByteArray 方法。
void	putDouble(String key, double value) 根據 Preferences.putDouble(String,double) 中的規範實作 putDouble 方法。
void	putFloat(String key, float value) 根據 Preferences.putFloat(String,float) 中的規範實作 putFloat 方法。
void	putInt(String key, int value) 根據 Preferences.putInt(String,int) 中的規範實作 putInt 方法。
void	putLong(String key, long value) 根據 Preferences.putLong(String,long) 中的規範實作 putLong 方法。
protected abstract void	putSpi(String key, String value) 將給定的鍵-值關聯置於此首選項節點中。
void	remove(String key) 根據 Preferences.remove(String) 中的規範實作 remove(String) 方法。
void	removeNode() 根據 Preferences.removeNode() 中的規範實作 removeNode() 方法。
void	removeNodeChangeListener(NodeChangeListener ncl) 移除指定 NodeChangeListener，使其不再接收更改事件。
protected abstract void	removeNodeSpi() 移除此首選項節點，該首選項節點及其所包含的所有首選項都將失效。
void	removePreferenceChangeListener(PreferenceChangeListener pcl) 移除指定首選項更改偵聽器，使其不再接收首選項更改事件。
protected abstract void	removeSpi(String key) 移除此首選項節點上指定鍵的關聯值（如果有）。
void	sync() 根據 Preferences.sync() 中的規範實作 sync 方法。
protected abstract void	syncSpi() 此方法是在此節點被鎖定的情況下調用的。
String	toString() 返回此首選項節點的絕對路徑名稱。

從類別 java.util.prefs.Preferences 繼承的方法

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

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

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

欄位詳細資訊

newNode

protected boolean newNode

如果在創建此物件前內部存儲中不存在此節點，則該欄位為 true。該欄位被初始化為 false，但是子類別建構子可以將其設置為 true（並且以後不應再修改）。此欄位指示創建完成時是否啟動節點更改事件。

lock

protected final Object lock

使用其監視器鎖定此節點的物件。使用此物件（優先於節點本身）來減少由於鎖定節點而有意或無意拒絕服務的可能性。為了避免死鎖，永遠 不要讓保持該節點後代上的鎖定的執行緒鎖定節點。

建構子詳細資訊

AbstractPreferences

protected AbstractPreferences(AbstractPreferences parent,
                              String name)

用指定的父節點和與其父節點相關的指定名稱創建首選項節點。

參數：

parent - 此首選項節點的父節點；如果此首選項是根，則為 null。

name - 此首選項節點相對於其父節點的名稱，如果此首選項是根，則為 ""。

拋出：

IllegalArgumentException - 如果 name 套件含一個斜槓 ('/') 或者 parent 為 null 且名稱不是 ""。

方法詳細資訊

put

public void put(String key,
                String value)

根據 Preferences.put(String,String) 中的規範實作 put 方法。

此實作檢查鍵和值是否合法，獲取此首選項節點的鎖定，檢查該節點是否未被移除，調用 putSpi(String,String)，並且如果存在首選項更改偵聽器，則將由事件指派執行緒所處理的通知事件加入佇列。

指定者：

類別 Preferences 中的 put

參數：

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

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

拋出：

NullPointerException - 如果 key 或 value 為 null。

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

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

get

public String get(String key,
                  String def)

根據 Preferences.get(String,String) 中的規範實作 get 方法。

此實作首先檢查 key 是否為 null；如果是，則拋出 NullPointerException。然後，它獲取此首選項節點的鎖，檢查該節點是否未被移除，調用 getSpi(String) 並返回結果，除非 getSpi 調用返回 null 或拋出異常，在這種情況下此調用返回 def。

指定者：

類別 Preferences 中的 get

參數：

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

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

返回：

與 key 相關聯的值；如果沒有與 key 相關聯的值，則返回 def。

拋出：

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

NullPointerException - 如果 key 為 null。（預設值 null 是 允許的。）

remove

public void remove(String key)

根據 Preferences.remove(String) 中的規範實作 remove(String) 方法。

此實作獲取首選項節點的鎖，檢查該節點是否未被移除，調用 removeSpi(String)，並且如果存在首選項更改偵聽器，則將由事件指派執行緒所處理的通知事件加入佇列。

指定者：

類別 Preferences 中的 remove

參數：

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

拋出：

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

clear

public void clear()
           throws BackingStoreException

根據 Preferences.clear() 中的規範實作 clear 方法。

此實作獲取首選項節點的鎖，調用 keys() 以獲取鍵的陣列，並且對每個鍵調用 remove(String)，從而在陣列上進行迭代。

指定者：

類別 Preferences 中的 clear

拋出：

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

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

另請參見：

Preferences.removeNode()

putInt

public void putInt(String key,
                   int value)

根據 Preferences.putInt(String,int) 中的規範實作 putInt 方法。

此實作使用 Integer.toString(int) 將 value 轉換為一個字元串，並在結果上調用 put(String,String)。

指定者：

類別 Preferences 中的 putInt

參數：

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

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

拋出：

NullPointerException - 如果 key 為 null。

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

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

另請參見：

Preferences.getInt(String,int)

getInt

public int getInt(String key,
                  int def)

根據 Preferences.getInt(String,int) 中的規範實作 getInt 方法。

此實作調用 get(key, null)。如果返回值為非 null，則實作嘗試使用 Integer.parseInt(String) 將其轉換為 int。如果嘗試成功，則此方法返回得到的值。否則返回 def。

指定者：

類別 Preferences 中的 getInt

參數：

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

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

返回：

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

拋出：

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

NullPointerException - 如果 key 為 null。

另請參見：

Preferences.putInt(String,int), Preferences.get(String,String)

putLong

public void putLong(String key,
                    long value)

根據 Preferences.putLong(String,long) 中的規範實作 putLong 方法。

此實作使用 Long.toString(long) 將 value 轉換為字元串，並在結果上調用 put(String,String)。

指定者：

類別 Preferences 中的 putLong

參數：

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

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

拋出：

NullPointerException - 如果 key 為 null。

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

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

另請參見：

Preferences.getLong(String,long)

getLong

public long getLong(String key,
                    long def)

根據 Preferences.getLong(String,long) 中的規範實作 getLong 方法。

此實作調用 get(key, null)。如果返回值為非 null，則實作嘗試嘗試使用 Long.parseLong(String) 將其轉換為 long。如果嘗試成功，則此方法返回得到的值。否則返回 def。

指定者：

類別 Preferences 中的 getLong

參數：

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

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

返回：

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

拋出：

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

NullPointerException - 如果 key 為 null。

另請參見：

Preferences.putLong(String,long), Preferences.get(String,String)

putBoolean

public void putBoolean(String key,
                       boolean value)

根據 Preferences.putBoolean(String,boolean) 中的規範實作 putBoolean 方法。

此實作使用 String.valueOf(boolean) 將 value 轉換為字元串，並在結果上調用 put(String,String)。

指定者：

類別 Preferences 中的 putBoolean

參數：

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

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

拋出：

NullPointerException - 如果 key 為 null。

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

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

另請參見：

Preferences.getBoolean(String,boolean), Preferences.get(String,String)

getBoolean

public boolean getBoolean(String key,
                          boolean def)

根據 Preferences.getBoolean(String,boolean) 中的規範實作 getBoolean 方法。

此實作調用 get(key, null)。如果返回值為非 null，則使用 String.equalsIgnoreCase(String) 將其與 "true" 相比較。如果比較返回 true，則此調用返回 true。否則，再次使用 String.equalsIgnoreCase(String) 將初始值與 "false" 相比較。如果比較返回 true，則此調用返回 false。否則此調用返回 def。

指定者：

類別 Preferences 中的 getBoolean

參數：

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

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

返回：

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

拋出：

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

NullPointerException - 如果 key 為 null。

另請參見：

Preferences.get(String,String), Preferences.putBoolean(String,boolean)

putFloat

public void putFloat(String key,
                     float value)

根據 Preferences.putFloat(String,float) 中的規範實作 putFloat 方法。

此實作使用 Float.toString(float) 將 value 轉換為字元串，並在結果上調用 put(String,String)。

指定者：

類別 Preferences 中的 putFloat

參數：

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

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

拋出：

NullPointerException - 如果 key 為 null。

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

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

另請參見：

Preferences.getFloat(String,float)

getFloat

public float getFloat(String key,
                      float def)

根據 Preferences.getFloat(String,float) 中的規範實作 getFloat 方法。

此實作調用 get(key, null)。如果返回值為非 null，則實作嘗試使用 Float.parseFloat(String) 將其轉換為 float。如果嘗試成功，則此方法返回得到的值。否則返回 def。

指定者：

類別 Preferences 中的 getFloat

參數：

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

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

返回：

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

拋出：

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

NullPointerException - 如果 key 為 null。

另請參見：

Preferences.putFloat(String,float), Preferences.get(String,String)

putDouble

public void putDouble(String key,
                      double value)

根據 Preferences.putDouble(String,double) 中的規範實作 putDouble 方法。

此實作使用 Double.toString(double) 將 value 轉換為字元串，並在結果上調用 put(String,String)。

指定者：

類別 Preferences 中的 putDouble

參數：

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

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

拋出：

NullPointerException - 如果 key 為 null。

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

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

另請參見：

Preferences.getDouble(String,double)

getDouble

public double getDouble(String key,
                        double def)

根據 Preferences.getDouble(String,double) 中的規範實作 getDouble 方法。

此實作調用 get(key, null)。如果返回值為非 null，則實作嘗試使用 Double.parseDouble(String) 將其轉換為 double。如果嘗試成功，則此方法返回得到的值。否則返回 def。

指定者：

類別 Preferences 中的 getDouble

參數：

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

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

返回：

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

拋出：

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

NullPointerException - 如果 key 為 null。

另請參見：

Preferences.putDouble(String,double), Preferences.get(String,String)

putByteArray

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

根據 Preferences.putByteArray(String,byte[]) 中的規範實作 putByteArray 方法。

指定者：

類別 Preferences 中的 putByteArray

參數：

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

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

拋出：

NullPointerException - 如果 key 或 value 為 null。

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

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

另請參見：

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

getByteArray

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

根據 Preferences.getByteArray(String,byte[]) 中的規範實作 getByteArray 方法。

指定者：

類別 Preferences 中的 getByteArray

參數：

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

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

返回：

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

拋出：

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

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

另請參見：

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

keys

public String[] keys()
              throws BackingStoreException

根據 Preferences.keys() 中的規範實作 keys 方法。

此實作獲取首選項節點的鎖，檢查該節點是否未被移除並調用 keysSpi()。

指定者：

類別 Preferences 中的 keys

返回：

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

拋出：

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

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

childrenNames

public String[] childrenNames()
                       throws BackingStoreException

根據 Preferences.childrenNames() 中的規範實作 children 方法。

此實作獲取首選項節點的鎖，檢查該節點是否未被移除，建構已初始化為已快取記憶體的子節點名稱（此節點「子快取記憶體」中的子節點）的 TreeSet，調用 childrenNamesSpi() 並將所有返回的子名稱添加到該 set 中。使用 toArray 方法將階層樹 set 的元素轉儲到 String 陣列中，並返回此陣列。

指定者：

類別 Preferences 中的 childrenNames

返回：

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

拋出：

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

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

另請參見：

cachedChildren()

cachedChildren

protected final AbstractPreferences[] cachedChildren()

返回此節點的所有已知未移除子節點。

返回：

此節點的所有已知未移除子節點。

parent

public Preferences parent()

根據 Preferences.parent() 中的規範實作 parent 方法。

此實作獲取首選項節點的鎖，檢查該節點是否未被移除，並返回傳遞給此節點建構子的父值。

指定者：

類別 Preferences 中的 parent

返回：

首選項節點的父節點。

拋出：

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

node

public Preferences node(String path)

根據 Preferences.node(String) 中的規範實作 node 方法。

此實作獲取首選項節點的鎖並檢查該節點是否未被移除。如果 path 為 ""，則返回此節點；如果 path 為 "/"，則返回此節點的根。如果 path 中的第一個字元不是 '/'，則此實作將 path 分解為標記，並從此節點到指定節點遞歸式遍歷此路徑，在遍歷的每一個步驟都要「使用」path 中的名稱和斜槓。在每一個步驟，都要鎖定當前節點並為指定節點檢查該節點的子快取記憶體。如果未找到，則該名稱已經過檢查，以確保其長度不超過 MAX_NAME_LENGTH。然後，調用 childSpi(String) 方法並將結果存儲在此節點的子快取記憶體中。如果新創建的 Preferences 物件的 newNode 欄位為 true，並且存在任一節點更改偵聽器，則將由事件指派執行緒所處理的通知事件加入佇列。

沒有其他的標記時，此方法將返回在子快取記憶體中找到的最後一個值或 childSpi 返回的值。如果在遍歷過程中，連續出現兩個 "/" 標記或者最後一個標記是 "/"（而不是名稱），則拋出適當的 IllegalArgumentException。

如果 path 的第一個字元是 '/'（指示絕對路徑名），則在將 path 分解為標記前，刪除此首選項節點的鎖，此方法從根（不是從此節點）開始遞歸式遍歷此路徑。該遞歸在其他方面與對相對路徑名的描述相同。根據 locking invariant，從根節點開始遍歷前刪除此節點上的鎖，這對於避免可能發生的死鎖是至關重要的。

指定者：

類別 Preferences 中的 node

參數：

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

返回：

指定的首選項節點。

拋出：

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

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

另請參見：

Preferences.flush()

nodeExists

public boolean nodeExists(String path)
                   throws BackingStoreException

根據 Preferences.nodeExists(String) 中的規範實作 nodeExists 方法。

此實作非常類似於 node(String)，不同之處是使用了 getChild(String) 而沒有使用 childSpi(String)。

指定者：

類別 Preferences 中的 nodeExists

參數：

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

返回：

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

拋出：

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

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

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

removeNode

public void removeNode()
                throws BackingStoreException

根據 Preferences.removeNode() 中的規範實作 removeNode() 方法。

此實作檢查此節點是否為根；如果是，則拋出適當的異常。然後，它鎖定此節點的父節點，並調用遞歸說明器方法來遍歷以此節點為根的子階層樹。遞歸方法鎖定其所調用的節點，檢查它是否未被刪除，然後確保已快取記憶體其所有子節點：調用 childrenNamesSpi() 方法並檢查每個返回的子節點名稱是否已包含在子快取記憶體中。如果沒有快取記憶體子節點，則會調用 childSpi(String) 方法為其創建一個 Preferences 實例並將此實例置於子快取記憶體中。然後，說明器方法在其子快取記憶體所包含的每個節點上遞歸式自我調用。下一步，它調用 removeNodeSpi()，將其自身標記為已移除，並從其父節點的子快取記憶體中自我移除。最後，如果存在任何節點更改偵聽器，則其會將由事件指派執行緒所處理的通知事件加入佇列。

注意，始終使用所有祖先來調用說明器方法，直到鎖定「未被移除的最近祖先」為止。

指定者：

類別 Preferences 中的 removeNode

拋出：

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

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

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

另請參見：

Preferences.flush()

name

public String name()

根據 Preferences.name() 中的規範實作 name 方法。

此實作僅返回傳遞給此節點建構子的名稱。

指定者：

類別 Preferences 中的 name

返回：

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

absolutePath

public String absolutePath()

根據 Preferences.absolutePath() 中的規範實作 absolutePath 方法。

此實作僅返回建構此節點時計算出的絕對路徑名（基於傳遞給此節點建構子的名稱和傳遞給此節點祖先建構子的名稱）。

指定者：

類別 Preferences 中的 absolutePath

返回：

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

isUserNode

public boolean isUserNode()

根據 Preferences.isUserNode() 中的規範實作 isUserNode 方法。

此實作將此節點的根節點（在 private 欄位中存儲）與 Preferences.userRoot() 返回的值相比較。如果兩個物件參考相同，則此方法返回 true。

指定者：

類別 Preferences 中的 isUserNode

返回：

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

addPreferenceChangeListener

public void addPreferenceChangeListener(PreferenceChangeListener pcl)

從類別 Preferences 複製的描述

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

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

指定者：

類別 Preferences 中的 addPreferenceChangeListener

參數：

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

另請參見：

Preferences.removePreferenceChangeListener(PreferenceChangeListener), Preferences.addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public void removePreferenceChangeListener(PreferenceChangeListener pcl)

從類別 Preferences 複製的描述

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

指定者：

類別 Preferences 中的 removePreferenceChangeListener

參數：

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

另請參見：

Preferences.addPreferenceChangeListener(PreferenceChangeListener)

addNodeChangeListener

public void addNodeChangeListener(NodeChangeListener ncl)

從類別 Preferences 複製的描述

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

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

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

指定者：

類別 Preferences 中的 addNodeChangeListener

參數：

ncl - 要添加的 NodeChangeListener。

另請參見：

Preferences.removeNodeChangeListener(NodeChangeListener), Preferences.addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public void removeNodeChangeListener(NodeChangeListener ncl)

從類別 Preferences 複製的描述

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

指定者：

類別 Preferences 中的 removeNodeChangeListener

參數：

ncl - 要移除的 NodeChangeListener。

另請參見：

Preferences.addNodeChangeListener(NodeChangeListener)

putSpi

protected abstract void putSpi(String key,
                               String value)

將給定的鍵-值關聯置於此首選項節點中。保證 key 和 value 均為非 null，並且具有合法的長度。此外，還要保證此節點未被移除。（實作者不必檢查這些事情。）

利用此節點上保持的鎖定調用此方法。

getSpi

protected abstract String getSpi(String key)

返回與此首選項節點上的指定鍵相關聯的值；如果不存在此鍵的關聯值或此時無法確定該關聯值，則返回 null。保證 key 為非 null。此外，還要保證此節點未被移除。（實作者不必檢查這兩件事。）

一般而言，此方法在任何情形下也不應拋出異常。但是，如果它確實拋出了異常，則該異常將被解釋為 null，並按 null 返回值對待。

利用此節點上保持的鎖定調用此方法。

返回：

與此首選項節點上的指定鍵相關聯的值；如果不存在此鍵的關聯值或此時無法確定該關聯值，則返回 null。

removeSpi

protected abstract void removeSpi(String key)

移除此首選項節點上指定鍵的關聯值（如果有）。保證 key 為非 null。此外，還要保證此節點未被移除。（實作者不必檢查這兩件事。）

利用此節點上保持的鎖定調用此方法。

removeNodeSpi

protected abstract void removeNodeSpi()
                               throws BackingStoreException

移除此首選項節點，該首選項節點及其所包含的所有首選項都將失效。進行此調用時，指定子節點不具有任何子節點（即 Preferences.removeNode() 方法以自下向上的方式重複調用此方法，在移除節點本身之前首先移除該節點的所有子節點）。

使用此節點及其父節點上保持的鎖調用此方法（對 Preferences.removeNode() 的一次調用即可移除所有祖先）。

在此節點（或祖先）上調用 flush 方法之前對節點的移除不必是持久的。

如果此節點拋出 BackingStoreException，則該異常將會傳播到封閉的 removeNode() 調用之外。

拋出：

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

keysSpi

protected abstract String[] keysSpi()
                             throws BackingStoreException

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

利用此節點上保持的鎖調用此方法。

如果此節點拋出 BackingStoreException，則該異常將會傳播到封閉的 keys() 調用之外。

返回：

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

拋出：

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

childrenNamesSpi

protected abstract String[] childrenNamesSpi()
                                      throws BackingStoreException

返回此首選項節點的子節點名稱。（如果此節點不具有任何子節點，則返回陣列的大小將為 0。）此方法不必返回任何已快取記憶體節點的名稱，但是這樣做也沒有什麼壞處。

利用此節點上保持的鎖調用此方法。

如果此節點拋出 BackingStoreException，則該異常將會傳播到封閉的 childrenNames() 調用之外。

返回：

包含此首選項節點的子節點名稱的陣列。

拋出：

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

getChild

protected AbstractPreferences getChild(String nodeName)
                                throws BackingStoreException

如果指定的子節點存在，則返回該子節點；如果它不存在，則返回 null。保證 nodeName 為非 null、非空(null)、不包含斜槓字元 ('/')，並且長度不超過 Preferences.MAX_NAME_LENGTH 個字元。此外，還要保證此節點未被移除。（如果選擇覆寫此方法，則實作者不必檢查這些事情。）

最後，保證最後一次將指定節點移除後此方法的以前調用或 childSpi(java.lang.String) 未曾返回它。換句話說，快取記憶體的值始終在首選項中使用，以調用此方法。（如果選擇覆寫此方法，則實作者不必維護它自己以前返回的子節點快取記憶體。）

此實作獲取首選項節點的鎖，調用 childrenNames() 以獲取此節點的子節點的名稱陣列，並在該陣列上迭代，將每個子節點的名稱與指定節點名稱進行比較。如果子節點名稱正確，則調用 childSpi(String) 方法並返回得到的節點。如果迭代完成時沒有找到指定的名稱，則返回 null。

參數：

nodeName - 要搜尋的子節點的名稱。

返回：

如果指定的子節點存在，則返回該子節點；如果它不存在，則返回 null。

拋出：

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

childSpi

protected abstract AbstractPreferences childSpi(String name)

返回此首選項節點的指定子節點；如果該子節點尚未存在，則創建它。保證 name 為非 null、非空(null)、不包含斜槓字元 ('/')，並且長度不超過 Preferences.MAX_NAME_LENGTH 個字元。此外，還要保證此節點未被移除。（實作者不必檢查這些事情。）

最後，保證最後一次將指定節點移除後此方法的以前調用或 getChild(String) 未曾返回它。換句話說，快取記憶體的值始終在首選項中使用，以調用此方法。子類別不必維護它們自己以前返回的子節點快取記憶體。

實作者必須確保返回的節點沒有被移除。如果以前移除了此節點的名稱相同的子節點，則實作者必須返回一個新建構的 AbstractPreferences 節點；一旦移除，AbstractPreferences 節點便無法「再生」。

如果此方法導致創建了節點，則在此節點或其祖先之一（或子節點）上調用 flush 方法之前，不保證該節點是持久的。

利用此節點上保持的鎖調用此方法。

參數：

name - 要返回的子節點的名稱（相對於此首選項節點）。

返回：

指定的子節點。

toString

public String toString()

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

指定者：

類別 Preferences 中的 toString

返回：

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

sync

public void sync()
          throws BackingStoreException

根據 Preferences.sync() 中的規範實作 sync 方法。

此實作調用鎖定此節點的遞歸說明器方法，針對該方法調用 syncSpi() ，解除此節點的鎖，並在每個「快取記憶體子節點」上遞歸式調用這一方法。快取記憶體子節點是此節點的子節點，已在此 VM 中創建並且後來沒有被移除。實際上，此方法對以此節點為根的「快取記憶體子階層樹」進行深度優先遍歷，針對該 subTree 中的每個節點調用 syncSpi()，這時只有該節點是鎖定的。注意，是自上向下調用 syncSpi() 的。

指定者：

類別 Preferences 中的 sync

拋出：

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

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

另請參見：

flush()

syncSpi

protected abstract void syncSpi()
                         throws BackingStoreException

此方法是在此節點被鎖定的情況下調用的。根據協定，此方法用於同步存儲在此節點上的所有快取記憶體首選項與存儲在內部存儲中的所有快取記憶體首選項。（內部存儲中不存在此節點是完全可能的，或者因為另一個 VM 刪除了它或者因為還沒有創建它。）注意，此方法不 應同步此節點的所有子節點中的首選項。如果內部存儲自然地同步了整個子階層樹，則鼓勵實作者覆寫 sync()，而不是僅僅覆寫此方法。

如果此節點拋出 BackingStoreException，則該異常將會傳播到封閉的 sync() 調用之外。

拋出：

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

flush

public void flush()
           throws BackingStoreException

根據 Preferences.flush() 中的規範實作 flush 方法。

此實作調用鎖定此節點的遞歸說明器方法，針對該方法調用 flushSpi()，解除此節點的鎖，並在每個「快取記憶體子節點」上遞歸式調用這一方法。快取記憶體子節點是此節點的子節點，已在此 VM 中創建並且後來沒有被移除。實際上，此方法對以此節點為根的「快取記憶體子階層樹」進行深度優先遍歷，針對該 subTree 中的每個節點調用 flushSpi()，這時只有該節點是鎖定的。注意，是自上向下調用 flushSpi() 的。

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

指定者：

類別 Preferences 中的 flush

拋出：

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

另請參見：

flush()

flushSpi

protected abstract void flushSpi()
                          throws BackingStoreException

此方法是在此節點被鎖定的情況下調用的。根據協定，此方法用於強制執行從此首選項節點到內部存儲內容的快取記憶體更改，以保證其持久性。（內部存儲中不存在此節點是完全可能的，或者因為另一個 VM 刪除了它或者因為還沒有創建它。）注意，此方法不 應刷新此節點的所有子節點中的首選項。如果內部存儲自然地刷新了整個子階層樹，則鼓勵實作者覆寫 flush()，而不是僅僅覆寫此方法。

如果此節點拋出 BackingStoreException，則該異常將會傳播到封閉的 flush() 調用之外。

拋出：

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

isRemoved

protected boolean isRemoved()

當且僅當已經使用 removeNode() 方法移除此節點（或其祖先）時才返回 true。此方法在返回用於追蹤此狀態的 private 欄位內容前鎖定此節點。

返回：

當且僅當已經使用 removeNode() 方法移除了此節點（或其祖先）時才返回 true。

exportNode

public void exportNode(OutputStream os)
                throws IOException,
                       BackingStoreException

根據 Preferences.exportNode(OutputStream) 中的規範實作 exportNode 方法。

指定者：

類別 Preferences 中的 exportNode

參數：

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

拋出：

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

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

另請參見：

Preferences.importPreferences(InputStream)

exportSubtree

public void exportSubtree(OutputStream os)
                   throws IOException,
                          BackingStoreException

根據 Preferences.exportSubtree(OutputStream) 中的規範實作 exportSubtree 方法。

指定者：

類別 Preferences 中的 exportSubtree

參數：

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

拋出：

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

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

另請參見：

Preferences.importPreferences(InputStream), Preferences.exportNode(OutputStream)