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 の呼び出しではすべて false を返してください。 true を返したときに、それまでのすべての操作が正常に適用されていることを示すためです。
putSpi、removeSpi、および childSpi が例外をスローすべき場合が 1 つだけあります。ベースとなるオペレーティングシステム上で、要求した操作の実行に必要な特権を呼び出し側が持っていない場合です。たとえば、ほとんどのシステムでは、非特権ユーザーがシステム設定を変更しようとすると例外が発生します。必要な特権は、実装ごとに異なります。たとえば、ファイルシステム内のディレクトリの内容を変更する権限が必要な場合や、レジストリ内のキーの内容を変更する権限が必要な場合があります。こうした環境の場合、プログラムの実行は続行しないでください。続行しても、これらの操作は適用されることがないためです。このような環境では、できるだけ例外をスローすることをお勧めします。SecurityException
が適切と考えられます。
ほとんどの SPI メソッドの実装では、設定ノードで情報の読み込みまたは書き込みを行う必要があります。設定ノードは、別の VM によってバッキングストアから並行して削除されている場合があります。このノードが削除されている場合は、実装するユーザーが再作成してください。
実装にあたっての注意:Sun のデフォルトの Preferences 実装では、ユーザー ID はベースとなるオペレーティングシステムから継承され、仮想マシンの寿命中に変わることはありません。サーバー側の Preferences 実装では、要求ごとにユーザー ID が変わり、静的な ThreadLocal
インスタンスを使用して Preferences メソッドに暗黙的に渡されます。サーバー側の実装の作成者は、設定にアクセスするときに、たとえば get(String,String)
や put(String,String)
メソッドなどを使用してユーザーを判断することを強くお勧めします。できるだけ、ユーザーと各 Preferences インスタンスを永続的に関連付けないでください。ユーザーを永続的に関連付けた場合、Preferences の正常な使い方に準拠していないため、大きな混乱を招くことになります。
Preferences
修飾子と型 | フィールドと説明 |
---|---|
protected Object |
lock
このオブジェクトには、このノードをロックしたときに使用されるモニターが組み込まれています。
|
protected boolean |
newNode
このオブジェクトを作成する前にこのノードがバッキングストアに存在しなかった場合、このフィールドは true にしてください。
|
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()
この設定ノードの絶対パス名を返します。
|
importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot
protected boolean newNode
protected final Object lock
protected AbstractPreferences(AbstractPreferences parent, String name)
parent
- この設定ノードの親。このノードがルートの場合は null。name
- この設定ノードの親に対する相対名。これがルートの場合は「」。IllegalArgumentException
- name にスラッシュ (「/」) が含まれているか、parent が null で name が「」でない場合。public void put(String key, String value)
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 を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。public String get(String key, String def)
Preferences.get(String,String)
の仕様に従って、get メソッドを実装します。
この実装はまず、key が null かどうかをチェックし、そうである場合は NullPointerException をスローします。次に、この設定ノードのロックを取得し、そのノードが削除されていないことを確認して、getSpi(String)
を呼び出します。 getSpi の呼び出しが正常終了した場合は、その結果を返します。 null が返されるか例外がスローされた場合は、def を返します。
get
、クラス: Preferences
key
- 関連付けられている値が返されるキー。def
- この設定ノードが key に関連付けられている値を持たない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- キーが null である場合。(null デフォルトは許可される。)public void remove(String key)
Preferences.remove(String)
の仕様に従って、remove(String) メソッドを実装します。
この実装では、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、removeSpi(String)
を呼び出します。また、設定変更リスナーがある場合は、イベントディスパッチスレッドに渡すために通知イベントをキューに入れます。
remove
、クラス: Preferences
key
- マッピングが設定ノードから削除されるキー。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。public void clear() throws BackingStoreException
Preferences.clear()
の仕様に従って、clear メソッドを実装します。
この実装では、この設定ノードのロックを取得し、keys()
を呼び出してキーの配列を取得します。次に、各キーに対し remove(String)
を呼び出して、配列を繰り返します。
clear
、クラス: Preferences
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.removeNode()
public void putInt(String key, int value)
Preferences.putInt(String,int)
の仕様に従って、putInt メソッドを実装します。
この実装では、Integer.toString(int)
を使用して value を文字列に変換し、その結果に対して put(String,String)
を呼び出します。
putInt
、クラス: Preferences
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。NullPointerException
- キーが null である場合。IllegalArgumentException
- key.length() が MAX_KEY_LENGTH を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getInt(String,int)
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 として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。Preferences.putInt(String,int)
, Preferences.get(String,String)
public void putLong(String key, long value)
Preferences.putLong(String,long)
の仕様に従って、putLong メソッドを実装します。
この実装では、Long.toString(long)
を使用して value を文字列に変換し、その結果に対して put(String,String)
を呼び出します。
putLong
、クラス: Preferences
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。NullPointerException
- キーが null である場合。IllegalArgumentException
- key.length() が MAX_KEY_LENGTH を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getLong(String,long)
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 として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。Preferences.putLong(String,long)
, Preferences.get(String,String)
public void putBoolean(String key, boolean value)
Preferences.putBoolean(String,boolean)
の仕様に従って、putBoolean メソッドを実装します。
この実装では、String.valueOf(boolean)
を使用して value を文字列に変換し、その結果に対して put(String,String)
を呼び出します。
putBoolean
、クラス: Preferences
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。NullPointerException
- キーが null である場合。IllegalArgumentException
- key.length() が MAX_KEY_LENGTH を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getBoolean(String,boolean)
, Preferences.get(String,String)
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 として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。Preferences.get(String,String)
, Preferences.putBoolean(String,boolean)
public void putFloat(String key, float value)
Preferences.putFloat(String,float)
の仕様に従って、putFloat メソッドを実装します。
この実装では、Float.toString(float)
を使用して value を文字列に変換し、その結果に対して put(String,String)
を呼び出します。
putFloat
、クラス: Preferences
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。NullPointerException
- キーが null である場合。IllegalArgumentException
- key.length() が MAX_KEY_LENGTH を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getFloat(String,float)
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 として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。Preferences.putFloat(String,float)
, Preferences.get(String,String)
public void putDouble(String key, double value)
Preferences.putDouble(String,double)
の仕様に従って、putDouble メソッドを実装します。
この実装では、Double.toString(double)
を使用して value を文字列に変換し、その結果に対して put(String,String)
を呼び出します。
putDouble
、クラス: Preferences
key
- 文字列形式の値が関連付けられるキー。value
- キーに関連付けられる文字列形式の値。NullPointerException
- キーが null である場合。IllegalArgumentException
- key.length() が MAX_KEY_LENGTH を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getDouble(String,double)
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 として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。Preferences.putDouble(String,double)
, Preferences.get(String,String)
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 を超える場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。Preferences.getByteArray(String,byte[])
, Preferences.get(String,String)
public byte[] getByteArray(String key, byte[] def)
Preferences.getByteArray(String,byte[])
の仕様に従って、getByteArray メソッドを実装します。getByteArray
、クラス: Preferences
key
- 関連付けられている値が byte 配列として返されるキー。def
- この設定ノードが key に関連付けられている値を持たないか、関連付けられている値をバイト配列として解釈できない場合に返すべき値。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。NullPointerException
- key が null である場合。(def には null 値を指定できる。)Preferences.get(String,String)
, Preferences.putByteArray(String,byte[])
public String[] keys() throws BackingStoreException
Preferences.keys()
の仕様に従って、keys メソッドを実装します。
この実装は、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、keysSpi()
を呼び出します。
keys
、クラス: Preferences
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。public String[] childrenNames() throws BackingStoreException
Preferences.childrenNames()
の仕様に従って、children メソッドを実装します。
この実装では、この設定ノードのロックを取得し、そのノードが削除されていないことを確認して、キャッシュ済みの子 (このノードの「子キャッシュ」に格納されている子) の名前に初期化されている TreeSet を構築し、childrenNamesSpi()
を呼び出し、返されたすべての子の名前をそのセット内に追加します。ツリーセットの要素は toArray メソッドを使用して String 配列にダンプされ、この配列が返されます。
childrenNames
、クラス: Preferences
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。cachedChildren()
protected final AbstractPreferences[] cachedChildren()
public Preferences parent()
Preferences.parent()
の仕様に従って、parent メソッドを実装します。
この実装では、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、このノードのコンストラクタに渡された親の値を返します。
parent
、クラス: Preferences
IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。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()
public boolean nodeExists(String path) throws BackingStoreException
Preferences.nodeExists(String)
の仕様に従って、nodeExists メソッドを実装します。
この実装は、childSpi(String)
の代わりに、getChild(String)
が使用されることを除き、node(String)
とよく似ています。
nodeExists
、クラス: Preferences
path
- 存在が確認されるノードのパス名。BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalArgumentException
- パス名が無効である場合 (つまり、パス名に連続した複数のスラッシュ文字が含まれているか、パス名がスラッシュ文字で終わっていてその長さが 2 文字以上の場合)。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されており、pathName が空の文字列 (「」) でない場合。public void removeNode() throws BackingStoreException
Preferences.removeNode()
の仕様に従って、removeNode() メソッドを実装します。
この実装は、このノードがルートであるかどうかを確認します。ルートである場合は、該当する例外をスローします。次に、このノードの親をロックし、このノードをルートとしたサブツリーをトラバースする再帰的ヘルパーメソッドを呼び出します。この再帰的メソッドは、その呼び出し元のノードをロックし、そのノードが削除されていないことを確認したあとで、そのノードの子がすべてキャッシュされていることを確認します。つまり、childrenNamesSpi()
メソッドを呼び出し、返された子の名前が子キャッシュに格納されているかどうかを確認します。子がキャッシュされていない場合は、childSpi(String)
メソッドを呼び出して Preferences インスタンスを作成し、子キャッシュに格納します。このヘルパーメソッドは、その子キャッシュに含まれているノードごとに自身を再帰的に呼び出します。次に、removeNodeSpi()
を呼び出し、そのノード自体を削除済みとして指定し、その親の子キャッシュから削除します。最後に、ノード変更リスナーがある場合は、イベントディスパッチスレッドに渡すために通知イベントをキューに入れます。
ヘルパーメソッドが呼び出されるときは、「削除されていないもっとも近い上位ノード」までのすべての上位ノードが常にロックされます。
removeNode
、クラス: Preferences
IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによってすでに削除されている場合。UnsupportedOperationException
- このメソッドがルートノード上で呼び出された場合。BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。Preferences.flush()
public String name()
Preferences.name()
の仕様に従って、name メソッドを実装します。
この実装は、ノードのコンストラクタに渡された名前だけを返します。
name
、クラス: Preferences
public String absolutePath()
Preferences.absolutePath()
の仕様に従って、absolutePath メソッドを実装します。
この実装は、このノードが構築されたときに算出された絶対パス名だけを返します (このノードのコンストラクタに渡された名前と、このノードの上位ノードのコンストラクタに渡された名前に基づいて算出される)。
absolutePath
、クラス: Preferences
public boolean isUserNode()
Preferences.isUserNode()
の仕様に従って、isUserNode メソッドを実装します。
この実装は、このノードのルートノード (private フィールドに格納されている) と Preferences.userRoot()
から返された値を比較します。2 つのオブジェクト参照が一致する場合は、true を返します。
isUserNode
、クラス: Preferences
public void addPreferenceChangeListener(PreferenceChangeListener pcl)
Preferences
Preferences.removeNode()
メソッドでは生成されません。このメソッドでは、ノード変更イベントが生成されます。設定変更イベントは clear メソッドによって生成されます。
ノード変更イベントは、登録されたリスナーと同じ JVM 内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在の JVM の外部で行われた変更に対して、イベントが生成されることがあります。イベントが生成された時点で、変更が永続的になっていないことがあります。現在のノードの下位ノードで設定が変更されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。
addPreferenceChangeListener
、クラス: Preferences
pcl
- 追加する設定変更リスナー。Preferences.removePreferenceChangeListener(PreferenceChangeListener)
, Preferences.addNodeChangeListener(NodeChangeListener)
public void removePreferenceChangeListener(PreferenceChangeListener pcl)
Preferences
removePreferenceChangeListener
、クラス: Preferences
pcl
- 削除する設定変更リスナー。Preferences.addPreferenceChangeListener(PreferenceChangeListener)
public void addNodeChangeListener(NodeChangeListener ncl)
Preferences
Preferences.removeNode()
呼び出しによって、複数のノード変更イベントが生成されます。つまり、削除されたノードをルートとするサブツリー内の各ノードに 1 つずつ生成されます。
ノード変更イベントは、登録されたリスナーと同じ JVM 内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在の JVM の外部で行われた変更に対して、イベントが生成されることがあります。イベントが生成された時点で、変更が持続的になっていないことがあります。現在のノードの配下にない下位ノードが追加または削除されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。
作成されたノードは、ただちに有効になりません。これらのノードは、アクセスされたときに暗黙的に作成されます。このため、アクセスされる前に、子ノードがバッキングストアに存在するかどうかを実装が判断できない場合があります (たとえば、バッキングストアが到達不能な場合や、キャッシュされた情報が最新でない場合など)。このような状況でのノード変更イベントの生成は、特に定義されていません。
addNodeChangeListener
、クラス: Preferences
ncl
- 追加する NodeChangeListener。Preferences.removeNodeChangeListener(NodeChangeListener)
, Preferences.addPreferenceChangeListener(PreferenceChangeListener)
public void removeNodeChangeListener(NodeChangeListener ncl)
Preferences
removeNodeChangeListener
、クラス: Preferences
ncl
- 削除する NodeChangeListener。Preferences.addNodeChangeListener(NodeChangeListener)
protected abstract void putSpi(String key, String value)
このメソッドが呼び出されるときは、このノードがロックされます。
protected abstract String getSpi(String key)
このメソッドは、ほとんどの状況で例外をスローしません。例外をスローした場合でも、その例外は捕獲され、null 戻り値として扱われます。
このメソッドが呼び出されるときは、このノードがロックされます。
protected abstract void removeSpi(String key)
このメソッドが呼び出されるときは、このノードがロックされます。
protected abstract void removeNodeSpi() throws BackingStoreException
Preferences.removeNode()
メソッドは、ノードの最下位ノードから上位ノード方向にこのメソッドを繰り返し呼び出して、下位ノードをすべて削除してから、ノード自体を削除します。
このメソッドが呼び出されるときは、このノードとその親 (および 1 回の Preferences.removeNode()
の呼び出しによって削除されるすべての上位ノード) がロックされます。
ノードの削除は、このノード (または上位ノード) 上で flush メソッドが呼び出されるまで、永続的となる必要はありません。
このノードがスローした BackingStoreException 例外は、内包している removeNode()
の呼び出しを超えて送られます。
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。protected abstract String[] keysSpi() throws BackingStoreException
このメソッドが呼び出されるときは、このノードがロックされます。
このノードがスローした BackingStoreException 例外は、内包している keys()
の呼び出しを超えて送られます。
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。protected abstract String[] childrenNamesSpi() throws BackingStoreException
このメソッドが呼び出されるときは、このノードがロックされます。
このノードがスローした BackingStoreException 例外は、内包している childrenNames()
の呼び出しを超えて送られます。
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。protected AbstractPreferences getChild(String nodeName) throws BackingStoreException
Preferences.MAX_NAME_LENGTH
文字以下であることが保証されています。また、このノードが削除されていないことも保証されています。このメソッドをオーバーライドするときに、これらのことを確認する必要はありません。
また、名前付きノードが最後に削除されたあとで、このメソッドまたは childSpi(java.lang.String)
が前回呼び出されたときに、そのノードが返されていないことも保証されています。つまり、このメソッドが呼び出される前に、キャッシュされた値が常に優先して使用されます。このメソッドをオーバーライドする場合、以前に返された子のキャッシュを保持する必要はありません。
この実装は、この設定ノードのロックを取得し、childrenNames()
を呼び出して子の名前の配列を取得し、配列内の子ノードの名前と指定されたノード名とを繰り返し比較します。子ノードの名前が正しい場合は、childSpi(String)
メソッドを呼び出し、結果のノードを返します。すべての子ノードを比較しても指定された名前が見つからなかった場合は、null が返されます。
nodeName
- 検索対象となる子の名前。BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。protected abstract AbstractPreferences childSpi(String name)
Preferences.MAX_NAME_LENGTH
文字以下であることが保証されています。また、このノードが削除されていないことも保証されています。実装するときに、これらのことを確認する必要はありません。
また、名前付きノードが最後に削除されたあとで、このメソッドまたは getChild(String)
が前回呼び出されたときに、そのノードが返されていないことも保証されています。つまり、このメソッドが呼び出される前に、キャッシュされた値が常に優先して使用されます。サブクラスは、以前に返された子のキャッシュを保持する必要はありません。
実装するときは、返されたノードが削除されていないことを確認する必要があります。このノードから同じ名前の子が削除されている場合は、AbstractPreferences ノードを新しく構築して、それを返す必要があります。一度削除した AbstractPreferences ノードは、復旧できません。
このメソッドによって作成されたノードは、このノードまたはその上位ノード (または下位ノード) で flush メソッドが呼び出されたときに、永続的になります。
このメソッドが呼び出されるときは、このノードがロックされます。
name
- 返す子ノードの名前 (この設定ノードを起点として相対名)。public String toString()
toString
、クラス: Preferences
public void sync() throws BackingStoreException
Preferences.sync()
の仕様に従って、sync メソッドを実装します。
再帰的ヘルパーメソッドは、このノードをロックし、このノード上で syncSpi() を呼び出します。次に、このノードのロックを解除して、「キャッシュされた子」ごとに再帰的にこのメソッドを呼び出します。キャッシュされた子とは、この VM 内で作成され、その後削除されていないこのノードの子です。つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとに syncSpi() を呼び出します。このとき、操作しているノードだけがロックされます。syncSpi() は上位ノードから下位方向に呼び出されます。
sync
、クラス: Preferences
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。IllegalStateException
- このノード (または上位ノード) が removeNode()
メソッドによって削除されている場合。flush()
protected abstract void syncSpi() throws BackingStoreException
このノードがスローした BackingStoreException 例外は、内包している sync()
の呼び出しを超えて送られます。
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。public void flush() throws BackingStoreException
Preferences.flush()
の仕様に従って、flush メソッドを実装します。
再帰的ヘルパーメソッドは、このノードをロックし、このノード上で flushSpi() を呼び出します。キャッシュされた子とは、この VM 内で作成され、その後削除されていないこのノードの子です。つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとに flushSpi() を呼び出します。このとき、操作しているノードだけがロックされます。flushSpi() は上位ノードから下位方向に呼び出されます。
このメソッドを、removeNode()
メソッドを使用して削除されたノード上で呼び出すと、flushSpi() がこのノード上で呼び出されますが、ほかのノードでは呼び出されません。
flush
、クラス: Preferences
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。flush()
protected abstract void flushSpi() throws BackingStoreException
このノードがスローした BackingStoreException 例外は、内包している flush()
の呼び出しを超えて送られます。
BackingStoreException
- バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。protected boolean isRemoved()
removeNode()
メソッドによって削除された場合に、true を返します。このメソッドは、このノードをロックしてから、この状態の追跡に使用された private フィールドの内容を返します。removeNode()
メソッドによって削除された場合、true。public void exportNode(OutputStream os) throws IOException, BackingStoreException
Preferences.exportNode(OutputStream)
の仕様に従って、exportNode メソッドを実装します。exportNode
、クラス: Preferences
os
- XML ドキュメントの発行先の出力ストリーム。IOException
- 指定された出力ストリームへの書き込み時に IOException が発生した場合。BackingStoreException
- 設定データがバッキングストアから読み取れない場合。Preferences.importPreferences(InputStream)
public void exportSubtree(OutputStream os) throws IOException, BackingStoreException
Preferences.exportSubtree(OutputStream)
の仕様に従って、exportSubtree メソッドを実装します。exportSubtree
、クラス: Preferences
os
- XML ドキュメントの発行先の出力ストリーム。IOException
- 指定された出力ストリームへの書き込み時に IOException が発生した場合。BackingStoreException
- 設定データがバッキングストアから読み取れない場合。Preferences.importPreferences(InputStream)
, Preferences.exportNode(OutputStream)
バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.