Preferences
クラスのスケルトン実装を提供します。このクラスを使用すれば、簡単に実装することができます。
Thisクラスは、Preferences
実装者専用です。 Preferences
機能の通常のユーザーは、このドキュメントを参照する必要はありません。 Preferences
のドキュメントで十分なはずです。
実装する場合は、9つの抽象サービス・プロバイダ・インタフェース(SPI)メソッドgetSpi(String)
、putSpi(String,String)
、removeSpi(String)
、childSpi(String)
、removeNodeSpi()
、keysSpi()
、childrenNamesSpi()
、syncSpi()
、およびflushSpi()
をオーバーライドする必要があります。 オーバーライドする具象メソッドには、これらのSPIメソッド上に実装する方法を正確に指定する必要があります。 パフォーマンスなどの理由でデフォルトの実装に変更を加えたい場合は、任意の具象メソッドをオーバーライドします。
SPIメソッドは、例外処理について3つのグループに分類されます。 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
を呼び出すことは、以前のすべての操作が正常に永続化されたことを意味しません。
putSpi, removeSpi and childSpi
「必要」が例外をスローする状況が1つあります: 呼び出し元に、リクエストされた操作を実行するための十分な特権がベースとなるオペレーティング・システム上にある場合。 たとえば、ほとんどのシステムでは、非特権ユーザーがシステム設定を変更しようとすると例外が発生します。 必要な特権は、実装ごとに異なります。 たとえば、ファイル・システム内のディレクトリの内容を変更する権限が必要な場合や、レジストリ内のキーの内容を変更する権限が必要な場合があります。 こうした環境の場合、プログラムの実行は続行しないでください。続行しても、これらの操作は適用されることがないためです。 このような環境では、できるだけ例外をスローすることをお薦めします。 SecurityException
が適切と考えられます。
ほとんどのSPIメソッドの実装では、設定ノードで情報の読み込みまたは書込みを行う必要があります。 設定ノードは、別のVMによってバッキング・ストアから並行して削除されている場合があります。 このノードが削除されている場合は、実装するユーザーが再作成してください。
実装ノート: SunのデフォルトのPreferences
実装では、ユーザーの識別情報はベースとなるオペレーティング・システムから継承され、仮想マシンの存続期間中は変更されません。 サーバー側のPreferences
実装では、静的ThreadLocal
インスタンスを使用して暗黙的にPreferences
メソッドに渡される、リクエストからリクエストへのユーザー・アイデンティティ変更があることが認識されます。 このような実装の作成者は、ユーザーを各Preferences
インスタンスに永続的に関連付けるのではなく、プリファレンスがアクセスされた時点で(たとえば、get(String,String)
またはput(String,String)
メソッド)のユーザーを判断することを「強く」お薦めします。 後者の動作は、通常のPreferences
の使用と競合するため、大きな混乱を招きます。
- 導入されたバージョン:
- 1.4
- 関連項目:
-
フィールドのサマリー
修飾子と型フィールド説明protected final Object
このオブジェクトには、このノードをロックしたときに使用されるモニターが組み込まれています。protected boolean
このオブジェクトを作成する前にこのノードがバッキング・ストアに存在しなかった場合は、このフィールドをtrue
にする必要があります。クラス java.util.prefs.Preferencesで宣言されたフィールド
MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH
-
コンストラクタのサマリー
修飾子コンストラクタ説明protected
AbstractPreferences
(AbstractPreferences parent, String name) 指定された親とその親を起点として相対名を使用して、設定ノードを作成します。 -
メソッドのサマリー
修飾子と型メソッド説明Preferences.absolutePath()
の仕様に従って、absolutePath
メソッドを実装します。void
指定されたリスナーがこのノードのノード変更イベントを受信するように登録します。void
指定されたリスナーがこの設定ノードに対する設定変更イベントを受信するように登録します。protected final AbstractPreferences[]
このノードの削除されていない既知の子をすべて返します。String[]
Preferences.childrenNames()
の仕様に従って、children
メソッドを実装します。protected abstract String[]
この設定ノードの子の名前を返します。protected abstract AbstractPreferences
この設定ノードの名前付きの子を返します。存在しない場合は作成します。void
clear()
Preferences.clear()
の仕様に従って、clear
メソッドを実装します。void
Preferences.exportNode(OutputStream)
の仕様に従って、exportNode
メソッドを実装します。void
Preferences.exportSubtree(OutputStream)
の仕様に従って、exportSubtree
メソッドを実装します。void
flush()
Preferences.flush()
の仕様に従って、flush
メソッドを実装します。protected abstract void
flushSpi()
このメソッドが呼び出されるときは、このノードがロックされます。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
指定された子が存在する場合はその子を返し、存在しない場合はnull
を返します。double
Preferences.getDouble(String,double)
の仕様に従って、getDouble
メソッドを実装します。float
Preferences.getFloat(String,float)
の仕様に従って、getFloat
メソッドを実装します。int
Preferences.getInt(String,int)
の仕様に従って、getInt
メソッドを実装します。long
Preferences.getLong(String,long)
の仕様に従って、getLong
メソッドを実装します。protected abstract String
このプリファレンス・ノードで指定したキーに関連付けられた値を返します。このキーの関連付けがない場合はnull
を返し、この時点でアソシエーションを判別できません。protected boolean
このノード(または祖先)がremoveNode()
メソッドで削除された場合は、true
を返します。boolean
Preferences.isUserNode()
の仕様に従って、isUserNode
メソッドを実装します。String[]
keys()
Preferences.keys()
の仕様に従って、keys
メソッドを実装します。protected abstract String[]
keysSpi()
この設定ノード内に関連付けられている値を持つキーをすべて返します。name()
Preferences.name()
の仕様に従って、name
メソッドを実装します。Preferences.node(String)
の仕様に従って、node
メソッドを実装します。boolean
nodeExists
(String path) Preferences.nodeExists(String)
の仕様に従って、nodeExists
メソッドを実装します。parent()
Preferences.parent()
の仕様に従って、parent
メソッドを実装します。void
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
Preferences.putDouble(String,double)
の仕様に従って、putDouble
メソッドを実装します。void
Preferences.putFloat(String,float)
の仕様に従って、putFloat
メソッドを実装します。void
Preferences.putInt(String,int)
の仕様に従って、putInt
メソッドを実装します。void
Preferences.putLong(String,long)
の仕様に従って、putLong
メソッドを実装します。protected abstract void
指定されたキーと値のペアをこの設定ノードに関連付けます。void
Preferences.remove(String)
の仕様に従って、remove(String)
メソッドを実装します。void
Preferences.removeNode()
の仕様に従って、removeNode()
メソッドを実装します。void
指定されたNodeChangeListener
を削除して、変更イベントを受信しないようにします。protected abstract void
この設定ノードを削除し、削除したノードに含まれている設定をすべて無効にします。void
指定された設定変更リスナーを削除して、設定変更イベントの受信を停止します。protected abstract void
この設定ノードの指定されたキーに関連付けがある場合は、それを削除します。void
sync()
Preferences.sync()
の仕様に従って、sync
メソッドを実装します。protected abstract void
syncSpi()
このメソッドが呼び出されるときは、このノードがロックされます。toString()
この設定ノードの絶対パス名を返します。クラス java.util.prefs.Preferencesで宣言されたメソッド
importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot
-
フィールド詳細
-
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
Preferences.put(String,String)
の仕様に従って、put
メソッドを実装します。この実装では、キーと値が正当であることを確認し、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、
putSpi(String,String)
を呼び出します。また、設定変更リスナーがある場合は、イベント・ディスパッチ・スレッドに渡すために通知イベントをキューに入れます。- 定義:
put
、クラスPreferences
- パラメータ:
key
- 指定の値が関連付けられるキー。value
- 指定のキーに関連付けられる値。- 例外:
NullPointerException
- キーまたは値がnull
の場合。IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超えた場合、またはvalue.length
がMAX_VALUE_LENGTH
を超えた場合。IllegalArgumentException
- キーまたは値のいずれかにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。
-
get
Preferences.get(String,String)
の仕様に従って、get
メソッドを実装します。この実装では、
key
がnull
でNullPointerException
がスローされるかどうかが最初にチェックされます(その場合)。 次に、このプリファレンス・ノードのロックを取得し、ノードが削除されていないことを確認し、getSpi(String)
を起動して結果を返します。ただし、getSpi
の呼出しでnull
が返されるか、例外がスローされた場合、この呼出しではdef
が返されます。- 定義:
get
、クラスPreferences
- パラメータ:
key
- 関連付けられている値が返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がない場合に返される値。- 戻り値:
key
に関連付けられた値、またはkey
に関連付けられている値がない場合はdef
。- 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
- キーがnull
の場合 (null
のデフォルトが許可されます。)IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。
-
remove
public void remove(String key) Preferences.remove(String)
の仕様に従って、remove(String)
メソッドを実装します。この実装では、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、
removeSpi(String)
を呼び出します。また、設定変更リスナーがある場合は、イベント・ディスパッチ・スレッドに渡すために通知イベントをキューに入れます。- 定義:
remove
、クラスPreferences
- パラメータ:
key
- マッピングが設定ノードから削除されるキー。- 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。NullPointerException
-key
がnull
である場合。
-
clear
public void clear() throws BackingStoreExceptionPreferences.clear()
の仕様に従って、clear
メソッドを実装します。この実装では、この設定ノードのロックを取得し、
keys()
を呼び出してキーの配列を取得します。次に、各キーに対しremove(String)
を呼び出して、配列を繰り返します。- 定義:
clear
、クラスPreferences
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
putInt
public void putInt(String key, int value) Preferences.putInt(String,int)
の仕様に従って、putInt
メソッドを実装します。この実装では、
value
をInteger.toString(int)
を含む文字列に変換し、結果に対してput(String,String)
を呼び出します。- 定義:
putInt
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーがnull
の場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
getInt
public int getInt(String key, int def) Preferences.getInt(String,int)
の仕様に従って、getInt
メソッドを実装します。この実装は
get(key, null)
を呼び出します。 戻り値がnull以外の場合、実装では、Integer.parseInt(String)
を使用してint
に変換しようとします。 正常に変換された場合は、このメソッドによって戻り値が返されます。 それ以外の場合は、def
が返されます。- 定義:
getInt
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がintとして返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値をintとして解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表されるint値、または関連する値が存在しないか、intとして解釈できない場合にはdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
putLong
public void putLong(String key, long value) Preferences.putLong(String,long)
の仕様に従って、putLong
メソッドを実装します。この実装では、
value
をLong.toString(long)
を含む文字列に変換し、結果に対してput(String,String)
を呼び出します。- 定義:
putLong
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーがnull
の場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
getLong
public long getLong(String key, long def) Preferences.getLong(String,long)
の仕様に従って、getLong
メソッドを実装します。この実装は
get(key, null)
を呼び出します。 戻り値がnull以外の場合、実装では、Long.parseLong(String)
を使用してlong
に変換しようとします。 正常に変換された場合は、このメソッドによって戻り値が返されます。 それ以外の場合は、def
が返されます。- 定義:
getLong
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がlongとして返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値をlongとして解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表されるlong値、または関連付けられた値が存在しないか、longとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
putBoolean
public void putBoolean(String key, boolean value) Preferences.putBoolean(String,boolean)
の仕様に従って、putBoolean
メソッドを実装します。この実装では、
value
をString.valueOf(boolean)
を含む文字列に変換し、結果に対してput(String,String)
を呼び出します。- 定義:
putBoolean
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーがnull
の場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
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
を返します。- 定義:
getBoolean
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がbooleanとして返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値をブールとして解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表されるブール値、または関連付けられた値が存在しないか、ブールとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
putFloat
public void putFloat(String key, float value) Preferences.putFloat(String,float)
の仕様に従って、putFloat
メソッドを実装します。この実装では、
value
をFloat.toString(float)
を含む文字列に変換し、結果に対してput(String,String)
を呼び出します。- 定義:
putFloat
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーがnull
の場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
getFloat
public float getFloat(String key, float def) Preferences.getFloat(String,float)
の仕様に従って、getFloat
メソッドを実装します。この実装は
get(key, null)
を呼び出します。 戻り値がnull以外の場合、実装では、Float.parseFloat(String)
を使用してfloat
に変換しようとします。 正常に変換された場合は、このメソッドによって戻り値が返されます。 それ以外の場合は、def
が返されます。- 定義:
getFloat
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がfloatとして返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値を浮動小数として解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表される浮動小数点値。関連付けられた値が存在しないか、または浮動小数点として解釈できない場合は、def
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
putDouble
public void putDouble(String key, double value) Preferences.putDouble(String,double)
の仕様に従って、putDouble
メソッドを実装します。この実装では、
value
をDouble.toString(double)
を含む文字列に変換し、結果に対してput(String,String)
を呼び出します。- 定義:
putDouble
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーがnull
の場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
getDouble
public double getDouble(String key, double def) Preferences.getDouble(String,double)
の仕様に従って、getDouble
メソッドを実装します。この実装は
get(key, null)
を呼び出します。 戻り値がnull以外の場合、実装では、Double.parseDouble(String)
を使用してdouble
に変換しようとします。 正常に変換された場合は、このメソッドによって戻り値が返されます。 それ以外の場合は、def
が返されます。- 定義:
getDouble
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がdoubleとして返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値をdoubleとして解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表されるdouble値、または関連付けられた値が存在しないか、doubleとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
putByteArray
public void putByteArray(String key, byte[] value) Preferences.putByteArray(String,byte[])
の仕様に従って、putByteArray
メソッドを実装します。- 定義:
putByteArray
、クラスPreferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- キーまたは値がnull
の場合。IllegalArgumentException
- key.length()がMAX_KEY_LENGTHを超える場合、またはvalue.lengthがMAX_VALUE_LENGTH*3/4を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
getByteArray
public byte[] getByteArray(String key, byte[] def) Preferences.getByteArray(String,byte[])
の仕様に従って、getByteArray
メソッドを実装します。- 定義:
getByteArray
、クラスPreferences
- パラメータ:
key
- 関連付けられている値がbyte配列として返されるキー。def
- このプリファレンス・ノードにkey
に関連付けられた値がないか、関連付けられた値をバイト配列として解釈できない場合に返される値。- 戻り値:
- このプリファレンス・ノードの
key
に関連付けられた文字列で表されるバイト配列値、または関連付けられている値が存在しないかバイト配列として解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。 (def
にはnull
値を使用できます。)IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
-
keys
public String[] keys() throws BackingStoreExceptionPreferences.keys()
の仕様に従って、keys
メソッドを実装します。この実装は、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、
keysSpi()
を呼び出します。- 定義:
keys
、クラスPreferences
- 戻り値:
- この設定ノード内に関連付けられている値を持つキーの配列。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。
-
childrenNames
public String[] childrenNames() throws BackingStoreExceptionPreferences.childrenNames()
の仕様に従って、children
メソッドを実装します。この実装では、このプリファレンス・ノードのロックを取得し、ノードが削除されていないことを確認し、すでにキャッシュされている子の名前に初期化された
TreeSet
を構築し (このノードの"child-cache"の子)、childrenNamesSpi()
を呼び出して、返された子の名前をすべてセットに追加します。 ツリー・セットの要素は、toArray
メソッドを使用してString
配列にダンプされ、この配列が返されます。- 定義:
childrenNames
、クラスPreferences
- 戻り値:
- この設定ノードの子の名前。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
cachedChildren
protected final AbstractPreferences[] cachedChildren()このノードの削除されていない既知の子をすべて返します。- 戻り値:
- このノードの削除されていない既知のすべての子。
-
parent
public Preferences parent()Preferences.parent()
の仕様に従って、parent
メソッドを実装します。この実装では、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、このノードのコンストラクタに渡された親の値を返します。
- 定義:
parent
、クラスPreferences
- 戻り値:
- この設定ノードの親。
- 例外:
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
によって返された最後の値が返されます。 トラバーサル中に2つの"/"
トークンが連続して発生した場合、または最終トークンが"/"
(名前ではなく)の場合は、適切なIllegalArgumentException
がスローされます。path
の最初の文字が'/'
(絶対パス名を示す)の場合、このプリファレンス・ノードのロックは、path
をトークンに分割する前に削除され、このメソッドはルート(このノードから開始するのではなく、)から始まるパスを再帰的にトラバースします。 最初の文字が「/」以外の場合は、相対パス名と同じトラバースを行います。 ルート・ノードでトラバースを開始する前に、locking invariant
のとおりに、デッドロックの可能性を防ぐため、このノードのロックを解除することが不可欠です。- 定義:
node
、クラスPreferences
- パラメータ:
path
- 返される設定ノードのパス名。- 戻り値:
- 指定された設定ノード。
- 例外:
IllegalArgumentException
- パス名が無効である場合(つまり、パス名に連続した複数のスラッシュ文字が含まれているか、パス名がスラッシュ文字で終わっていてその長さが2文字以上の場合)。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
nodeExists
public boolean nodeExists(String path) throws BackingStoreException Preferences.nodeExists(String)
の仕様に従って、nodeExists
メソッドを実装します。この実装は、
childSpi(String)
の代わりに、getChild(String)
が使用されることを除き、node(String)
とよく似ています。- 定義:
nodeExists
、クラスPreferences
- パラメータ:
path
- 存在が確認されるノードのパス名。- 戻り値:
- 指定されたノードが存在する場合にtrue。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalArgumentException
- パス名が無効である場合(つまり、パス名に連続した複数のスラッシュ文字が含まれているか、パス名がスラッシュ文字で終わっていてその長さが2文字以上の場合)。IllegalStateException
- このノード(または祖先)がremoveNode()
メソッドで削除され、pathname
が空の文字列(""
)でない場合。
-
removeNode
public void removeNode() throws BackingStoreExceptionPreferences.removeNode()
の仕様に従って、removeNode()
メソッドを実装します。この実装は、このノードがルートであるかどうかを確認します。ルートである場合は、該当する例外をスローします。 次に、このノードの親をロックし、このノードをルートとしたサブツリーをトラバースする再帰的ヘルパー・メソッドを呼び出します。 この再帰的メソッドは、その呼出し元のノードをロックし、そのノードが削除されていないことを確認したあとで、そのノードの子がすべてキャッシュされていることを確認します。つまり、
childrenNamesSpi()
メソッドを呼び出し、返された子の名前が子キャッシュに格納されているかどうかを確認します。 子がまだキャッシュされていない場合、childSpi(String)
メソッドが呼び出されてPreferences
インスタンスが作成され、このインスタンスが子キャッシュに配置されます。 このヘルパー・メソッドは、その子キャッシュに含まれているノードごとに自身を再帰的に呼び出します。 次に、removeNodeSpi()
を呼び出し、それ自体を削除済みとしてマークし、その親の子キャッシュから削除します。 最後に、ノード変更リスナーがある場合は、イベント・ディスパッチ・スレッドに渡すために通知イベントをキューに入れます。ヘルパー・メソッドが呼び出されるときは、「削除されていないもっとも近い上位ノード」までのすべての上位ノードが常にロックされます。
- 定義:
removeNode
、クラスPreferences
- 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによってすでに削除されている場合。UnsupportedOperationException
- このメソッドがルート・ノード上で呼び出された場合。BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。- 関連項目:
-
name
public String name()Preferences.name()
の仕様に従って、name
メソッドを実装します。この実装は、ノードのコンストラクタに渡された名前だけを返します。
- 定義:
name
、クラスPreferences
- 戻り値:
- この設定ノードの名前(その親を起点とした相対名)。
-
absolutePath
public String absolutePath()Preferences.absolutePath()
の仕様に従って、absolutePath
メソッドを実装します。この実装は、このノードが構築されたときに算出された絶対パス名だけを返します(このノードのコンストラクタに渡された名前と、このノードの上位ノードのコンストラクタに渡された名前に基づいて算出される)。
- 定義:
absolutePath
、クラスPreferences
- 戻り値:
- この設定ノードの絶対パス名。
-
isUserNode
public boolean isUserNode()Preferences.isUserNode()
の仕様に従って、isUserNode
メソッドを実装します。この実装は、このノードのルート・ノード(privateフィールドに格納されている)と
Preferences.userRoot()
から返された値を比較します。 2つのオブジェクト参照が一致する場合は、trueを返します。- 定義:
isUserNode
、クラスPreferences
- 戻り値:
- このプリファレンス・ノードがユーザー・プリファレンス・ツリーにある場合は
true
、システム・プリファレンス・ツリーにある場合はfalse
。
-
addPreferenceChangeListener
public void addPreferenceChangeListener(PreferenceChangeListener pcl) クラスからコピーされた説明:Preferences
指定されたリスナーがこの設定ノードに対する設定変更イベントを受信するように登録します。 設定変更イベントは、設定がこのノードに追加されたとき、設定がこのノードから削除されたとき、または設定に関連付けられている値が変更されたときに生成されます。 (設定変更イベントは、Preferences.removeNode()
メソッドでは生成されません。このメソッドでは、ノード変更イベントが生成されます。 プリファレンス変更イベントは、clear
メソッドによって生成されます。)ノード変更イベントは、登録されたリスナーと同じJVM内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在のJVMの外部で行われた変更に対して、イベントが生成されることがあります。 イベントが生成された時点で、変更が永続的になっていないことがあります。 現在のノードの下位ノードで設定が変更されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。
- 定義:
addPreferenceChangeListener
、クラスPreferences
- パラメータ:
pcl
- 追加する設定変更リスナー。- 関連項目:
-
removePreferenceChangeListener
public void removePreferenceChangeListener(PreferenceChangeListener pcl) クラスからコピーされた説明:Preferences
指定された設定変更リスナーを削除して、設定変更イベントの受信を停止します。- 定義:
removePreferenceChangeListener
、クラスPreferences
- パラメータ:
pcl
- 削除する設定変更リスナー。- 関連項目:
-
addNodeChangeListener
public void addNodeChangeListener(NodeChangeListener ncl) クラスからコピーされた説明:Preferences
指定されたリスナーがこのノードのノード変更イベントを受信するように登録します。 ノード変更イベントは、子ノードがこのノードに追加されたとき、またはこのノードから削除されたときに生成されます。 (1回のPreferences.removeNode()
呼出しによって、複数のノード変更イベントが、削除されたノードをルートとするサブツリー内の各ノードに1つずつ生成されます。)ノード変更イベントは、登録されたリスナーと同じJVM内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在のJVMの外部で行われた変更に対して、イベントが生成されることがあります。 イベントが生成された時点で、変更が持続的になっていないことがあります。 現在のノードの配下にない下位ノードが追加または削除されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。
作成されたノードは、ただちに有効になりません。 これらのノードは、アクセスされたときに暗黙的に作成されます。このため、アクセスされる前に、子ノードがバッキング・ストアに存在するかどうかを実装が判断できない場合があります(たとえば、バッキング・ストアが到達不能な場合や、キャッシュされた情報が最新でない場合など)。 このような状況でのノード変更イベントの生成は、特に定義されていません。
- 定義:
addNodeChangeListener
、クラスPreferences
- パラメータ:
ncl
- 追加するNodeChangeListener
。- 関連項目:
-
removeNodeChangeListener
public void removeNodeChangeListener(NodeChangeListener ncl) クラスからコピーされた説明:Preferences
指定されたNodeChangeListener
を削除して、変更イベントを受信しないようにします。- 定義:
removeNodeChangeListener
、クラスPreferences
- パラメータ:
ncl
- 削除するNodeChangeListener
。- 関連項目:
-
putSpi
指定されたキーと値のペアをこの設定ノードに関連付けます。key
およびvalue
がnull以外で、有効な長さであることが保証されます。 また、このノードが削除されていないことも保証されています。 実装するときに、これらのことを確認する必要はありません。このメソッドが呼び出されるときは、このノードがロックされます。
- パラメータ:
key
- キーvalue
- 値
-
getSpi
このプリファレンス・ノードで指定したキーに関連付けられた値を返します。このキーの関連付けがない場合はnull
を返し、この時点でアソシエーションを判別できません。key
がnullでないことが保証されます。 また、このノードが削除されていないことも保証されています。 このメソッドが呼び出されるときは、このノードがロックされます。このメソッドは、ほとんどの状況で例外をスローしません。 ただし、例外をスローした場合、例外はインターセプトされ、
null
戻り値として処理されます。このメソッドが呼び出されるときは、このノードがロックされます。
- パラメータ:
key
- キー- 戻り値:
- このプリファレンス・ノードで指定したキーに関連付けられた値。このキーにアソシエーションがない場合、またはこの時点でアソシエーションを決定できない場合は
null
。
-
removeSpi
protected abstract void removeSpi(String key) この設定ノードの指定されたキーに関連付けがある場合は、それを削除します。key
がnullでないことが保証されます。 また、このノードが削除されていないことも保証されています。 このメソッドが呼び出されるときは、このノードがロックされます。このメソッドが呼び出されるときは、このノードがロックされます。
- パラメータ:
key
- キー
-
removeNodeSpi
protected abstract void removeNodeSpi() throws BackingStoreExceptionこの設定ノードを削除し、削除したノードに含まれている設定をすべて無効にします。 この呼出しを行うと、名前付きの子の下位ノードがすべて削除されます。つまり、Preferences.removeNode()
メソッドは、ノードの最下位ノードから上位ノード方向にこのメソッドを繰り返し呼び出して、下位ノードをすべて削除してから、ノード自体を削除します。このメソッドが呼び出されるときは、このノードとその親(および1回の
Preferences.removeNode()
の呼出しによって削除されるすべての上位ノード)がロックされます。ノードの削除は、このノード(または祖先)で
flush
メソッドが呼び出されるまで永続化される必要はありません。このノードが
BackingStoreException
をスローすると、例外は囲んでいるremoveNode()
呼出しを超えて伝播されます。- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
-
keysSpi
protected abstract String[] keysSpi() throws BackingStoreExceptionこの設定ノード内に関連付けられている値を持つキーをすべて返します。 このノードに設定がない場合、返される配列のサイズはゼロになります。 このノードが削除されていないことが保証されています。このメソッドが呼び出されるときは、このノードがロックされます。
このノードが
BackingStoreException
をスローすると、例外は囲んでいるkeys()
呼出しを超えて伝播されます。- 戻り値:
- この設定ノード内に関連付けられている値を持つキーの配列。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
-
childrenNamesSpi
protected abstract String[] childrenNamesSpi() throws BackingStoreExceptionこの設定ノードの子の名前を返します。 このノードに子がない場合、返される配列のサイズはゼロになります。 このメソッドでは、キャッシュ済みのノードの名前を返す必要はありませんが、返してもかまいません。このメソッドが呼び出されるときは、このノードがロックされます。
このノードが
BackingStoreException
をスローすると、例外は囲んでいるchildrenNames()
呼出しを超えて伝播されます。- 戻り値:
- 設定ノードの子の名前が含まれている配列。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
-
getChild
protected AbstractPreferences getChild(String nodeName) throws BackingStoreException 指定された子が存在する場合はその子を返し、存在しない場合はnull
を返します。nodeName
が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以外で空でないこと、スラッシュ文字('/')が含まれず、Preferences.MAX_NAME_LENGTH
文字以下であることが保証されます。 また、このノードが削除されていないことも保証されています。 実装するときに、これらのことを確認する必要はありません。また、名前付きノードが最後に削除されたあとで、このメソッドまたは
getChild(String)
が前回呼び出されたときに、そのノードが返されていないことも保証されています。 つまり、このメソッドが呼び出される前に、キャッシュされた値が常に優先して使用されます。 サブクラスは、以前に返された子のキャッシュを保持する必要はありません。実装するときは、返されたノードが削除されていないことを確認する必要があります。 このノードの類似子が以前に削除された場合、実装者は新しく構築された
AbstractPreferences
ノードを返す必要があります。一度削除すると、AbstractPreferences
ノードを"resuscitated."にすることはできませんこのメソッドによってノードが作成される場合、
flush
メソッドがこのノードまたはその祖先(または子孫)のいずれかで起動されるまで、このノードの永続性は保証されません。このメソッドが呼び出されるときは、このノードがロックされます。
- パラメータ:
name
- 返す子ノードの名前(この設定ノードを起点として相対名)。- 戻り値:
- 名前付きの子ノード。
-
toString
public String toString()この設定ノードの絶対パス名を返します。- 定義:
toString
、クラスPreferences
- 戻り値:
- このオブジェクトの文字列表現
-
sync
public void sync() throws BackingStoreExceptionPreferences.sync()
の仕様に従って、sync
メソッドを実装します。再帰的ヘルパー・メソッドは、このノードをロックし、このノード上でsyncSpi()を呼び出します。次に、このノードのロックを解除して、「キャッシュされた子」ごとに再帰的にこのメソッドを呼び出します。 キャッシュされた子とは、このVM内で作成され、その後削除されていないこのノードの子です。 つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとにsyncSpi()を呼び出します。このとき、操作しているノードだけがロックされます。 syncSpi()は上位ノードから下位方向に呼び出されます。
- 定義:
sync
、クラスPreferences
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
-
syncSpi
protected abstract void syncSpi() throws BackingStoreExceptionこのメソッドが呼び出されるときは、このノードがロックされます。 このメソッドの規約では、このノードに格納されているキャッシュされた設定が、バッキング・ストアに格納されている設定と同期されます。 このとき、このノードが別のVMによって削除されたり、まだ作成されていないために、バッキング・ストアに存在しない可能性があります。 このメソッドでは、このノードのサブノードの設定は同期されません。 バッキング・ストアに格納されているサブツリー全体を一度に同期させる場合は、このメソッドをオーバーライドするだけではなく、sync()もオーバーライドすることをお薦めします。このノードが
BackingStoreException
をスローすると、例外は囲んでいるsync()
呼出しを超えて伝播されます。- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
-
flush
public void flush() throws BackingStoreExceptionPreferences.flush()
の仕様に従って、flush
メソッドを実装します。再帰的ヘルパー・メソッドは、このノードをロックし、このノード上でflushSpi()を呼び出します。 キャッシュされた子とは、このVM内で作成され、その後削除されていないこのノードの子です。 つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとにflushSpi()を呼び出します。このとき、操作しているノードだけがロックされます。 flushSpi()は上位ノードから下位方向に呼び出されます。
このメソッドを、
removeNode()
メソッドを使用して削除されたノード上で呼び出すと、flushSpi()がこのノード上で呼び出されますが、ほかのノードでは呼び出されません。- 定義:
flush
、クラスPreferences
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。- 関連項目:
-
flushSpi
protected abstract void flushSpi() throws BackingStoreExceptionこのメソッドが呼び出されるときは、このノードがロックされます。 このメソッドの規約では、キャッシュされた変更をこの設定ノードの内容に強制的に適用してから、それらをバッキング・ストアにフラッシュし、それらの永続性を保証します。 このとき、このノードが別のVMによって削除されたり、まだ作成されていないために、バッキング・ストアに存在しない可能性があります。 このメソッドでは、このノードのサブノードの設定はフラッシュされません。 バッキング・ストアに格納されているサブツリー全体を一度にフラッシュする場合は、このメソッドをオーバーライドするだけではなく、flush()もオーバーライドすることをお薦めします。このノードが
BackingStoreException
をスローすると、例外は囲んでいるflush()
呼出しを超えて伝播されます。- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
-
isRemoved
protected boolean isRemoved()このノード(または祖先)がremoveNode()
メソッドで削除された場合は、true
を返します。 このメソッドは、このノードをロックしてから、この状態の追跡に使用されたprivateフィールドの内容を返します。- 戻り値:
true
iffこのノード(または祖先)は、removeNode()
メソッドで削除されました。
-
exportNode
public void exportNode(OutputStream os) throws IOException, BackingStoreException Preferences.exportNode(OutputStream)
の仕様に従って、exportNode
メソッドを実装します。- 定義:
exportNode
、クラスPreferences
- パラメータ:
os
- XMLドキュメントの発行先の出力ストリーム- 例外:
IOException
- 指定した出力ストリームに書き込むと、IOException
になります。BackingStoreException
- 設定データがバッキング・ストアから読み取れない場合。- 関連項目:
-
exportSubtree
public void exportSubtree(OutputStream os) throws IOException, BackingStoreException Preferences.exportSubtree(OutputStream)
の仕様に従って、exportSubtree
メソッドを実装します。- 定義:
exportSubtree
、クラスPreferences
- パラメータ:
os
- XMLドキュメントの発行先の出力ストリーム- 例外:
IOException
- 指定した出力ストリームに書き込むと、IOException
になります。BackingStoreException
- 設定データがバッキング・ストアから読み取れない場合。- 関連項目:
-