JavaTM 2 Platform
Standard Ed. 5.0

java.util.prefs
クラス Preferences

java.lang.Object
  上位を拡張 java.util.prefs.Preferences
直系の既知のサブクラス:
AbstractPreferences

public abstract class Preferences
extends Object

設定データの階層的な集合の中の 1 つのノードです。このクラスを使用して、アプリケーションからユーザおよびシステムの設定データと構成データを格納および取得できます。このデータは、実装に依存したバッキングストアに永続的に格納されます。たとえば、フラットファイル、OS 固有のレジストリ、ディレクトリサーバ、SQL データベースなどのバッキングストアに格納されます。このクラスを使用するときに、バッキングストアの詳細を把握している必要はありません。

ユーザ設定ツリーとシステム設定ツリーの、2 つの独立した設定ノードのツリーがあります。それぞれのユーザは個々のユーザ設定ツリーを持ち、そのシステムのすべてのユーザはシステム設計ツリーを持ちます。ユーザ設定ツリーとシステム設定ツリーの定義は、実装ごとに異なります。ユーザ設定ツリーには、フォント選択、カラー選択、特定のアプリケーションに設定したウィンドウ位置やサイズなどが格納されます。システム設定ツリーには、アプリケーションのインストール構成データなどが格納されます。

設定ツリー内のノードには、階層ファイルシステムのディレクトリと同じ方法で名前が付けられます。設定ツリーの各ノードには、「ノード名 (一意である必要はない)」、一意の「絶対パス名」、および各上位ノード (そのノード自体を含む) を起点とした相対パス名が割り当てられます。

ルートノードのノード名は、空の文字列 ("") です。ほかのノードの名前は、作成時に任意に指定できます。ノード名には任意の文字を使用できますが、空の文字列は指定できず、スラッシュ文字 ('/') は使用できません。

ルートノードの絶対パス名は、"/" です。ルートノードの子の絶対パス名は、"/" + <ノード名> になります。その他のノードの絶対パス名は、<親の絶対パス名> + "/" + <ノード名> になります。絶対パス名は、常にスラッシュ文字から始まります。

ノード n の相対パス名は、上位ノード a を起点とした場合、n の絶対パス名を作成するときに a の絶対パス名に追加される文字列になります。先頭にスラッシュ文字がある場合は、削除します。次の点に注意してください。

次の点にも注意してください。

設定データを変更するメソッドはすべて、非同期に実行できます。つまり、実行後はただちに復帰し、変更は実装に依存した遅延が経過してから持続バッキングストアに送られます。flush メソッドは、更新データをバッキングストアに強制的に書き込んで、同期をとるときに使用します。Java 仮想マシンが正常終了しても、保留中の更新は失われません。このため、終了時に明示的に flush を呼び出して、保留中の更新を保持する必要はありません。

Preferences オブジェクトから設定を読み込むときは、デフォルト値を指定してメソッドを呼び出す必要があります。読み込む前に値が設定されていなかった場合またはバッキングストアが利用できない場合は、そのデフォルト値が返されます。これは、バッキングストアが利用できなくなった場合でも、アプリケーションが動作できるようにするためです (ただし、機能がわずかに低下する)。一部のメソッド (flush など) のセマンティクスでは、バッキングストアが利用できない場合にアプリケーションが動作しなくなります。通常のアプリケーションでは、これらのメソッドを呼び出す必要がありません。これらのメソッドは、BackingStoreException のスローを宣言しているアプリケーションで使用します。

このクラスのメソッドは、1 つの JVM の複数のスレッドから同時に呼び出すことができます。このとき、外部的に同期化する必要はありません。実行結果は、逐次実行した場合と等価です。複数の JVM でこのクラスを同時に使用し、同じバッキングストアに設定データを格納した場合、データストアは破壊されませんが、設定データの整合性は保証されません。

このクラスには、エクスポート/インポート機能があり、設定を XML ドキュメントに「エクスポート」したり、設定が記述された XML ドキュメントをシステムに「インポート」することができます。この機能は、設定ツリーのすべてまたは一部をバックアップし、そのバックアップを復元するときに使用します。

この XML ドキュメントでは、次の DOCTYPE が宣言されます。


 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 
設定をエクスポート/インポートするときに、システム URI (http://java.sun.com/dtd/preferences.dtd) にはアクセスしません。システム URI は、DTD を一意に識別する文字列として使用されます。その内容は次のとおりです。

    <?xml version="1.0" encoding="UTF-8"?>

    <!-- DTD for a Preferences tree. -->

    <!-- The preferences element is at the root of an XML document
         representing a Preferences tree. -->
    <!ELEMENT preferences (root)>
  
    <!-- The preferences element contains an optional version attribute,
          which specifies version of DTD. -->
    <!ATTLIST preferences EXTERNAL_XML_VERSION CDATA "0.0" >  

    <!-- The root element has a map representing the root's preferences
         (if any), and one node for each child of the root (if any). -->
    <!ELEMENT root (map, node*) >

    <!-- Additionally, the root contains a type attribute, which
         specifies whether it's the system or user root. -->
    <!ATTLIST root
              type (system|user) #REQUIRED >

    <!-- Each node has a map representing its preferences (if any),
         and one node for each child (if any). -->
    <!ELEMENT node (map, node*) >

    <!-- Additionally, each node has a name attribute -->
    <!ATTLIST node
              name CDATA #REQUIRED >

    <!-- A map represents the preferences stored at a node (if any). -->
    <!ELEMENT map (entry*) >

    <!-- An entry represents a single preference, which is simply
          a key-value pair. -->
    <!ELEMENT entry EMPTY >
    <!ATTLIST entry
              key   CDATA #REQUIRED
              value CDATA #REQUIRED >
 
Preferences 実装には、PreferencesFactory 実装を関連付ける必要があります。ルート設定ノードを生成するときに PreferencesFactory 実装を指定するには、J2SE 実装にその方法を設定する必要があります。これによって、管理者はデフォルトの preferences 実装を代替実装に置き換えることができます。

実装上の注意: Sun の JRE では、PreferencesFactory の実装は次のように実施されます。

  1. システムプロパティ java.util.prefs.PreferencesFactory が定義されている場合、これがクラスを実装する PreferencesFactory インタフェースの完全修飾名と見なされます。クラスがロードされ、そのインスタンスが作成されます。この処理に失敗した場合、詳細不明エラーがスローされます。

  2. システムクラスローダの認識する jar ファイルに PreferencesFactory 実装クラスファイルがインストールされていて、この jar ファイルにリソースディレクトリ META-INF/services 内のプロバイダ構成ファイル java.util.prefs.PreferencesFactory が含まれている場合、このファイルに指定されている最初のクラス名が使用されます。このような jar ファイルが 2 つ以上指定された場合は、最初に検出されたファイルが使用されます。その後、クラスがロードされ、インスタンスが作成されます。この処理に失敗した場合は、詳細不明エラーがスローされます。

  3. 最後に、前述のシステムプロパティと拡張 jar ファイルのどちらも指定されていない場合は、そのとき使用されているプラットフォームに対してシステムワイドのデフォルトである PreferencesFactory 実装がロードされ、インスタンスが作成されます。

導入されたバージョン:
1.4

フィールドの概要
static int MAX_KEY_LENGTH
          キーとして使用できる文字列の最大長 (80 文字) です。
static int MAX_NAME_LENGTH
          ノード名の最大長 (80 文字) です。
static int MAX_VALUE_LENGTH
          値として使用できる文字列の最大長 (8192 文字) です。
 
コンストラクタの概要
protected Preferences()
          唯一のコンストラクタです。
 
メソッドの概要
abstract  String absolutePath()
          この設定ノードの絶対パス名を返します。
abstract  void addNodeChangeListener(NodeChangeListener ncl)
          指定されたリスナーがこのノードの「ノード変更イベント」を受信するように登録します。
abstract  void addPreferenceChangeListener(PreferenceChangeListener pcl)
          指定されたリスナーがこの設定ノードに対する「設定変更イベント」を受信するように登録します。
abstract  String[] childrenNames()
          この設定ノードの子の名前 (このノードを起点とした相対名) を返します。
abstract  void clear()
          この設定ノード内の設定 (キーと値のペアの関連付け) をすべて削除します。
abstract  void exportNode(OutputStream os)
          このノード (その下位ノードは含まない) に含まれているすべての設定を表す XML ドキュメントを、指定された出力ストリームに発行します。
abstract  void exportSubtree(OutputStream os)
          このノードとそのすべての下位ノードに含まれるすべての設定を表す XML ドキュメントを発行します。
abstract  void flush()
          この設定ノードとその下位ノードの内容に対するすべての変更を、持続ストアに強制的に格納します。
abstract  String get(String key, String def)
          この設定ノード内の指定されたキーに関連付けられた値を返します。
abstract  boolean getBoolean(String key, boolean def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す boolean 値を返します。
abstract  byte[] getByteArray(String key, byte[] def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す byte 配列値を返します。
abstract  double getDouble(String key, double def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す double 値を返します。
abstract  float getFloat(String key, float def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す float 値を返します。
abstract  int getInt(String key, int def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す int 値を返します。
abstract  long getLong(String key, long def)
          この設定ノード内の指定されたキーに関連付けられた文字列が表す long 値を返します。
static void importPreferences(InputStream is)
          XML ドキュメントによって表されるすべての設定を、指定された入力ストリームからインポートします。
abstract  boolean isUserNode()
          この設定ノードがユーザ設定ツリーにある場合は、true を返します。
abstract  String[] keys()
          この設定ノード内に関連付けられた値を持つキーをすべて返します。
abstract  String name()
          この設定ノードの名前 (その親を起点とした相対名) を返します。
abstract  Preferences node(String pathName)
          このノードと同じツリーにある名前付き設定ノードを返します。
abstract  boolean nodeExists(String pathName)
          名前付き設定ノードがこのノードと同じツリーに存在する場合は、true を返します。
abstract  Preferences parent()
          この設定ノードの親を返し、このノードがルートの場合は null を返します。
abstract  void put(String key, String value)
          この設定ノードで指定されたキーに、指定された値を関連付けます。
abstract  void putBoolean(String key, boolean value)
          この設定ノード内の指定されたキーに、指定された boolean 値を表す文字列を関連付けます。
abstract  void putByteArray(String key, byte[] value)
          この設定ノード内の指定されたキーに、指定された byte 配列を表す文字列を関連付けます。
abstract  void putDouble(String key, double value)
          この設定ノード内の指定されたキーに、指定された double 値を表す文字列を関連付けます。
abstract  void putFloat(String key, float value)
          この設定ノード内の指定されたキーに、指定された float 値を表す文字列を関連付けます。
abstract  void putInt(String key, int value)
          この設定ノード内の指定されたキーに、指定された int 値を表す文字列を関連付けます。
abstract  void putLong(String key, long value)
          この設定ノード内の指定されたキーに、指定された long 値を表す文字列を関連付けます。
abstract  void remove(String key)
          この設定ノード内の指定されたキーに関連付けられた値がある場合は、それを削除します。
abstract  void removeNode()
          この設定ノードとその下位ノードをすべて削除し、削除したノードに含まれている設定をすべて無効にします。
abstract  void removeNodeChangeListener(NodeChangeListener ncl)
          指定された NodeChangeListener を削除して、イベントの受信を停止します。
abstract  void removePreferenceChangeListener(PreferenceChangeListener pcl)
          指定された設定変更リスナーを削除して、設定変更イベントの受信を停止します。
abstract  void sync()
          sync を呼び出すと、最初に、VM から持続ストアに格納された変更がこの設定ノードとその下位ノードにすべて反映されます。
static Preferences systemNodeForPackage(Class<?> c)
          システム設定ツリーから設定ノードを返します。
static Preferences systemRoot()
          システムのルート設定ノードを返します。
abstract  String toString()
          この設定ノードの文字列表現を返します。
static Preferences userNodeForPackage(Class<?> c)
          呼び出し側ユーザの設定ツリーから設定ノードを返します。
static Preferences userRoot()
          呼び出し側ユーザのルート設定ノードを返します。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

フィールドの詳細

MAX_KEY_LENGTH

public static final int MAX_KEY_LENGTH
キーとして使用できる文字列の最大長 (80 文字) です。

関連項目:
定数フィールド値

MAX_VALUE_LENGTH

public static final int MAX_VALUE_LENGTH
値として使用できる文字列の最大長 (8192 文字) です。

関連項目:
定数フィールド値

MAX_NAME_LENGTH

public static final int MAX_NAME_LENGTH
ノード名の最大長 (80 文字) です。

関連項目:
定数フィールド値
コンストラクタの詳細

Preferences

protected Preferences()
唯一のコンストラクタです。サブクラスのコンストラクタによる呼び出しは、通常は暗黙的な呼び出しです。

メソッドの詳細

userNodeForPackage

public static Preferences userNodeForPackage(Class<?> c)
呼び出し側ユーザの設定ツリーから設定ノードを返します。このユーザ設定ツリーは、規則に従って、指定されたクラスのパッケージに関連付けられています。つまり、ノードの絶対パス名は、完全指定のパッケージ名で、スラッシュ ('/') で始まり、ピリオド ('.') はスラッシュに置き換えられます。たとえば、クラス com.acme.widget に関連付けられたノードの絶対パス名は、/com/acme/widget となります。

この規則は、名前なしのパッケージには適用されません。名前なしのパッケージに関連付けられた設定ノードは、<unnamed> になります。このノードは、長期間の使用には適していませんが、パッケージにまだ属していない開発初期段階のプログラムや使い捨てのプログラムで使用できます。ただし、重要なデータはこのノードに格納しないでください。このノードを使用するすべてのプログラムがデータを共有するためです。

クラス Foo を使用して名前なしのパッケージに関する設定にアクセスするには、 次の方法で設定ノードを取得します


    static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
 
このイディオムを使用すると、設定ノードを記述する文字列を使用する必要がないため、実行時障害が発生する可能性が減少します (クラス名のスペルが間違っている場合は通常、コンパイル時エラーになる)。

このメソッドを呼び出したときに、返されるノードとその上位ノードが存在しなかった場合は、それらのノードが作成されます。返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。

パラメータ:
c - ユーザ設定ノードを必要とするパッケージのクラス
戻り値:
c が属しているパッケージに関連付けられたユーザ設定ノード
例外:
NullPointerException - cnull の場合
SecurityException - セキュリティマネージャが存在し、それが RuntimePermission("preferences") を拒否した場合
関連項目:
RuntimePermission

systemNodeForPackage

public static Preferences systemNodeForPackage(Class<?> c)
システム設定ツリーから設定ノードを返します。このシステム設定ツリーは、規則に従って、指定されたクラスのパッケージに関連付けられています。つまり、ノードの絶対パス名は、完全指定のパッケージ名で、スラッシュ ('/') で始まり、ピリオド ('.') はスラッシュに置き換えられます。たとえば、クラス com.acme.widget に関連付けられたノードの絶対パス名は、/com/acme/widget となります。

この規則は、名前なしのパッケージには適用されません。名前なしのパッケージに関連付けられた設定ノードは、<unnamed> になります。このノードは、長期間の使用には適していませんが、パッケージにまだ属していない開発初期段階のプログラムや使い捨てのプログラムで使用できます。ただし、重要なデータはこのノードに格納しないでください。このノードを使用するすべてのプログラムがデータを共有するためです。

クラス Foo を使用して名前なしのパッケージに関する設定にアクセスするには、 次の方法で設定ノードを取得します


  static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);
 
このイディオムを使用すると、設定ノードを記述する文字列を使用する必要がないため、実行時障害が発生する可能性が減少します (クラス名のスペルが間違っている場合は通常、コンパイル時エラーになる)。

このメソッドを呼び出したときに、返されるノードとその上位ノードが存在しなかった場合は、それらのノードが作成されます。返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。

パラメータ:
c - システム設定ノードを必要とするパッケージのクラス
戻り値:
c が属しているパッケージに関連付けられたシステム設定ノード
例外:
NullPointerException - cnull の場合
SecurityException - セキュリティマネージャが存在し、それが RuntimePermission("preferences") を拒否した場合
関連項目:
RuntimePermission

userRoot

public static Preferences userRoot()
呼び出し側ユーザのルート設定ノードを返します。

戻り値:
呼び出し側ユーザのルート設定ノード
例外:
SecurityException - セキュリティマネージャが存在し、それが RuntimePermission("preferences") を拒否した場合
関連項目:
RuntimePermission

systemRoot

public static Preferences systemRoot()
システムのルート設定ノードを返します。

戻り値:
システムのルート設定ノード
例外:
SecurityException - セキュリティマネージャが存在し、それが RuntimePermission("preferences") を拒否した場合
関連項目:
RuntimePermission

put

public abstract void put(String key,
                         String value)
この設定ノードで指定されたキーに、指定された値を関連付けます。

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

get

public abstract String get(String key,
                           String def)
この設定ノード内の指定されたキーに関連付けられた値を返します。キーに関連付けられた値がない場合またはバッキングストアが利用できない場合は、指定されたデフォルトを返します。

一部の実装は、デフォルト値をそのバッキングストアに格納します。指定されたキーに関連付けられた値がない場合でも、「格納済みデフォルト」がある場合は、指定されたデフォルトに優先して格納済みデフォルトが返されます。

パラメータ:
key - 関連付けられた値が返されるキー
def - この設定ノードの key に関連付けられた値がない場合に返される値
戻り値:
key に関連付けられた値。key に関連付けられた値がない場合またはバッキングストアが利用できない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合 (def には null 値を指定できる)

remove

public abstract void remove(String key)
この設定ノード内の指定されたキーに関連付けられた値がある場合は、それを削除します。

この実装が「格納済みデフォルト」をサポートしており、指定された設定に格納済みデフォルトが存在する場合は、この呼び出しにより格納済みデフォルトが使用されるようになります。つまり、後続の get 呼び出しでは格納済みデフォルトが返されます。

パラメータ:
key - マッピングが設定ノードから削除されるキー
例外:
NullPointerException - keynull の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合

clear

public abstract void clear()
                    throws BackingStoreException
この設定ノード内の設定 (キーと値のペアの関連付け) をすべて削除します。この呼び出しは、このノードの下位ノードには適用されません。

この実装が「格納済みデフォルト」をサポートしており、設定階層内のこのノードに格納済みデフォルトが含まれている場合は、この呼び出しにより格納済みデフォルトが使用されるようになります。つまり、後続の get 呼び出しでは格納済みデフォルトが返されます。

例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
removeNode()

putInt

public abstract void putInt(String key,
                            int value)
この設定ノード内の指定されたキーに、指定された int 値を表す文字列を関連付けます。関連付けられる文字列は、int 値が Integer.toString(int) に渡された場合に返される値です。このメソッドは、getInt(java.lang.String, int) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - keynull の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getInt(String,int)

getInt

public abstract int getInt(String key,
                           int def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す int 値を返します。この文字列は、Integer.parseInt(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Integer.parseInt(String)NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putInt(java.lang.String, int) と組み合わせて使用します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Integer.parseInt によって int に変換できる場合は、指定されたデフォルトに優先してこの int が返されます。

パラメータ:
key - 関連付けられた値が int として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が int とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノード内の key に関連付けられた文字列が表す int 値。関連付けられた値が存在しない場合または int とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合
関連項目:
putInt(String,int), get(String,String)

putLong

public abstract void putLong(String key,
                             long value)
この設定ノード内の指定されたキーに、指定された long 値を表す文字列を関連付けます。関連付けられる文字列は、long 値が Long.toString(long) に渡された場合に返される値です。このメソッドは、getLong(java.lang.String, long) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - keynull の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getLong(String,long)

getLong

public abstract long getLong(String key,
                             long def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す long 値を返します。この文字列は、Long.parseLong(String) によって long に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Long.parseLong(String)NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putLong(java.lang.String, long) と組み合わせて使用します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Long.parseLong によって long に変換できる場合は、指定されたデフォルトに優先してこの long が返されます。

パラメータ:
key - 関連付けられた値が long として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が long とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す long 値。関連付けられた値が存在しない場合または long とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合
関連項目:
putLong(String,long), get(String,String)

putBoolean

public abstract void putBoolean(String key,
                                boolean value)
この設定ノード内の指定されたキーに、指定された boolean 値を表す文字列を関連付けます。関連付けられる文字列は、この値が true である場合は "true"、false である場合は "false" となります。このメソッドは、getBoolean(java.lang.String, boolean) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - keynull の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getBoolean(String,boolean), get(String,String)

getBoolean

public abstract boolean getBoolean(String key,
                                   boolean def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す boolean 値を返します。有効な値は、ture を表す "true" と false を表す "false" です。大文字と小文字は区別されないため、"TRUE""False" も有効です。このメソッドは、putBoolean(java.lang.String, boolean) と組み合わせて使用します。

キーに関連付けられる値がない場合、バッキングストアが利用できない場合、または関連付けられた値が "true" または "false" (大文字と小文字は区別されない) 以外である場合は、指定されたデフォルトを返します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、格納済みデフォルトが "true" または "false" (大文字と小文字は区別されない) である場合は、指定されたデフォルトに優先して使用されます。そうでない場合は、指定されたデフォルトが使用されます。

パラメータ:
key - 関連付けられた値が boolean として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が boolean とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す boolean 値。関連付けられた値が存在しない場合または boolean とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合
関連項目:
get(String,String), putBoolean(String,boolean)

putFloat

public abstract void putFloat(String key,
                              float value)
この設定ノード内の指定されたキーに、指定された float 値を表す文字列を関連付けます。関連付けられる文字列は、float 値が Float.toString(float) に渡された場合に返される値です。このメソッドは、getFloat(java.lang.String, float) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - keynull の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getFloat(String,float)

getFloat

public abstract float getFloat(String key,
                               float def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す float 値を返します。この文字列は、Float.parseFloat(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Float.parseFloat(String)NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putFloat(java.lang.String, float) と組み合わせて使用します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Float.parseFloat によって float に変換できる場合は、指定されたデフォルトに優先してこの float が返されます。

パラメータ:
key - 関連付けられた値が float として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が float とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す float 値。関連付けられた値が存在しない場合または float とみなされない場合は def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合
関連項目:
putFloat(String,float), get(String,String)

putDouble

public abstract void putDouble(String key,
                               double value)
この設定ノード内の指定されたキーに、指定された double 値を表す文字列を関連付けます。関連付けられる文字列は、double 値が Double.toString(double) に渡された場合に返される値です。このメソッドは、getDouble(java.lang.String, double) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - keynull の場合
IllegalArgumentException - key.length()MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getDouble(String,double)

getDouble

public abstract double getDouble(String key,
                                 double def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す double 値を返します。この文字列は、Double.parseDouble(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Double.parseDouble(String)NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putDouble(java.lang.String, double) と組み合わせて使用します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Double.parseDouble によって double に変換できる場合は、指定されたデフォルトに優先してこの double が返されます。

パラメータ:
key - 関連付けられた値が double として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が double とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す double 値。関連付けられた値が存在しない場合または double とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合
関連項目:
putDouble(String,double), get(String,String)

putByteArray

public abstract void putByteArray(String key,
                                  byte[] value)
この設定ノード内の指定されたキーに、指定された byte 配列を表す文字列を関連付けます。関連付ける値は、Base64 でエンコードされた byte 配列です。これについては、RFC 2045 の 6.8 項に定義されています。ただし、この文字列は Base64 Alphabet の文字だけで構成し、改行文字を含めることができません。また、Base64 でエンコードされた文字列が MAX_VALUE_LENGTH を超えないように、byte 配列の最大長が MAX_VALUE_LENGTH の 4 分の 3 に制限されています。このメソッドは、getByteArray(java.lang.String, byte[]) と組み合わせて使用します。

パラメータ:
key - 文字列形式の値が関連付けられるキー
value - キーに関連付けられる文字列形式の値
例外:
NullPointerException - キーまたは値が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合または value.length が MAX_VALUE_LENGTH*3/4 を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
getByteArray(String,byte[]), get(String,String)

getByteArray

public abstract byte[] getByteArray(String key,
                                    byte[] def)
この設定ノード内の指定されたキーに関連付けられた文字列が表す byte 配列値を返します。有効な文字列は、Base64 でエンコードされたバイナリデータです。これについては、RFC 2045 の 6.8 項に定義されています。ただし、この文字列は Base64 Alphabet の文字だけで構成し、これ以外の文字や改行文字は使用できません。このメソッドは、putByteArray(java.lang.String, byte[]) と組み合わせて使用します。

キーに関連付けられる値がない場合、バッキングストアが利用できない場合、または関連付けられた値が Base64 でエンコードされた有効な byte 配列 (前述の定義どおり) でない場合は、指定されたデフォルトを返します。

この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、格納済みデフォルトが Base64 でエンコードされた有効な byte 配列 (前述の定義どおり) である場合は、指定されたデフォルトに優先して使用されます。そうでない場合は、指定されたデフォルトが使用されます。

パラメータ:
key - 関連付けられた値が byte 配列として返されるキー
def - この設定ノードの key に関連付けられる値がない場合、関連付けられた値が byte 配列とみなされない場合、またはバッキングストアが利用できない場合に、返される値
戻り値:
この設定ノードの key に関連付けられた文字列が表す byte 配列値。関連付けられた値が存在しない場合または byte 配列とみなされない場合は、def
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - keynull の場合 (def には null 値を指定できる)
関連項目:
get(String,String), putByteArray(String,byte[])

keys

public abstract String[] keys()
                       throws BackingStoreException
この設定ノード内に関連付けられた値を持つキーをすべて返します。このノードに設定がない場合、返される配列のサイズはゼロになります。

この実装が「格納済みデフォルト」をサポートし、このノードに格納済みデフォルトがあり、明示的な設定によってオーバーライドされていない場合は、明示的な設定と格納済みデフォルトが配列に返されます。

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

childrenNames

public abstract String[] childrenNames()
                                throws BackingStoreException
この設定ノードの子の名前 (このノードを起点とした相対名) を返します。このノードに子がない場合、返される配列のサイズはゼロになります。

戻り値:
この設定ノードの子の名前
例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合

parent

public abstract Preferences parent()
この設定ノードの親を返し、このノードがルートの場合は null を返します。

戻り値:
この設定ノードの親
例外:
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合

node

public abstract Preferences node(String pathName)
このノードと同じツリーにある名前付き設定ノードを返します。このノードとその上位ノードが存在しない場合は、それらをすべて作成します。相対パス名または絶対パス名を受け入れます。相対パス名 (スラッシュ文字 ('/') で始まらないパス名) は、この設定ノードを起点として解釈されます。

返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。

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

nodeExists

public abstract boolean nodeExists(String pathName)
                            throws BackingStoreException
名前付き設定ノードがこのノードと同じツリーに存在する場合は、true を返します。相対パス名 (スラッシュ文字 ('/') で始まらないパス名) は、この設定ノードを起点として解釈されます。

このノード (または上位ノード) が removeNode() メソッドによってすでに削除されている場合は、パス名が "" のときにだけこのメソッドの呼び出しが正当になり、false を返します。つまり、イディオム p.nodeExists("") は、p が削除されているかどうかをテストする場合に使用します。

パラメータ:
pathName - 存在が確認されるノードのパス名
戻り値:
指定されたノードが存在する場合に true
例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalArgumentException - パス名が無効の場合 (連続した複数のスラッシュ文字が含まれている場合、または複数の文字長のパスがスラッシュ文字で終わっている場合)
NullPointerException - パス名が null の場合。* このノード (または上位ノード) が removeNode() メソッドによって削除され、pathName が空の文字列 ("") でないときに、@throws IllegalStateException がスローされる

removeNode

public abstract void removeNode()
                         throws BackingStoreException
この設定ノードとその下位ノードをすべて削除し、削除したノードに含まれている設定をすべて無効にします。ノードが削除されたあとで、対応する Preferences インスタンス上で name()absolutePath()isUserNode()flush()nodeExists("") 以外のメソッドを呼び出すと、すべて失敗して IllegalStateException がスローされます。Object に定義されたメソッドは、ノードが削除されたあとでも呼び出すことができ、IllegalStateException はスローされません。

この削除は、このノード (または上位ノード) 上で flush メソッドを呼び出したときに、持続的になります。

この実装が「格納済みデフォルト」をサポートしている場合は、ノードを削除すると、このノードまたはその下位ノードに格納済みデフォルトが使用されます。つまり、それ以降にこのノードのパス名上で nodeExists を呼び出すと、true が返されます。また、node を呼び出すと、設定または子、あるいはその両方の空でないコレクションを表す (別の) Preferences インスタンスが返されます。

例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除済みの場合
UnsupportedOperationException - このメソッドがルートノード上で呼び出された場合
関連項目:
flush()

name

public abstract String name()
この設定ノードの名前 (その親を起点とした相対名) を返します。

戻り値:
この設定ノードの名前 (その親を起点とした相対名)

absolutePath

public abstract String absolutePath()
この設定ノードの絶対パス名を返します。

戻り値:
この設定ノードの絶対パス名

isUserNode

public abstract boolean isUserNode()
この設定ノードがユーザ設定ツリーにある場合は、true を返します。システム設定ツリーにある場合は、false を返します。

戻り値:
この設定ノードがユーザ設定ツリーにある場合は、true。システム設定ツリーにある場合は、false

toString

public abstract String toString()
この設定ノードの文字列表現を返します。(this.isUserNode() ? "User" : "System") + " Preference Node: " + this.absolutePath() という形式で返します。

オーバーライド:
クラス Object 内の toString
戻り値:
このオブジェクトの文字列表現

flush

public abstract void flush()
                    throws BackingStoreException
この設定ノードとその下位ノードの内容に対するすべての変更を、持続ストアに強制的に格納します。このメソッドが正常に復帰した場合は、このメソッドが呼び出される前に、このノードをルートとするサブツリーにすべての変更が適用されています。

この実装を使用すれば、任意のタイミングで持続ストアに変更をフラッシュできます。このメソッドが呼び出されるまで待機する必要はありません。

新しく作成されたノードでフラッシュが発生すると、そのノードが持続的になり、まだ持続的になっていない上位ノード (および下位ノード) も持続的になります。ただし、上位ノードに対する設定値の変更は、持続的になりません。

このメソッドを、removeNode() メソッドを使用して削除されたノード上で呼び出すと、flushSpi() がこのノード上で呼び出されますが、他のノードでは呼び出されません。

例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
関連項目:
sync()

sync

public abstract void sync()
                   throws BackingStoreException
sync を呼び出すと、最初に、VM から持続ストアに格納された変更がこの設定ノードとその下位ノードにすべて反映されます。つまり、この設定ノードとその下位ノードの内容に対する変更がすべて強制的に持続ストアに格納され、この設定ノード上で flush メソッドを呼び出した場合と同じ効果が発生します。

例外:
BackingStoreException - バッキングストアに障害が発生したためにこの操作を完了できない場合、またはバッキングストアと通信できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
flush()

addPreferenceChangeListener

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

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

パラメータ:
pcl - 追加する設定変更リスナー
例外:
NullPointerException - pcl が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
removePreferenceChangeListener(PreferenceChangeListener), addNodeChangeListener(NodeChangeListener)

removePreferenceChangeListener

public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
指定された設定変更リスナーを削除して、設定変更イベントの受信を停止します。

パラメータ:
pcl - 削除する設定変更リスナー
例外:
IllegalArgumentException - pcl がこのノードに登録された設定変更リスナーでなかった場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
addPreferenceChangeListener(PreferenceChangeListener)

addNodeChangeListener

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

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

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

パラメータ:
ncl - 追加する NodeChangeListener
例外:
NullPointerException - ncl が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
removeNodeChangeListener(NodeChangeListener), addPreferenceChangeListener(PreferenceChangeListener)

removeNodeChangeListener

public abstract void removeNodeChangeListener(NodeChangeListener ncl)
指定された NodeChangeListener を削除して、イベントの受信を停止します。

パラメータ:
ncl - 削除する NodeChangeListener
例外:
IllegalArgumentException - ncl がこのノードに登録された NodeChangeListener でなかった場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
addNodeChangeListener(NodeChangeListener)

exportNode

public abstract void exportNode(OutputStream os)
                         throws IOException,
                                BackingStoreException
このノード (その下位ノードは含まない) に含まれているすべての設定を表す XML ドキュメントを、指定された出力ストリームに発行します。この XML ドキュメントは、このノードのオフラインバックアップにもなります。

この XML ドキュメントでは、次の DOCTYPE が宣言されます。


 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 
UTF-8 文字セットが使用されます。

このメソッドは通常の規則と異なり、このクラスの複数のメソッドを同時に実行すると、逐次実行した場合と同じ結果が生成されます。このメソッドの 1 回の呼び出しでこのノードの設定が同時に変更された場合、エクスポートされた設定がこのノードに含まれる設定と一致していないことがあります。つまり、同時に行われた変更は、エクスポートされたデータに反映されていないことがあります。

パラメータ:
os - XML ドキュメントの発行先の出力ストリーム
例外:
IOException - 指定された出力ストリームに書き込んだときに、IOException が発生した場合
BackingStoreException - 設定データがバッキングストアから読み取れない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
importPreferences(InputStream)

exportSubtree

public abstract void exportSubtree(OutputStream os)
                            throws IOException,
                                   BackingStoreException
このノードとそのすべての下位ノードに含まれるすべての設定を表す XML ドキュメントを発行します。この XML ドキュメントは、このノードをルートとするサブツリーのオフラインバックアップにもなります。

この XML ドキュメントでは、次の DOCTYPE が宣言されます。


 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 
UTF-8 文字セットが使用されます。

このメソッドは通常の規則と異なり、このクラスの複数のメソッドを同時に実行すると、逐次実行した場合と同じ結果が生成されます。このメソッドの 1 回の呼び出しでこのノードをルートとするサブツリーの設定またはノードが同時に変更された場合、エクスポートされた設定がサブツリーと一致していないことがあります。つまり、同時に行われた変更は、エクスポートされたデータに反映されていないことがあります。

パラメータ:
os - XML ドキュメントの発行先の出力ストリーム
例外:
IOException - 指定された出力ストリームに書き込んだときに、IOException が発生した場合
BackingStoreException - 設定データがバッキングストアから読み取れない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
関連項目:
importPreferences(InputStream), exportNode(OutputStream)

importPreferences

public static void importPreferences(InputStream is)
                              throws IOException,
                                     InvalidPreferencesFormatException
XML ドキュメントによって表されるすべての設定を、指定された入力ストリームからインポートします。このドキュメントは、ユーザ設定またはシステム設定を表しています。ユーザ設定を表している場合は、呼び出したユーザの設定ツリーに設定がインポートされます。別のユーザ設定ツリーのドキュメントをインポートしてもかまいません。このドキュメントに記述されている設定の設定ノードが存在しない場合は、そのノードが作成されます。

XML ドキュメントには、次の DOCTYPE 宣言が必要です。


 <!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
 
(このメソッドは、exportNode(OutputStream) および exportSubtree(OutputStream) と組み合わせて使用するように設計されている)

このメソッドは通常の規則と異なり、このクラスの複数のメソッドを同時に実行すると、逐次実行した場合と同じ結果が生成されます。このメソッドを実行すると、このクラスのほかの public メソッド (node(String)put(String, String) など) をオーバーライドして実装した場合と同じ結果が生成されます。

パラメータ:
is - XML ドキュメントの読み込み元の入力ストリーム
例外:
IOException - 指定された入力ストリームを読み込んだときに、IOException が発生した場合
InvalidPreferencesFormatException - 入力ストリームのデータによって、要求されたドキュメント型を持つ有効な XML ドキュメントが作成されなかった場合
SecurityException - セキュリティマネージャが存在し、それが RuntimePermission("preferences") を拒否した場合
関連項目:
RuntimePermission

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 も参照してください。