public interface IPreferences
This is very close to the native Java preferences with the additional feature of "scoping" (and some other minor deviations).
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
SCOPE_DEFAULT
The non - persistent default settings
|
static java.lang.String |
SCOPE_GLOBAL
Preferences for all users
|
static java.lang.String |
SCOPE_INSTALLATION
The preferences provided with the instrument installation
|
static java.lang.String |
SCOPE_TEAM
Preferences for a dedicated team of users
|
static java.lang.String |
SCOPE_USER
Preferences for a specific user
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
absolutePath()
Returns this preference node's absolute path name.
|
IPreferences[] |
children()
The array of all child preferences.
|
java.lang.String[] |
childrenNames()
Returns the names of the children of this preference node, relative to
this node.
|
void |
clear()
Removes all of the preferences (key-value associations) in this
preference node.
|
void |
flush()
Forces any changes in the contents of this preference node and its
descendants to the persistent store.
|
java.lang.String |
get(java.lang.String name)
Returns the current value of the string-valued preference with the given
name.
|
java.lang.String |
get(java.lang.String key,
java.lang.String def)
Returns the value associated with the specified key in this preference
node.
|
boolean |
getBoolean(java.lang.String name)
Returns the current value of the boolean-valued preference with the given
name.
|
boolean |
getBoolean(java.lang.String key,
boolean def)
Returns the boolean value represented by the string associated with the
specified key in this preference node.
|
byte[] |
getByteArray(java.lang.String key,
byte[] def)
Returns the byte array value represented by the string associated with
the specified key in this preference node.
|
double |
getDouble(java.lang.String name)
Returns the current value of the double-valued preference with the given
name.
|
double |
getDouble(java.lang.String key,
double def)
Returns the double value represented by the string associated with the
specified key in this preference node.
|
float |
getFloat(java.lang.String name)
Returns the current value of the float-valued preference with the given
name.
|
float |
getFloat(java.lang.String key,
float def)
Returns the float value represented by the string associated with the
specified key in this preference node.
|
int |
getInt(java.lang.String name)
Returns the current value of the integer-valued preference with the given
name.
|
int |
getInt(java.lang.String key,
int def)
Returns the int value represented by the string associated with the
specified key in this preference node.
|
long |
getLong(java.lang.String name)
Returns the current value of the long-valued preference with the given
name.
|
long |
getLong(java.lang.String key,
long def)
Returns the long value represented by the string associated with the
specified key in this preference node.
|
java.lang.String[] |
keys()
Returns all of the keys that have an associated value in this preference
node.
|
java.lang.String |
name()
Returns this preference node's name, relative to its parent.
|
IPreferences |
node(java.lang.String pathName)
Returns the named preference node in the same tree as this node, creating
it and any of its ancestors if they do not already exist.
|
boolean |
nodeExists(java.lang.String pathName)
Returns true if the named preference node exists in the same tree as this
node.
|
IPreferences |
parent()
Returns the parent of this preference node, or null if this is
the root.
|
java.util.Map<java.lang.String,java.lang.String> |
properties()
A map of all property mappings in this
IPreferences node. |
void |
put(java.lang.String name,
boolean value)
Sets the current value of the boolean-valued preference with the given
name.
|
void |
put(java.lang.String key,
byte[] value)
Associates a string representing the specified byte array with the
specified key in this preference node.
|
void |
put(java.lang.String name,
double value)
Sets the current value of the double-valued preference with the given
name.
|
void |
put(java.lang.String name,
float value)
Sets the current value of the float-valued preference with the given
name.
|
void |
put(java.lang.String name,
int value)
Sets the current value of the integer-valued preference with the given
name.
|
void |
put(java.lang.String name,
long value)
Sets the current value of the long-valued preference with the given name.
|
void |
put(java.lang.String name,
java.lang.String value)
Sets the current value of the string-valued preference with the given
name.
|
void |
putBoolean(java.lang.String key,
boolean value)
Set the current value.
|
void |
putByteArray(java.lang.String key,
byte[] value)
Set the current value.
|
void |
putDouble(java.lang.String key,
double value)
Set the current value.
|
void |
putFloat(java.lang.String key,
float value)
Set the current value.
|
void |
putInt(java.lang.String key,
int value)
Set the current value.
|
void |
putLong(java.lang.String key,
long value)
Set the current value.
|
void |
remove(java.lang.String key)
Removes the value associated with the specified key in this preference
node, if any.
|
void |
removeNode()
Removes this preference node and all of its descendants, invalidating any
preferences contained in the removed nodes.
|
IPreferences |
restrict(java.lang.String scopeName)
Create a new IPreferences object whose scopes include all scopes from the
receiver before and including "scopeName".
|
void |
sync()
Ensures that future reads from this preference node and its descendants
reflect any changes that were committed to the persistent store (from any
VM) prior to the sync invocation.
|
static final java.lang.String SCOPE_DEFAULT
static final java.lang.String SCOPE_INSTALLATION
static final java.lang.String SCOPE_GLOBAL
static final java.lang.String SCOPE_TEAM
static final java.lang.String SCOPE_USER
java.lang.String absolutePath()
IPreferences[] children()
java.lang.String[] childrenNames() throws java.util.prefs.BackingStoreException
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.void clear() throws java.util.prefs.BackingStoreException
If this implementation supports stored defaults, and this node in the preferences hierarchy contains any such defaults, the stored defaults will be "exposed" by this call, in the sense that they will be returned by succeeding calls to get.
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.removeNode()
void flush() throws java.util.prefs.BackingStoreException
Implementations are free to flush changes into the persistent store at any time. They do not need to wait for this method to be called.
When a flush occurs on a newly created node, it is made persistent, as are any ancestors (and descendants) that have yet to be made persistent. Note however that any preference value changes in ancestors are not guaranteed to be made persistent.
If this method is invoked on a node that has been removed with the
removeNode()
method, flushSpi() is invoked on this node, but not
on others.
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.sync()
java.lang.String get(java.lang.String name)
""
) if there is no preference with the given name, or if the current value
cannot be treated as a string.name
- the name of the preferencejava.lang.String get(java.lang.String key, java.lang.String def)
Some implementations may store default values in their backing stores. If there is no value associated with the specified key but there is such a stored default, it is returned in preference to the specified default.
key
- key whose associated value is to be returned.def
- the value to be returned in the event that this preference
node has no value associated with key.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null. (A null value for
def is permitted.)boolean getBoolean(java.lang.String name)
false
) if there is
no preference with the given name, or if the current value cannot be
treated as a boolean.name
- the name of the preferenceboolean getBoolean(java.lang.String key, boolean def)
putBoolean(java.lang.String, boolean)
.
Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is something other than "true" or "false", ignoring case.
If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is something other than "true" or "false", ignoring case, in which case the specified default is used.
key
- key whose associated value is to be returned as a boolean.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as a boolean, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null.get(String,String)
,
putBoolean(String,boolean)
byte[] getByteArray(java.lang.String key, byte[] def)
putByteArray(java.lang.String, byte[])
.
Returns the specified default if there is no value associated with the key, the backing store is inaccessible, or if the associated value is not a valid Base64 encoded byte array (as defined above).
If the implementation supports stored defaults and such a default exists and is accessible, it is used in preference to the specified default, unless the stored default is not a valid Base64 encoded byte array (as defined above), in which case the specified default is used.
key
- key whose associated value is to be returned as a byte array.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as a byte array, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null. (A null value for
def is permitted.)get(String,String)
,
putByteArray(String,byte[])
double getDouble(java.lang.String name)
0.0
) if there is no
preference with the given name, or if the current value cannot be treated
as a double.name
- the name of the preferencedouble getDouble(java.lang.String key, double def)
Double.parseDouble(String)
. Returns the specified
default if there is no value associated with the key, the backing store
is inaccessible, or if Double.parseDouble(String) would throw a
NumberFormatException
if the associated value were passed. This
method is intended for use in conjunction with putDouble(java.lang.String, double)
.
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a double with Double.parseDouble, this double is returned in preference to the specified default.
key
- key whose associated value is to be returned as a double.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as a double, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null.putDouble(String,double)
,
get(String,String)
float getFloat(java.lang.String name)
0.0f
) if there is
no preference with the given name, or if the current value cannot be
treated as a float.name
- the name of the preferencefloat getFloat(java.lang.String key, float def)
Float.parseFloat(String)
. Returns the specified
default if there is no value associated with the key, the backing store
is inaccessible, or if Float.parseFloat(String) would throw a
NumberFormatException
if the associated value were passed. This
method is intended for use in conjunction with putFloat(java.lang.String, float)
.
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a float with Float.parseFloat, this float is returned in preference to the specified default.
key
- key whose associated value is to be returned as a float.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as a float, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null.putFloat(String,float)
,
get(String,String)
int getInt(java.lang.String name)
0
) if there is no
preference with the given name, or if the current value cannot be treated
as an integer.name
- the name of the preferenceint getInt(java.lang.String key, int def)
Integer.parseInt(String)
. Returns the specified
default if there is no value associated with the key, the backing store
is inaccessible, or if Integer.parseInt(String) would throw a
NumberFormatException
if the associated value were passed. This
method is intended for use in conjunction with putInt(java.lang.String, int)
.
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to an int with Integer.parseInt, this int is returned in preference to the specified default.
key
- key whose associated value is to be returned as an int.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as an int, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null.putInt(String,int)
,
get(String,String)
long getLong(java.lang.String name)
0L
) if there is no
preference with the given name, or if the current value cannot be treated
as a long.name
- the name of the preferencelong getLong(java.lang.String key, long def)
Long.parseLong(String)
. Returns the specified default if
there is no value associated with the key, the backing store is
inaccessible, or if Long.parseLong(String) would throw a
NumberFormatException
if the associated value were passed. This
method is intended for use in conjunction with putLong(java.lang.String, long)
.
If the implementation supports stored defaults and such a default exists, is accessible, and could be converted to a long with Long.parseLong, this long is returned in preference to the specified default.
key
- key whose associated value is to be returned as a long.def
- the value to be returned in the event that this preference
node has no value associated with key or the
associated value cannot be interpreted as a long, or the
backing store is inaccessible.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.NullPointerException
- if key is null.putLong(String,long)
,
get(String,String)
java.lang.String[] keys() throws java.util.prefs.BackingStoreException
If the implementation supports stored defaults and there are any such defaults at this node that have not been overridden, by explicit preferences, the defaults are returned in the array in addition to any explicit preferences.
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.lang.String name()
IPreferences node(java.lang.String pathName)
If the returned node did not exist prior to this call, this node and any ancestors that were created by this call are not guaranteed to become permanent until the flush method is called on the returned node (or one of its ancestors or descendants).
pathName
- the path name of the preference node to return.java.lang.IllegalArgumentException
- if the path name is invalid (i.e., it contains multiple
consecutive slash characters, or ends with a slash character
and is more than one character long).java.lang.NullPointerException
- if path name is null.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.flush()
boolean nodeExists(java.lang.String pathName) throws java.util.prefs.BackingStoreException
If this node (or an ancestor) has already been removed with the
removeNode()
method, it is legal to invoke this method,
but only with the path name ""; the invocation will return
false. Thus, the idiom p.nodeExists("") may be used to
test whether p has been removed.
pathName
- the path name of the node whose existence is to be checked.java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.java.lang.IllegalArgumentException
- if the path name is invalid (i.e., it contains multiple
consecutive slash characters, or ends with a slash character
and is more than one character long).java.lang.NullPointerException
- if path name is null. s *java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method and pathName is not the
empty string ("").IPreferences parent()
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.java.util.Map<java.lang.String,java.lang.String> properties()
IPreferences
node.IPreferences
node.void put(java.lang.String name, boolean value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid put(java.lang.String key, byte[] value)
getByteArray(java.lang.String, byte[])
.key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.java.lang.NullPointerException
- if key or value is null.java.lang.IllegalArgumentException
- if key.length() exceeds MAX_KEY_LENGTH or if value.length
exceeds MAX_VALUE_LENGTH*3/4.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.getByteArray(String,byte[])
,
get(String,String)
void put(java.lang.String name, double value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid put(java.lang.String name, float value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid put(java.lang.String name, int value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid put(java.lang.String name, long value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid put(java.lang.String name, java.lang.String value)
name
- the name of the preferencevalue
- the new current value of the preferencevoid putBoolean(java.lang.String key, boolean value)
key
- value
- void putByteArray(java.lang.String key, byte[] value)
key
- value
- void putDouble(java.lang.String key, double value)
key
- value
- void putFloat(java.lang.String key, float value)
key
- value
- void putInt(java.lang.String key, int value)
key
- value
- void putLong(java.lang.String key, long value)
key
- value
- void remove(java.lang.String key)
If this implementation supports stored defaults, and there is such a default for the specified preference, the stored default will be "exposed" by this call, in the sense that it will be returned by a succeeding call to get.
key
- key whose mapping is to be removed from the preference node.java.lang.NullPointerException
- if key is null.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.void removeNode() throws java.util.prefs.BackingStoreException
name()
, absolutePath()
, flush()
or nodeExists("")
on the
corresponding Preferences instance will fail with an
IllegalStateException. (The methods defined on Object
can still be invoked on a node after it has been removed; they will not
throw IllegalStateException.)
The removal is not guaranteed to be persistent until the flush method is called on this node (or an ancestor).
If this implementation supports stored defaults, removing a node exposes any stored defaults at or below this node. Thus, a subsequent call to nodeExists on this node's path name may return true, and a subsequent call to node on this path name may may return a (different) Preferences instance representing a non-empty collection of preferences and/or children.
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.java.lang.IllegalStateException
- if this node (or an ancestor) has already been removed with
the removeNode()
method.java.lang.UnsupportedOperationException
- if this method is invoked on the root node.flush()
IPreferences restrict(java.lang.String scopeName)
scopeName
- void sync() throws java.util.prefs.BackingStoreException
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the
backing store, or inability to communicate with it.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with the
removeNode()
method.flush()