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

クラスAbstractPreferences


  • 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

    • フィールドの詳細

      • 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

        public void put​(String key,
                String value)
        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

        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 - 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 BackingStoreException
        Preferences.clear()の仕様に従って、clearメソッドを実装します。

        この実装では、この設定ノードのロックを取得し、keys()を呼び出してキーの配列を取得します。次に、各キーに対しremove(String)を呼び出して、配列を繰り返します。

        定義:
        clear、クラス: Preferences
        例外:
        BackingStoreException - バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
        IllegalStateException - このノード(または上位ノード)がremoveNode()メソッドによって削除されている場合。
        関連項目:
        Preferences.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。
        関連項目:
        Preferences.putInt(String,int), Preferences.get(String,String)

      • 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)

      • 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)

      • 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)

      • 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)

      • 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 BackingStoreException
        Preferences.keys()の仕様に従って、keysメソッドを実装します。

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

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

      • childrenNames

        public String[] childrenNames​()
                       throws BackingStoreException
        Preferences.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 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 - バッキング・ストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合。
        関連項目:
        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を返します。

      • addPreferenceChangeListener

        public void addPreferenceChangeListener​(PreferenceChangeListener pcl)
        クラスからコピーされた説明: Preferences
        指定されたリスナーがこの設定ノードに対する設定変更イベントを受信するように登録します。 設定変更イベントは、設定がこのノードに追加されたとき、設定がこのノードから削除されたとき、または設定に関連付けられている値が変更されたときに生成されます。 (設定変更イベントは、Preferences.removeNode()メソッドでは生成されません。このメソッドでは、ノード変更イベントが生成されます。 設定変更イベントはclearメソッドによって生成されます。

        ノード変更イベントは、登録されたリスナーと同じJVM内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在のJVMの外部で行われた変更に対して、イベントが生成されることがあります。 イベントが生成された時点で、変更が永続的になっていないことがあります。 現在のノードの下位ノードで設定が変更されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。

        定義:
        addPreferenceChangeListener、クラス: Preferences
        パラメータ:
        pcl - 追加する設定変更リスナー。
        関連項目:
        Preferences.removePreferenceChangeListener(PreferenceChangeListener), Preferences.addNodeChangeListener(NodeChangeListener)

      • addNodeChangeListener

        public void addNodeChangeListener​(NodeChangeListener ncl)
        クラスからコピーされた説明: Preferences
        指定されたリスナーがこのノードのノード変更イベントを受信するように登録します。 ノード変更イベントは、子ノードがこのノードに追加されたとき、またはこのノードから削除されたときに生成されます。 (1回のPreferences.removeNode()呼出しによって、複数のノード変更イベントが、削除されたノードをルートとするサブツリー内の各ノードに1つずつ生成されます。)

        ノード変更イベントは、登録されたリスナーと同じJVM内で変更が行われたときにだけ、生成されます。ただし、一部の実装では、現在のJVMの外部で行われた変更に対して、イベントが生成されることがあります。 イベントが生成された時点で、変更が持続的になっていないことがあります。 現在のノードの配下にない下位ノードが追加または削除されたときは、イベントは生成されません。そのようなイベントが必要な場合は、そのノードを登録する必要があります。

        作成されたノードは、ただちに有効になりません。 これらのノードは、アクセスされたときに暗黙的に作成されます。このため、アクセスされる前に、子ノードがバッキング・ストアに存在するかどうかを実装が判断できない場合があります(たとえば、バッキング・ストアが到達不能な場合や、キャッシュされた情報が最新でない場合など)。 このような状況でのノード変更イベントの生成は、特に定義されていません。

        定義:
        addNodeChangeListener、クラス: Preferences
        パラメータ:
        ncl - 追加するNodeChangeListener。
        関連項目:
        Preferences.removeNodeChangeListener(NodeChangeListener), Preferences.addPreferenceChangeListener(PreferenceChangeListener)

      • 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ノードは、復旧できません。

        このメソッドによって作成されたノードは、このノードまたはその上位ノード(または下位ノード)で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()メソッドによって削除されている場合。
        関連項目:
        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()がこのノード上で呼び出されますが、ほかのノードでは呼び出されません。

        定義:
        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。