public abstract class AbstractPreferences extends Preferences
Preferences
クラスのスケルトン実装を提供します。このクラスを使用すれば、簡単に実装することができます。
このクラスは、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、およびchildSpi
が例外をスローすべき場合が1つだけあります。ベースとなるオペレーティング・システム上で、要求した操作の実行に必要な特権を呼出し側が持っていない場合です。 たとえば、ほとんどのシステムでは、非特権ユーザーがシステム設定を変更しようとすると例外が発生します。 必要な特権は、実装ごとに異なります。 たとえば、ファイル・システム内のディレクトリの内容を変更する権限が必要な場合や、レジストリ内のキーの内容を変更する権限が必要な場合があります。 こうした環境の場合、プログラムの実行は続行しないでください。続行しても、これらの操作は適用されることがないためです。 このような環境では、できるだけ例外をスローすることをお薦めします。 SecurityException
が適切と考えられます。
ほとんどのSPIメソッドの実装では、設定ノードで情報の読み込みまたは書込みを行う必要があります。 設定ノードは、別のVMによってバッキング・ストアから並行して削除されている場合があります。 このノードが削除されている場合は、実装するユーザーが再作成してください。
実装にあたってのノート:SunのデフォルトのPreferences
実装では、ユーザーIDはベースとなるオペレーティング・システムから継承され、仮想マシンの寿命中に変わることはありません。 サーバー側のPreferences
実装では、要求ごとにユーザーIDが変わることがあり、静的なThreadLocal
インスタンスを使用してPreferences
メソッドに暗黙的に渡されることが認識されています。 そのような実装の作成者は、ユーザーと各Preferences
インスタンスを永続的に関連付けるのではなく、設定にアクセスするときに、たとえばget(String,String)
またはput(String,String)
メソッドなどを使用してユーザーを判断することを強くお薦めします。 ユーザーを永続的に関連付けた場合、Preferences
の正常な使い方に準拠していないため、大きな混乱を招くことになります。
- 導入されたバージョン:
- 1.4
- 関連項目:
Preferences
-
フィールドのサマリー
-
コンストラクタのサマリー
コンストラクタ 修飾子 コンストラクタ 説明 protected
AbstractPreferences(AbstractPreferences parent, String name)
指定された親とその親を起点として相対名を使用して、設定ノードを作成します。 -
メソッドのサマリー
修飾子と型 メソッド 説明 String
absolutePath()
Preferences.absolutePath()
の仕様に従って、absolutePath
メソッドを実装します。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()
メソッドを実装します。protected abstract void
removeNodeSpi()
この設定ノードを削除し、削除したノードに含まれている設定をすべて無効にします。protected abstract void
removeSpi(String key)
この設定ノードの指定されたキーに関連付けがある場合は、それを削除します。void
sync()
Preferences.sync()
の仕様に従って、sync
メソッドを実装します。protected abstract void
syncSpi()
このメソッドが呼び出されるときは、このノードがロックされます。String
toString()
この設定ノードの絶対パス名を返します。クラス java.util.prefs.Preferencesで宣言されたメソッド
addNodeChangeListener, addPreferenceChangeListener, importPreferences, removeNodeChangeListener, removePreferenceChangeListener, 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
でnameが「」でない場合。
-
-
メソッドの詳細
-
put
Preferences.put(String,String)
の仕様に従って、put
メソッドを実装します。この実装では、キーと値が正当であることを確認し、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、
putSpi(String,String)
を呼び出します。また、設定変更リスナーがある場合は、イベント・ディスパッチ・スレッドに渡すために通知イベントをキューに入れます。- 定義:
put
、クラス:Preferences
- パラメータ:
key
- 指定の値が関連付けられるキー。value
- 指定のキーに関連付けられる値。- 例外:
NullPointerException
- keyまたはvalueが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
- keyが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()
メソッドによって削除されている場合。- 関連項目:
Preferences.removeNode()
-
putInt
public void putInt(String key, int value)Preferences.putInt(String,int)
の仕様に従って、putInt
メソッドを実装します。この実装では、
Integer.toString(int)
を使用してvalue
を文字列に変換し、その結果に対してput(String,String)
を呼び出します。- 定義:
putInt
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyがnull
である場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。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
が返されます。- 定義:
getInt
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がintとして返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をintとして解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すint値。関連付けられている値が存在しないか、その値をintとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
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)
を呼び出します。- 定義:
putLong
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyがnull
である場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。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
が返されます。- 定義:
getLong
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がlongとして返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をlongとして解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すlong値。関連付けられている値が存在しないか、その値をlongとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
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)
を呼び出します。- 定義:
putBoolean
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyがnull
である場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。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
が返されます。- 定義:
getBoolean
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がbooleanとして返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をbooleanとして解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すboolean値。関連付けられている値が存在しないか、その値をbooleanとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
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)
を呼び出します。- 定義:
putFloat
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyがnull
である場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。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
が返されます。- 定義:
getFloat
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がfloatとして返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をfloatとして解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すfloat値。関連付けられている値が存在しないか、その値をfloatとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
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)
を呼び出します。- 定義:
putDouble
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyがnull
である場合IllegalArgumentException
-key.length()
がMAX_KEY_LENGTH
を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。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
が返されます。- 定義:
getDouble
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がdoubleとして返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をdoubleとして解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すdouble値。関連付けられている値が存在しないか、その値をdoubleとして解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
Preferences.putDouble(String,double)
,Preferences.get(String,String)
-
putByteArray
public void putByteArray(String key, byte[] value)Preferences.putByteArray(String,byte[])
の仕様に従って、putByteArray
メソッドを実装します。- 定義:
putByteArray
、クラス:Preferences
- パラメータ:
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。- 例外:
NullPointerException
- keyまたはvalueがnull
の場合。IllegalArgumentException
- key.length()がMAX_KEY_LENGTHを超える場合、またはvalue.lengthがMAX_VALUE_LENGTH*3/4を超える場合。IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
Preferences.getByteArray(String,byte[])
,Preferences.get(String,String)
-
getByteArray
public byte[] getByteArray(String key, byte[] def)Preferences.getByteArray(String,byte[])
の仕様に従って、getByteArray
メソッドを実装します。- 定義:
getByteArray
、クラス:Preferences
- パラメータ:
key
- 関連付けられている値がbyte配列として返されるキー。def
- この設定ノードがkey
に関連付けられている値を持たないか、関連付けられている値をバイト配列として解釈できない場合に返すべき値。- 戻り値:
- この設定ノード内の
key
に関連付けられている文字列が表すbyte配列値。関連付けられている値が存在しないか、その値をbyte配列として解釈できない場合はdef
。 - 例外:
IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。NullPointerException
-key
がnull
である場合。 (def
にはnull
値を指定できる。)IllegalArgumentException
- keyにnull制御文字が含まれている場合、コード・ポイントU+0000。- 関連項目:
Preferences.get(String,String)
,Preferences.putByteArray(String,byte[])
-
keys
public String[] keys() throws BackingStoreExceptionPreferences.keys()
の仕様に従って、keys
メソッドを実装します。この実装は、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、
keysSpi()
を呼び出します。- 定義:
keys
、クラス:Preferences
- 戻り値:
- この設定ノード内に関連付けられている値を持つキーの配列。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。
-
childrenNames
public String[] childrenNames() throws BackingStoreExceptionPreferences.childrenNames()
の仕様に従って、children
メソッドを実装します。この実装では、この設定ノードのロックを取得し、そのノードが削除されていないことを確認して、キャッシュ済みの子(このノードの「子キャッシュ」に格納されている子)の名前に初期化されている
TreeSet
を構築し、childrenNamesSpi()
を呼び出し、返されたすべての子の名前をそのセット内に追加します。 ツリー・セットの要素はtoArray
メソッドを使用してString
配列にダンプされ、この配列が返されます。- 定義:
childrenNames
、クラス:Preferences
- 戻り値:
- この設定ノードの子の名前。
- 例外:
BackingStoreException
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード(または上位ノード)がremoveNode()
メソッドによって削除されている場合。- 関連項目:
cachedChildren()
-
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()
メソッドによって削除されている場合。- 関連項目:
Preferences.flush()
-
nodeExists
public boolean nodeExists(String path) throws BackingStoreExceptionPreferences.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
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。- 関連項目:
Preferences.flush()
-
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
を返します。
-
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
ノードは、復旧できません。このメソッドによって作成されたノードは、このノードまたはその上位ノード(または下位ノード)で
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()
メソッドによって削除されている場合。- 関連項目:
flush()
-
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
- バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。- 関連項目:
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, BackingStoreExceptionPreferences.exportNode(OutputStream)
の仕様に従って、exportNode
メソッドを実装します。- 定義:
exportNode
、クラス:Preferences
- パラメータ:
os
- XMLドキュメントの発行先の出力ストリーム- 例外:
IOException
- 指定された出力ストリームへの書込み時にIOException
が発生した場合。BackingStoreException
- 設定データがバッキング・ストアから読み取れない場合。- 関連項目:
Preferences.importPreferences(InputStream)
-
exportSubtree
public void exportSubtree(OutputStream os) throws IOException, BackingStoreExceptionPreferences.exportSubtree(OutputStream)
の仕様に従って、exportSubtree
メソッドを実装します。- 定義:
exportSubtree
、クラス:Preferences
- パラメータ:
os
- XMLドキュメントの発行先の出力ストリーム- 例外:
IOException
- 指定された出力ストリームへの書込み時にIOException
が発生した場合。BackingStoreException
- 設定データがバッキング・ストアから読み取れない場合。- 関連項目:
Preferences.importPreferences(InputStream)
,Preferences.exportNode(OutputStream)
-