JavaTM 2 Platform
Standard Ed. 5.0

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 の文書を参照してください。

Preferences を実装するときは、getSpi(String)putSpi(String,String)removeSpi(String)childSpi(String)removeNodeSpi()keysSpi()childrenNamesSpi()syncSpi()、および flushSpi() の 9 つの abstract サービスプロバイダインタフェース (SPI) メソッドをオーバーライドする必要があります。オーバーライドする具象メソッドには、これらの SPI メソッド上に実装する方法を正確に指定する必要があります。パフォーマンスなどの理由でデフォルトの実装に変更を加えたい場合は、任意の具象メソッドをオーバーライドします。

SPI メソッドは、例外処理について 3 つのグループに分類されます。getSpi メソッドは、例外をスローしません。これは問題ではなく、このメソッドがスローする例外はすべて get(String,String) によって捕獲され、指定されたデフォルト値が呼び出し側に返されます。removeNodeSpikeysSpichildrenNamesSpisyncSpi、および flushSpi メソッドは、BackingStoreException をスローするように指定されています。Preferences の実装は、操作を実行できない場合にこのチェック済み例外をスローする必要があります。スローされた例外は外部に送られ、対応する API メソッドが失敗します。

残りの SPI メソッド (putSpi(String,String)removeSpi(String)、および childSpi(String)) は、より複雑な例外処理を行います。これらのメソッドは通常、バッキングストアが利用できない場合でもその規約に従って動作できるため、BackingStoreException をスローするように指定されていません。これらのメソッドは、{Preferences#flush()} または {Preferences#sync()} が次に呼び出されたときに、情報を返し、効果が適用されるためです。一般に、これらの SPI メソッドは例外をスローしません。一部の実装では、これらの呼び出しが要求した操作を、あとで処理するためにキューに入れることができない場合があります。こうした場合でも、通常は例外をスローせずに、呼び出しや戻り値を無視してください。ただし、後続の flush()sync の呼び出しでは false を返す必要があります。true を返したときに、それまでのすべての操作が正常に適用されていることを示すためです。

putSpiremoveSpi、および childSpi が例外をスローする必要がある場合が 1 つだけあります。基本となるオペレーティングシステム上で、要求した操作の実行に必要な権限を呼び出し側が持っていない場合です。たとえば、ほとんどのシステムでは、非特権ユーザがシステム設定を変更しようとすると例外が発生します。必要な権限は、実装ごとに異なります。たとえば、ファイルシステム内のディレクトリの内容を変更する権限が必要な場合や、レジストリ内のキーの内容を変更する権限が必要な場合があります。こうした環境の場合、プログラムの実行は続行しないでください。続行しても、これらの操作は適用されることがないためです。このような環境では、できるだけ例外をスローすることをお勧めします。その場合、SecurityException をスローしてください。

ほとんどの SPI メソッドの実装では、設定ノードで情報の読み込みまたは書き込みを行う必要があります。設定ノードは、別の VM によってバッキングストアから並行して削除されている場合があります。このノードが削除されている場合は、実装するユーザが再作成してください。

実装上の注意: Sun のデフォルトの Preferences 実装では、ユーザ ID は基本となるオペレーティングシステムから継承され、仮想マシンの寿命中に変わることはありません。サーバ側の Preferences 実装では、要求ごとにユーザ ID が変わり、静的な 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)
          この設定ノードの指定されたキーに関連付けられた値を返します。
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 にスラッシュ ('/') が含まれている場合、または parentnullname"" 以外の場合
メソッドの詳細

put

public void put(String key,
                String value)
Preferences.put(String,String) の仕様に従って、put メソッドを実装します。

この実装では、キーと値が正当であることを確認し、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、putSpi(String,String) を呼び出します。また、設定変更リスナーがある場合は、イベントディスパッチスレッドに渡すために通知イベントをキューに入れます。

定義:
クラス Preferences 内の put
パラメータ:
key - 指定される値が関連付けられるキー
value - 指定されるキーに関連付けられる値
例外:
NullPointerException - キーまたは値が null の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合または value.lengthMAX_VALUE_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合

get

public String get(String key,
                  String def)
Preferences.get(String,String) の仕様に従って、get メソッドを実装します。

この実装では、まず keynull であるかどうかを確認して、null の場合は NullPointerException をスローします。次に、この設定ノードのロックを取得し、そのノードが削除されていないことを確認して、getSpi(String) を呼び出します。getSpi の呼び出しが正常終了した場合は、その結果を返します。null が返されるか例外がスローされた場合は、def を返します。

定義:
クラス Preferences 内の get
パラメータ:
key - 関連付けられた値が返されるキー
def - この設定ノードの key に関連付けられた値がない場合に返される値
戻り値:
key に関連付けられた値。key に関連付けられる値がない場合は def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - キーが 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 - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーが 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 - keynull の場合
関連項目:
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 - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーが 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 - keynull の場合
関連項目:
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 - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーが 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 - keynull の場合
関連項目:
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 - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーが 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 - keynull の場合
関連項目:
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 - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーが 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 - keynull の場合
関連項目:
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 - キーに関連付けられる文字列形式の値
例外:
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)

getByteArray

public byte[] getByteArray(String key,
                           byte[] def)
Preferences.getByteArray(String,byte[]) の仕様に従って、getByteArray メソッドを実装します。

定義:
クラス Preferences 内の getByteArray
パラメータ:
key - 関連付けられた値が byte 配列として返されるキー
def - この設定ノードの key に関連付けられる値がない場合または関連付けられた値が byte 配列とみなされない場合に返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す byte 配列値。関連付けられた値が存在しない場合または byte 配列とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合 (def には null 値を指定できる)
関連項目:
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() を呼び出し、返された子の名前をすべてそのツリーセットに追加します。ツリーセットの要素は toArray メソッドを使用して 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 から最後に返された値を返します。トラバース時に 2 つの "/" が連続して発生した場合、または最後のトークンが名前ではなく "/" の場合は、適切な IllegalArgumentException をスローします。

path の最初の文字が '/' (絶対パス名を示す) の場合は、この設定ノードのロックを解除してから、path をいくつかのトークンに分割し、パスをルートから (このノードからではなく) 再帰的にトラバースします。最初の文字が '/' 以外の場合は、相対パス名と同じトラバースを行います。ルートノードでトラバースを開始するときは、このノードのロックを必ず解除してください。デッドロックの発生を防ぐためです (locking invariant を参照)。

定義:
クラス Preferences 内の node
パラメータ:
path - 返される設定ノードのパス名
戻り値:
指定された設定ノード
例外:
IllegalArgumentException - パス名が無効の場合 (連続した複数のスラッシュ文字が含まれている場合、または複数の文字長のパスがスラッシュ文字で終わっている場合)
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
Preferences.flush()

nodeExists

public boolean nodeExists(String path)
                   throws BackingStoreException
Preferences.nodeExists(String) の仕様に従って、nodeExists メソッドを実装します。

この実装は、node(String) と似ていますが、childSpi(String) ではなく getChild(String) が使用されます。

定義:
クラス Preferences 内の nodeExists
パラメータ:
path - 存在が確認されるノードのパス名
戻り値:
指定されたノードが存在する場合に true
例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalArgumentException - パス名が無効の場合 (連続した複数のスラッシュ文字が含まれている場合、または複数の文字長のパスがスラッシュ文字で終わっている場合)
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() から返される値とを比較します。2 つのオブジェクト参照が一致する場合は、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 の記述:
指定されたリスナーがこのノードの「ノード変更イベント」を受信するように登録します。ノード変更イベントは、子ノードがこのノードに追加されたとき、またはこのノードから削除されたときに生成されます。1 回の Preferences.removeNode() 呼び出しによって、複数の「ノード変更イベント」が生成されます。つまり、削除されたノードをルートとするサブツリー内の各ノードに 1 つずつ生成されます。

ノード変更イベントは、登録されたリスナーと同じ 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)
指定されたキーと値のペアをこの設定ノードに関連付けます。keyvalue が null 以外で、正当な長さであることが保証されています。また、このノードが削除されていないことも保証されています。実装するときに、これらのことを確認する必要はありません。

このメソッドが呼び出されるときは、このノードがロックされます。


getSpi

protected abstract String getSpi(String key)
この設定ノードの指定されたキーに関連付けられた値を返します。このキーに関連付けがない場合、または返すときに関連付けを判断できない場合は、null を返します。key が null 以外であることが保証されています。また、このノードが削除されていないことも保証されています。実装するときに、これらのことを確認する必要はありません。

このメソッドは、ほとんどの状況で例外をスローしません。例外をスローした場合でも、その例外は捕獲され、null 戻り値として扱われます。

このメソッドが呼び出されるときは、このノードがロックされます。

戻り値:
この設定ノードの指定されたキーに関連付けられた値。このキーに関連付けがない場合、または返すときに関連付けを判断できない場合は null

removeSpi

protected abstract void removeSpi(String key)
この設定ノードの指定されたキーに関連付けがある場合は、それを削除します。key が null 以外であることが保証されています。また、このノードが削除されていないことも保証されています。実装するときに、これらのことを確認する必要はありません。

このメソッドが呼び出されるときは、このノードがロックされます。


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()
この設定ノードの絶対パス名を返します。

定義:
クラス Preferences 内の toString
戻り値:
このオブジェクトの文字列表現

sync

public void sync()
          throws BackingStoreException
Preferences.sync() の仕様に従って、sync メソッドを実装します。

この実装は、再帰的ヘルパーメソッドを呼び出します。再帰的ヘルパーメソッドは、このノードをロックし、このノード上で syncSpi() を呼び出します。次に、このノードのロックを解除して、「キャッシュされた子」ごとに再帰的にこのメソッドを呼び出します。キャッシュされた子とは、この VM 内で作成され、その後削除されていないこのノードの子です。つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとに 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 内で作成され、その後削除されていないこのノードの子です。つまり、このメソッドは、このノードをルートとする「キャッシュされたサブツリー」の深さ優先トラバースを実行し、サブツリー内のノードごとに 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)

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。