Interface IPreferences
-
- All Known Implementing Classes:
NullPreferences
,PreferencesAdapter
public interface IPreferences
Yet another preferences abstraction.This is very close to the native Java preferences with the additional feature of "scoping" (and some other minor deviations).
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
SCOPE_DEFAULT
The non - persistent default settingsstatic java.lang.String
SCOPE_GLOBAL
Preferences for all usersstatic java.lang.String
SCOPE_INSTALLATION
The preferences provided with the instrument installationstatic java.lang.String
SCOPE_TEAM
Preferences for a dedicated team of usersstatic java.lang.String
SCOPE_USER
Preferences for a specific user
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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 thisIPreferences
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.
-
-
-
Field Detail
-
SCOPE_DEFAULT
static final java.lang.String SCOPE_DEFAULT
The non - persistent default settings- See Also:
- Constant Field Values
-
SCOPE_INSTALLATION
static final java.lang.String SCOPE_INSTALLATION
The preferences provided with the instrument installation- See Also:
- Constant Field Values
-
SCOPE_GLOBAL
static final java.lang.String SCOPE_GLOBAL
Preferences for all users- See Also:
- Constant Field Values
-
SCOPE_TEAM
static final java.lang.String SCOPE_TEAM
Preferences for a dedicated team of users- See Also:
- Constant Field Values
-
SCOPE_USER
static final java.lang.String SCOPE_USER
Preferences for a specific user- See Also:
- Constant Field Values
-
-
Method Detail
-
absolutePath
java.lang.String absolutePath()
Returns this preference node's absolute path name.- Returns:
- this preference node's absolute path name.
-
children
IPreferences[] children()
The array of all child preferences.- Returns:
- The array of all child preferences.
-
childrenNames
java.lang.String[] childrenNames() throws java.util.prefs.BackingStoreException
Returns the names of the children of this preference node, relative to this node. (The returned array will be of size zero if this node has no children.)- Returns:
- the names of the children of this preference node.
- Throws:
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.
-
clear
void clear() throws java.util.prefs.BackingStoreException
Removes all of the preferences (key-value associations) in this preference node. This call has no effect on any descendants of this node.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.
- Throws:
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 theremoveNode()
method.- See Also:
removeNode()
-
flush
void flush() throws java.util.prefs.BackingStoreException
Forces any changes in the contents of this preference node and its descendants to the persistent store. Once this method returns successfully, it is safe to assume that all changes made in the subtree rooted at this node prior to the method invocation have become permanent.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.- Throws:
java.util.prefs.BackingStoreException
- if this operation cannot be completed due to a failure in the backing store, or inability to communicate with it.- See Also:
sync()
-
get
java.lang.String get(java.lang.String name)
Returns the current value of the string-valued preference with the given name. Returns the default-default value (the empty string""
) if there is no preference with the given name, or if the current value cannot be treated as a string.- Parameters:
name
- the name of the preference- Returns:
- the string-valued preference
-
get
java.lang.String get(java.lang.String key, java.lang.String def)
Returns the value associated with the specified key in this preference node. Returns the specified default if there is no value associated with the key, or the backing store is inaccessible.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.
- Parameters:
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.- Returns:
- the value associated with key, or def if no value is associated with key, or the backing store is inaccessible.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null. (A null value for def is permitted.)
-
getBoolean
boolean getBoolean(java.lang.String name)
Returns the current value of the boolean-valued preference with the given name. Returns the default-default value (false
) if there is no preference with the given name, or if the current value cannot be treated as a boolean.- Parameters:
name
- the name of the preference- Returns:
- the boolean-valued preference
-
getBoolean
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. Valid strings are "true", which represents true, and "false", which represents false. Case is ignored, so, for example, "TRUE" and "False" are also valid. This method is intended for use in conjunction withputBoolean(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.
- Parameters:
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.- Returns:
- the boolean value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a boolean.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null.- See Also:
get(String,String)
,putBoolean(String,boolean)
-
getByteArray
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. Valid strings are Base64 encoded binary data, as defined in RFC 2045, Section 6.8, with one minor change: the string must consist solely of characters from the Base64 Alphabet; no newline characters or extraneous characters are permitted. This method is intended for use in conjunction withputByteArray(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.
- Parameters:
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.- Returns:
- the byte array value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a byte array.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null. (A null value for def is permitted.)- See Also:
get(String,String)
,putByteArray(String,byte[])
-
getDouble
double getDouble(java.lang.String name)
Returns the current value of the double-valued preference with the given name. Returns the default-default value (0.0
) if there is no preference with the given name, or if the current value cannot be treated as a double.- Parameters:
name
- the name of the preference- Returns:
- the double-valued preference
-
getDouble
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. The string is converted to an integer as byDouble.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 aNumberFormatException
if the associated value were passed. This method is intended for use in conjunction withputDouble(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.
- Parameters:
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.- Returns:
- the double value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a double.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null.- See Also:
putDouble(String,double)
,get(String,String)
-
getFloat
float getFloat(java.lang.String name)
Returns the current value of the float-valued preference with the given name. Returns the default-default value (0.0f
) if there is no preference with the given name, or if the current value cannot be treated as a float.- Parameters:
name
- the name of the preference- Returns:
- the float-valued preference
-
getFloat
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. The string is converted to an integer as byFloat.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 aNumberFormatException
if the associated value were passed. This method is intended for use in conjunction withputFloat(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.
- Parameters:
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.- Returns:
- the float value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a float.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null.- See Also:
putFloat(String,float)
,get(String,String)
-
getInt
int getInt(java.lang.String name)
Returns the current value of the integer-valued preference with the given name. Returns the default-default value (0
) if there is no preference with the given name, or if the current value cannot be treated as an integer.- Parameters:
name
- the name of the preference- Returns:
- the int-valued preference
-
getInt
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. The string is converted to an integer as byInteger.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 aNumberFormatException
if the associated value were passed. This method is intended for use in conjunction withputInt(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.
- Parameters:
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.- Returns:
- the int value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as an int.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null.- See Also:
putInt(String,int)
,get(String,String)
-
getLong
long getLong(java.lang.String name)
Returns the current value of the long-valued preference with the given name. Returns the default-default value (0L
) if there is no preference with the given name, or if the current value cannot be treated as a long.- Parameters:
name
- the name of the preference- Returns:
- the long-valued preference
-
getLong
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. The string is converted to a long as byLong.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 aNumberFormatException
if the associated value were passed. This method is intended for use in conjunction withputLong(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.
- Parameters:
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.- Returns:
- the long value represented by the string associated with key in this preference node, or def if the associated value does not exist or cannot be interpreted as a long.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.java.lang.NullPointerException
- if key is null.- See Also:
putLong(String,long)
,get(String,String)
-
keys
java.lang.String[] keys() throws java.util.prefs.BackingStoreException
Returns all of the keys that have an associated value in this preference node. (The returned array will be of size zero if this node has no preferences.)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.
- Returns:
- an array of the keys that have an associated value in this preference node.
- Throws:
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 theremoveNode()
method.
-
name
java.lang.String name()
Returns this preference node's name, relative to its parent.- Returns:
- this preference node's name, relative to its parent.
-
node
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. Accepts a relative or absolute path name. Relative path names (which do not begin with the slash character ('/')) are interpreted relative to this preference node.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).
- Parameters:
pathName
- the path name of the preference node to return.- Returns:
- the specified preference node.
- Throws:
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 theremoveNode()
method.- See Also:
flush()
-
nodeExists
boolean nodeExists(java.lang.String pathName) throws java.util.prefs.BackingStoreException
Returns true if the named preference node exists in the same tree as this node. Relative path names (which do not begin with the slash character ('/')) are interpreted relative to this preference node.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.- Parameters:
pathName
- the path name of the node whose existence is to be checked.- Returns:
- true if the specified node exists.
- Throws:
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 theremoveNode()
method and pathName is not the empty string ("").
-
parent
IPreferences parent()
Returns the parent of this preference node, or null if this is the root.- Returns:
- the parent of this preference node.
- Throws:
java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
properties
java.util.Map<java.lang.String,java.lang.String> properties()
A map of all property mappings in thisIPreferences
node.- Returns:
- A map of all property mappings in this
IPreferences
node.
-
put
void put(java.lang.String name, boolean value)
Sets the current value of the boolean-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
put
void put(java.lang.String key, byte[] value)
Associates a string representing the specified byte array with the specified key in this preference node. The associated string is the Base64 encoding of the byte array, as defined in RFC 2045, Section 6.8, with one minor change: the string will consist solely of characters from the Base64 Alphabet; it will not contain any newline characters. Note that the maximum length of the byte array is limited to three quarters of MAX_VALUE_LENGTH so that the length of the Base64 encoded String does not exceed MAX_VALUE_LENGTH. This method is intended for use in conjunction withgetByteArray(java.lang.String, byte[])
.- Parameters:
key
- key with which the string form of value is to be associated.value
- value whose string form is to be associated with key.- Throws:
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 theremoveNode()
method.- See Also:
getByteArray(String,byte[])
,get(String,String)
-
put
void put(java.lang.String name, double value)
Sets the current value of the double-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
put
void put(java.lang.String name, float value)
Sets the current value of the float-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
put
void put(java.lang.String name, int value)
Sets the current value of the integer-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
put
void put(java.lang.String name, long value)
Sets the current value of the long-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
put
void put(java.lang.String name, java.lang.String value)
Sets the current value of the string-valued preference with the given name.- Parameters:
name
- the name of the preferencevalue
- the new current value of the preference
-
putBoolean
void putBoolean(java.lang.String key, boolean value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
putByteArray
void putByteArray(java.lang.String key, byte[] value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
putDouble
void putDouble(java.lang.String key, double value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
putFloat
void putFloat(java.lang.String key, float value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
putInt
void putInt(java.lang.String key, int value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
putLong
void putLong(java.lang.String key, long value)
Set the current value. This is for drop in compatibility to Java platform preferences.- Parameters:
key
-value
-
-
remove
void remove(java.lang.String key)
Removes the value associated with the specified key in this preference node, if any.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.
- Parameters:
key
- key whose mapping is to be removed from the preference node.- Throws:
java.lang.NullPointerException
- if key is null.java.lang.IllegalStateException
- if this node (or an ancestor) has been removed with theremoveNode()
method.
-
removeNode
void removeNode() throws java.util.prefs.BackingStoreException
Removes this preference node and all of its descendants, invalidating any preferences contained in the removed nodes. Once a node has been removed, attempting any method other thanname()
,absolutePath()
,flush()
ornodeExists("")
on the corresponding Preferences instance will fail with an IllegalStateException. (The methods defined onObject
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.
- Throws:
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 theremoveNode()
method.java.lang.UnsupportedOperationException
- if this method is invoked on the root node.- See Also:
flush()
-
restrict
IPreferences restrict(java.lang.String scopeName)
Create a new IPreferences object whose scopes include all scopes from the receiver before and including "scopeName".- Parameters:
scopeName
-- Returns:
- a new IPreferences object whose scopes include all scopes from the receiver before and including "scopeName".
-
sync
void sync() throws java.util.prefs.BackingStoreException
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. As a side-effect, forces any changes in the contents of this preference node and its descendants to the persistent store, as if the flush method had been invoked on this node.- Throws:
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 theremoveNode()
method.- See Also:
flush()
-
-