モジュール java.prefs
パッケージ java.util.prefs

クラスAbstractPreferences

java.lang.Object
java.util.prefs.Preferences
java.util.prefs.AbstractPreferences
public abstract class AbstractPreferences extends Preferences
このクラスは、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
関連項目:

  • ﾌｨｰﾙﾄﾞ詳細

    • newNode

      protected boolean newNode
      このオブジェクトを作成する前にこのノードがバッキング・ストアに存在しなかった場合は、このフィールドをtrueにする必要があります。 このフィールドの初期値はfalseですが、サブクラスのコンストラクタによってtrueに設定されます(それ以降は変更しないでください)。 このフィールドには、オブジェクトの作成が完了したときにノード変更イベントをトリガーする必要があるかどうかを指定します。

    • lock

      protected final Object lock
      このオブジェクトには、このノードをロックしたときに使用されるモニターが組み込まれています。 このオブジェクトは、そのノード自体より優先され、ノードがロックされたときに意図的または非意図的にサービスが拒否される可能性を減少します。 デッドロックを回避するために、下位ノードのロックを保持しているスレッドによって上位ノードがロックされることはありません。

  • コンストラクタの詳細

    • AbstractPreferences

      protected AbstractPreferences(AbstractPreferences parent, String name)
      指定された親とその親を起点として相対名を使用して、設定ノードを作成します。
      パラメータ:
      parent - この設定ノードの親。このノードがルートの場合はnull。
      name - このプリファレンス・ノードの名前(親に対する相対名)、またはルートの場合は""。
      例外:
      IllegalArgumentException - nameにスラッシュ('/')が含まれる場合、またはparentがnullで名前が""ではない場合。

  • メソッドの詳細

    • put

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

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

      定義:
      put、クラスPreferences
      パラメータ:
      key - 指定の値が関連付けられるキー。
      value - 指定のキーに関連付けられる値。
      例外:
      NullPointerException - キーまたは値がnullの場合。
      IllegalArgumentException - key.length()がMAX_KEY_LENGTHを超えた場合、またはvalue.lengthがMAX_VALUE_LENGTHを超えた場合。
      IllegalArgumentException - キーまたは値のいずれかにnull制御文字が含まれている場合、コード・ポイントU+0000。
      IllegalStateException - このノード(または上位ノード)がremoveNode()メソッドによって削除されている場合。

    • get

      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に関連付けられた値がない場合に返される値。
      戻り値:
      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 BackingStoreException
      Preferences.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 BackingStoreException
      Preferences.keys()の仕様に従って、keysメソッドを実装します。

      この実装は、この設定ノードのロックを取得し、設定ノードが削除されていないことを確認して、keysSpi()を呼び出します。

      定義:
      keys、クラスPreferences
      戻り値:
      この設定ノード内に関連付けられている値を持つキーの配列。
      例外:
      BackingStoreException - バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
      IllegalStateException - このノード(または上位ノード)がremoveNode()メソッドによって削除されている場合。

    • childrenNames

      public String[] childrenNames() throws BackingStoreException
      Preferences.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 BackingStoreException
      Preferences.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

      protected abstract void putSpi(String key, String value)
      指定されたキーと値のペアをこの設定ノードに関連付けます。 keyおよびvalueがnull以外で、有効な長さであることが保証されます。 また、このノードが削除されていないことも保証されています。 実装するときに、これらのことを確認する必要はありません。

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

      パラメータ:
      key - キー
      value - 値

    • getSpi

      protected abstract String getSpi(String key)
      このプリファレンス・ノードで指定したキーに関連付けられた値を返します。このキーの関連付けがない場合は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 BackingStoreException
      Preferences.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 BackingStoreException
      Preferences.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 - 設定データがバッキング・ストアから読み取れない場合。
      関連項目: