java.util.prefs.Preferences
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public abstract class Preferences
設定データの階層的な集合の中の 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 実装を指定するには、Java(TM) SE 実装にその方法を設定する必要があります。これによって、管理者はデフォルトの preferences 実装を代替実装に置き換えることができます。
実装にあたっての注意:Sun の JRE では、PreferencesFactory の実装は次のように実施されます。
システムプロパティー java.util.prefs.PreferencesFactory が定義されている場合、これがクラスを実装する PreferencesFactory インタフェースの完全指定名と見なされます。その後、クラスがロードされ、インスタンスが作成されます。
システムクラスローダーの認識する jar ファイルに PreferencesFactory 実装クラスファイルがインストールされていて、この jar ファイルにリソースディレクトリ META-INF/services 内のプロバイダ構成ファイル java.util.prefs.PreferencesFactory が含まれている場合、このファイルに指定されている最初のクラス名が使用されます。このような jar ファイルが 2 つ以上指定された場合は、最初に検出されたファイルが使用されます。その後、クラスがロードされ、インスタンスが作成されます。
この処理に失敗した場合は、詳細不明エラーがスローされます。 最後に、前述のシステムプロパティーと拡張 jar ファイルのどちらも指定されていない場合は、そのとき使用されているプラットフォームに対してシステムワイドのデフォルトである PreferencesFactory 実装がロードされ、インスタンスが作成されます。
| フィールドの概要 | |
|---|---|
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 |
| フィールドの詳細 |
|---|
public static final int MAX_KEY_LENGTH
public static final int MAX_VALUE_LENGTH
public static final int MAX_NAME_LENGTH
| コンストラクタの詳細 |
|---|
protected Preferences()
| メソッドの詳細 |
|---|
public static Preferences userNodeForPackage(Class<?> c)
この規則は、名前なしのパッケージには適用されません。 名前なしのパッケージに関連付けられた設定ノードは、<unnamed> になります。このノードは、長期間の使用には適していませんが、パッケージにまだ属していない開発初期段階のプログラムや使い捨てのプログラムで使用できます。ただし、重要なデータはこのノードに格納しないでください。 このノードを使用するすべてのプログラムがデータを共有するためです。
Foo クラスを使用して名前なしのパッケージに関する設定にアクセスするには、次の方法で設定ノードを取得します。
static Preferences prefs = Preferences.userNodeForPackage(Foo.class);
このイディオムを使えば、文字列を使って設定ノードを記述する必要がなくなるため、実行時にエラーが発生する可能性が減ります。(クラス名の綴りを間違った場合は通常、コンパイル時にエラーが発生する。)
このメソッドを呼び出したときに、返されるノードとその上位ノードが存在しなかった場合は、それらのノードが作成されます。返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。
c - ユーザー設定ノードを必要とするパッケージのクラス
NullPointerException - c が null の場合
SecurityException - セキュリティーマネージャーが存在し、それが RuntimePermission("preferences") を拒否した場合RuntimePermissionpublic static Preferences systemNodeForPackage(Class<?> c)
この規則は、名前なしのパッケージには適用されません。 名前なしのパッケージに関連付けられた設定ノードは、<unnamed> になります。このノードは、長期間の使用には適していませんが、パッケージにまだ属していない開発初期段階のプログラムや使い捨てのプログラムで使用できます。ただし、重要なデータはこのノードに格納しないでください。 このノードを使用するすべてのプログラムがデータを共有するためです。
Foo クラスを使用して名前なしのパッケージに関する設定にアクセスするには、次の方法で設定ノードを取得します。
static Preferences prefs = Preferences.systemNodeForPackage(Foo.class);このイディオムを使えば、文字列を使って設定ノードを記述する必要がなくなるため、実行時にエラーが発生する可能性が減ります。(クラス名の綴りを間違った場合は通常、コンパイル時にエラーが発生する。)
このメソッドを呼び出したときに、返されるノードとその上位ノードが存在しなかった場合は、それらのノードが作成されます。返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。
c - システム設定ノードを必要とするパッケージのクラス
NullPointerException - c が null の場合
SecurityException - セキュリティーマネージャーが存在し、それが RuntimePermission("preferences") を拒否した場合RuntimePermissionpublic static Preferences userRoot()
SecurityException - セキュリティーマネージャーが存在し、それが RuntimePermission("preferences") を拒否した場合RuntimePermissionpublic static Preferences systemRoot()
SecurityException - セキュリティーマネージャーが存在し、それが RuntimePermission("preferences") を拒否した場合RuntimePermission
public abstract void put(String key,
String value)
key - 指定の値が関連付けられるキーvalue - 指定のキーに関連付けられる値
NullPointerException - キーまたは値が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合、または value.length が MAX_VALUE_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
public abstract String get(String key,
String def)
一部の実装は、デフォルト値をそのバッキングストアに格納します。指定されたキーに関連付けられた値がない場合でも、「格納済みデフォルト」がある場合は、指定されたデフォルトに優先して格納済みデフォルトが返されます。
key - 関連付けられている値が返されるキーdef - この設定ノードが key に関連付けられた値を持たない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合)public abstract void remove(String key)
この実装が「格納済みデフォルト」をサポートしており、指定された設定に格納済みデフォルトが存在する場合は、この呼び出しにより格納済みデフォルトが使用されるようになります。つまり、後続の get 呼び出しでは格納済みデフォルトが返されます。
key - マッピングが設定ノードから削除されるキー
NullPointerException - key が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
public abstract void clear()
throws BackingStoreException
この実装が「格納済みデフォルト」をサポートしており、設定階層内のこのノードに格納済みデフォルトが含まれている場合は、この呼び出しにより格納済みデフォルトが使用されるようになります。つまり、後続の get 呼び出しでは格納済みデフォルトが返されます。
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合removeNode()
public abstract void putInt(String key,
int value)
Integer.toString(int) に渡された場合に返される値です。このメソッドは、getInt(java.lang.String, int) と組み合わせて使用します。
key - 文字列形式の値が関連付けられるキーvalue - キーに関連付けられる文字列形式の値
NullPointerException - key が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合getInt(String,int)
public abstract int getInt(String key,
int def)
Integer.parseInt(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Integer.parseInt(String) が NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putInt(java.lang.String, int) と組み合わせて使用します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Integer.parseInt によって int に変換できる場合は、指定されたデフォルトに優先してこの int が返されます。
key - 関連付けられた値が int として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を int として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合putInt(String,int),
get(String,String)
public abstract void putLong(String key,
long value)
Long.toString(long) に渡された場合に返される値です。このメソッドは、getLong(java.lang.String, long) と組み合わせて使用します。
key - 文字列形式の値が関連付けられるキーvalue - キーに関連付けられる文字列形式の値
NullPointerException - key が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合getLong(String,long)
public abstract long getLong(String key,
long def)
Long.parseLong(String) によって long に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Long.parseLong(String) が NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putLong(java.lang.String, long) と組み合わせて使用します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Long.parseLong によって long に変換できる場合は、指定されたデフォルトに優先してこの long が返されます。
key - 関連付けられた値が long として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を long として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合putLong(String,long),
get(String,String)
public abstract void putBoolean(String key,
boolean value)
getBoolean(java.lang.String, boolean) と組み合わせて使用します。
key - 文字列形式の値が関連付けられるキーvalue - キーに関連付けられる文字列形式の値
NullPointerException - key が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合getBoolean(String,boolean),
get(String,String)
public abstract boolean getBoolean(String key,
boolean def)
putBoolean(java.lang.String, boolean) と組み合わせて使用します。
キーに関連付けられる値がない場合、バッキングストアが利用できない場合、または関連付けられた値が "true" または "false" (大文字と小文字は区別されない) 以外である場合は、指定されたデフォルトを返します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、格納済みデフォルトが "true" または "false" (大文字と小文字は区別されない) である場合は、指定されたデフォルトに優先して使用されます。そうでない場合は、指定されたデフォルトが使用されます。
key - 関連付けられた値が boolean として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を boolean として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合get(String,String),
putBoolean(String,boolean)
public abstract void putFloat(String key,
float value)
Float.toString(float) に渡された場合に返される値です。このメソッドは、getFloat(java.lang.String, float) と組み合わせて使用します。
key - 文字列形式の値が関連付けられるキーvalue - キーに関連付けられる文字列形式の値
NullPointerException - key が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合getFloat(String,float)
public abstract float getFloat(String key,
float def)
Float.parseFloat(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Float.parseFloat(String) が NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putFloat(java.lang.String, float) と組み合わせて使用します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Float.parseFloat によって float に変換できる場合は、指定されたデフォルトに優先してこの float が返されます。
key - 関連付けられた値が float として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を float として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合putFloat(String,float),
get(String,String)
public abstract void putDouble(String key,
double value)
Double.toString(double) に渡された場合に返される値です。このメソッドは、getDouble(java.lang.String, double) と組み合わせて使用します。
key - 文字列形式の値が関連付けられるキーvalue - キーに関連付けられる文字列形式の値
NullPointerException - key が null の場合
IllegalArgumentException - key.length() が MAX_KEY_LENGTH を超える場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合getDouble(String,double)
public abstract double getDouble(String key,
double def)
Double.parseDouble(String) によって整数に変換されます。キーに関連付けられた値がない場合、バッキングストアが利用できない場合、または関連付けられた値が渡されたときに Double.parseDouble(String) が NumberFormatException をスローした場合は、指定されたデフォルトを返します。このメソッドは、putDouble(java.lang.String, double) と組み合わせて使用します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、Double.parseDouble によって double に変換できる場合は、指定されたデフォルトに優先してこの double が返されます。
key - 関連付けられた値が double として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を double として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合putDouble(String,double),
get(String,String)
public abstract void putByteArray(String key,
byte[] value)
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)
public abstract byte[] getByteArray(String key,
byte[] def)
putByteArray(java.lang.String, byte[]) と組み合わせて使用します。
キーに関連付けられる値がない場合、バッキングストアが利用できない場合、または関連付けられた値が Base64 でエンコードされた有効な byte 配列 (上の定義を参照) でない場合は、指定されたデフォルトを返します。
この実装が「格納済みデフォルト」をサポートし、格納済みデフォルトが存在してアクセス可能であり、格納済みデフォルトが Base64 でエンコードされた有効な byte 配列 (上記の定義どおり) である場合は、指定されたデフォルトに優先して使用されます。そうでない場合は、指定されたデフォルトが使用されます。
key - 関連付けられた値が byte 配列として返されるキーdef - この設定ノードが key に関連付けられた値を持たないか、関連付けられた値を byte 配列として解釈できないか、あるいはバッキングストアにアクセスできない場合に返すべき値
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
NullPointerException - key が null の場合)get(String,String),
putByteArray(String,byte[])
public abstract String[] keys()
throws BackingStoreException
この実装が「格納済みデフォルト」をサポートし、このノードに格納済みデフォルトがあり、明示的な設定によってオーバーライドされていない場合は、明示的な設定と格納済みデフォルトが配列に返されます。
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合
public abstract String[] childrenNames()
throws BackingStoreException
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合public abstract Preferences parent()
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合public abstract Preferences node(String pathName)
返されるノードがこの呼び出し以前に存在しなかった場合、この呼び出しによって作成されたノードとその上位ノードは、返されるノード (あるいはその上位ノードまたは下位ノード) 上で flush メソッドが呼び出されたときに、持続的になります。
pathName - 返される設定ノードのパス名
IllegalArgumentException - パス名が無効である場合 (つまり、パス名に連続した複数のスラッシュ文字が含まれているか、パス名がスラッシュ文字で終わっていてその長さが 2 文字以上の場合)
NullPointerException - パス名が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合flush()
public abstract boolean nodeExists(String pathName)
throws BackingStoreException
このノード (または上位ノード) が removeNode() メソッドによってすでに削除されている場合は、パス名が "" のときにだけこのメソッドの呼び出しが正当になり、false を返します。つまり、イディオム p.nodeExists("") は、p が削除されているかどうかをテストする場合に使用します。
pathName - 存在が確認されるノードのパス名
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalArgumentException - パス名が無効である場合 (つまり、パス名に連続した複数のスラッシュ文字が含まれているか、パス名がスラッシュ文字で終わっていてその長さが 2 文字以上の場合)
NullPointerException - パス名が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除されており、pathName が空の文字列 (「」) でない場合
public abstract void removeNode()
throws BackingStoreException
name()、absolutePath()、isUserNode()、flush()、nodeExists("") 以外のメソッドを呼び出すと、すべて失敗して IllegalStateException がスローされます。Object に定義されたメソッドは、ノードが削除されたあとでも呼び出すことができ、IllegalStateException はスローされません。
この削除は、このノード (または上位ノード) 上で flush メソッドを呼び出したときに、持続的になります。
この実装が「格納済みデフォルト」をサポートしている場合は、ノードを削除すると、このノードまたはその下位ノードに格納済みデフォルトが使用されます。つまり、それ以降にこのノードのパス名上で nodeExists を呼び出すと、true が返されます。 また、node を呼び出すと、設定または子、あるいはその両方の空でないコレクションを表す (別の) Preferences インスタンスが返されます。
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによってすでに削除されている場合
UnsupportedOperationException - このメソッドがルートノード上で呼び出された場合flush()public abstract String name()
public abstract String absolutePath()
public abstract boolean isUserNode()
public abstract String toString()
Object 内の toString
public abstract void flush()
throws BackingStoreException
この実装を使用すれば、任意のタイミングで持続ストアに変更をフラッシュできます。このメソッドが呼び出されるまで待機する必要はありません。
新しく作成されたノードでフラッシュが発生すると、そのノードが持続的になり、まだ持続的になっていない上位ノード (および下位ノード) も持続的になります。ただし、上位ノードに対する設定値の変更は、持続的になりません。
このメソッドを、removeNode() メソッドを使用して削除されたノード上で呼び出すと、flushSpi() がこのノード上で呼び出されますが、ほかのノードでは呼び出されません。
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合sync()
public abstract void sync()
throws BackingStoreException
BackingStoreException - バッキングストアで障害が発生したかストアとの通信が行えないために、このオペレーションを完了できない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合flush()public abstract void addPreferenceChangeListener(PreferenceChangeListener pcl)
removeNode() メソッドでは生成されません。 このメソッドでは、「ノード変更イベント」が生成されます。設定変更イベントは clear メソッドによって生成されます。
ノード変更イベントは、登録されたリスナーと同じ JVM 内で変更が行われたときにだけ、生成されます。 ただし、一部の実装では、現在の JVM の外部で行われた変更に対して、イベントが生成されることがあります。イベントが生成された時点で、変更が持続的になっていないことがあります。現在のノードの下位ノードで設定が変更されたときは、イベントは生成されません。 そのようなイベントが必要な場合は、そのノードを登録する必要があります。
pcl - 追加する設定変更リスナー
NullPointerException - pcl が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合removePreferenceChangeListener(PreferenceChangeListener),
addNodeChangeListener(NodeChangeListener)public abstract void removePreferenceChangeListener(PreferenceChangeListener pcl)
pcl - 削除する設定変更リスナー
IllegalArgumentException - pcl がこのノード上で登録された設定変更リスナーではなかった場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合addPreferenceChangeListener(PreferenceChangeListener)public abstract void addNodeChangeListener(NodeChangeListener ncl)
removeNode() 呼び出しによって、複数の「ノード変更イベント」が生成されます。 つまり、削除されたノードをルートとするサブツリー内の各ノードに 1 つずつ生成されます。
ノード変更イベントは、登録されたリスナーと同じ JVM 内で変更が行われたときにだけ、生成されます。 ただし、一部の実装では、現在の JVM の外部で行われた変更に対して、イベントが生成されることがあります。イベントが生成された時点で、変更が持続的になっていないことがあります。現在のノードの配下にない下位ノードが追加または削除されたときは、イベントは生成されません。 そのようなイベントが必要な場合は、そのノードを登録する必要があります。
作成されたノードは、ただちに有効になりません。これらのノードは、アクセスされたときに暗黙的に作成されます。 このため、アクセスされる前に、子ノードがバッキングストアに存在するかどうかを実装が判断できない場合があります (たとえば、バッキングストアが到達不能な場合や、キャッシュされた情報が最新でない場合など)。このような状況でのノード変更イベントの生成は、特に定義されていません。
ncl - 追加する NodeChangeListener
NullPointerException - ncl が null の場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合removeNodeChangeListener(NodeChangeListener),
addPreferenceChangeListener(PreferenceChangeListener)public abstract void removeNodeChangeListener(NodeChangeListener ncl)
ncl - 削除する NodeChangeListener
IllegalArgumentException - ncl がこのノード上で登録された NodeChangeListener ではなかった場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合addNodeChangeListener(NodeChangeListener)
public abstract void exportNode(OutputStream os)
throws IOException,
BackingStoreException
この XML ドキュメントでは、次の DOCTYPE が宣言されます。
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">UTF-8 文字エンコーディングが使用されます。
このメソッドは通常の規則と異なり、このクラスの複数のメソッドを並行して実行すると、逐次実行した場合と同じ結果が生成されます。このメソッドの 1 回の呼び出しでこのノードの設定が並行して変更された場合、エクスポートされた設定がこのノードに含まれる設定と一致していないことがあります。 つまり、並行して行われた変更は、エクスポートされたデータに反映されていないことがあります。
os - XML ドキュメントの発行先の出力ストリーム
IOException - 指定された出力ストリームへの書き込み時に IOException が発生した場合
BackingStoreException - 設定データがバッキングストアから読み取れない場合
IllegalStateException - このノード (または上位ノード) が removeNode() メソッドによって削除された場合importPreferences(InputStream)
public abstract void exportSubtree(OutputStream os)
throws IOException,
BackingStoreException
この 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)
public static void importPreferences(InputStream is)
throws IOException,
InvalidPreferencesFormatException
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 Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2009 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。