Preferences Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
A node in a hierarchical collection of preference data.
[Android.Runtime.Register("java/util/prefs/Preferences", DoNotGenerateAcw=true)]
public abstract class Preferences : Java.Lang.Object[<Android.Runtime.Register("java/util/prefs/Preferences", DoNotGenerateAcw=true)>]
type Preferences = class
inherit Object- Inheritance
- Derived
- Attributes
Remarks
A node in a hierarchical collection of preference data. This class allows applications to store and retrieve user and system preference and configuration data. This data is stored persistently in an implementation-dependent backing store. Typical implementations include flat files, OS-specific registries, directory servers and SQL databases. The user of this class needn't be concerned with details of the backing store.
There are two separate trees of preference nodes, one for user preferences and one for system preferences. Each user has a separate user preference tree, and all users in a given system share the same system preference tree. The precise description of "user" and "system" will vary from implementation to implementation. Typical information stored in the user preference tree might include font choice, color choice, or preferred window location and size for a particular application. Typical information stored in the system preference tree might include installation configuration data for an application.
Nodes in a preference tree are named in a similar fashion to directories in a hierarchical file system. Every node in a preference tree has a node name (which is not necessarily unique), a unique absolute path name, and a path name relative to each ancestor including itself.
The root node has a node name of the empty string (""). Every other node has an arbitrary node name, specified at the time it is created. The only restrictions on this name are that it cannot be the empty string, and it cannot contain the slash character ('/').
The root node has an absolute path name of "/". Children of the root node have absolute path names of "/" + <node name>. All other nodes have absolute path names of <parent's absolute path name> + "/" + <node name>. Note that all absolute path names begin with the slash character.
A node n's path name relative to its ancestor a is simply the string that must be appended to a's absolute path name in order to form n's absolute path name, with the initial slash character (if present) removed. Note that: <ul> <li>No relative path names begin with the slash character. <li>Every node's path name relative to itself is the empty string. <li>Every node's path name relative to its parent is its node name (except for the root node, which does not have a parent). <li>Every node's path name relative to the root is its absolute path name with the initial slash character removed. </ul>
Note finally that: <ul> <li>No path name contains multiple consecutive slash characters. <li>No path name with the exception of the root's absolute path name ends in the slash character. <li>Any string that conforms to these two rules is a valid path name. </ul>
All of the methods that modify preferences data are permitted to operate asynchronously; they may return immediately, and changes will eventually propagate to the persistent backing store with an implementation-dependent delay. The flush method may be used to synchronously force updates to the backing store. Normal termination of the Java Virtual Machine will not result in the loss of pending updates -- an explicit flush invocation is not required upon termination to ensure that pending updates are made persistent.
All of the methods that read preferences from a Preferences object require the invoker to provide a default value. The default value is returned if no value has been previously set or if the backing store is unavailable. The intent is to allow applications to operate, albeit with slightly degraded functionality, even if the backing store becomes unavailable. Several methods, like flush, have semantics that prevent them from operating if the backing store is unavailable. Ordinary applications should have no need to invoke any of these methods, which can be identified by the fact that they are declared to throw BackingStoreException.
The methods in this class may be invoked concurrently by multiple threads in a single JVM without the need for external synchronization, and the results will be equivalent to some serial execution. If this class is used concurrently by multiple JVMs that store their preference data in the same backing store, the data store will not be corrupted, but no other guarantees are made concerning the consistency of the preference data.
This class contains an export/import facility, allowing preferences to be "exported" to an XML document, and XML documents representing preferences to be "imported" back into the system. This facility may be used to back up all or part of a preference tree, and subsequently restore from the backup.
The XML document has the following DOCTYPE declaration:
{@code
<!DOCTYPE preferences SYSTEM "http://java.sun.com/dtd/preferences.dtd">
}
Note that the system URI (http://java.sun.com/dtd/preferences.dtd) is not accessed when exporting or importing preferences; it merely serves as a string to uniquely identify the DTD, which is:
{@code
<?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 >
}
Every Preferences implementation must have an associated PreferencesFactory implementation. Every Java(TM) SE implementation must provide some means of specifying which PreferencesFactory implementation is used to generate the root preferences nodes. This allows the administrator to replace the default preferences implementation with an alternative implementation.
Implementation note: In Sun's JRE, the PreferencesFactory implementation is located as follows:
<ol>
<li>
If the system property java.util.prefs.PreferencesFactory is defined, then it is taken to be the fully-qualified name of a class implementing the PreferencesFactory interface. The class is loaded and instantiated; if this process fails then an unspecified error is thrown.
</li>
<li>
If a PreferencesFactory implementation class file has been installed in a jar file that is visible to the java.lang.ClassLoader#getSystemClassLoader system class loader, and that jar file contains a provider-configuration file named java.util.prefs.PreferencesFactory in the resource directory META-INF/services, then the first class name specified in that file is taken. If more than one such jar file is provided, the first one found will be used. The class is loaded and instantiated; if this process fails then an unspecified error is thrown.
</li>
<li>
Finally, if neither the above-mentioned system property nor an extension jar file is provided, then the system-wide default PreferencesFactory implementation for the underlying platform is loaded and instantiated.
</li>
</ol>
Added in 1.4.
Java documentation for java.util.prefs.Preferences.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Constructors
| Preferences() |
Sole constructor. |
| Preferences(IntPtr, JniHandleOwnership) |
A constructor used when creating managed representations of JNI objects; called by the runtime. |
Fields
| MaxKeyLength |
Maximum length of string allowed as a key (80 characters). |
| MaxNameLength |
Maximum length of a node name (80 characters). |
| MaxValueLength |
Maximum length of string allowed as a value (8192 characters). |
Properties
| Class |
Returns the runtime class of this |
| Handle |
The handle to the underlying Android instance. (Inherited from Object) |
| IsUserNode |
Returns whether this is a user preference node. |
| JniIdentityHashCode | (Inherited from Object) |
| JniPeerMembers | |
| PeerReference | (Inherited from Object) |
| ThresholdClass |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
| ThresholdType |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
Methods
| AbsolutePath() |
Returns this preference node's absolute path name. |
| AddNodeChangeListener(INodeChangeListener) |
Registers the specified listener to receive node change events for this node. |
| AddPreferenceChangeListener(IPreferenceChangeListener) |
Registers the specified listener to receive preference change events for this preference node. |
| ChildrenNames() |
Returns the names of the children of this preference node, relative to this node. |
| Clear() |
Removes all of the preferences (key-value associations) in this preference node. |
| Clone() |
Creates and returns a copy of this object. (Inherited from Object) |
| Dispose() | (Inherited from Object) |
| Dispose(Boolean) | (Inherited from Object) |
| Equals(Object) |
Indicates whether some other object is "equal to" this one. (Inherited from Object) |
| ExportNode(Stream) |
Emits on the specified output stream an XML document representing all of the preferences contained in this node (but not its descendants). |
| ExportNodeAsync(Stream) | |
| ExportSubtree(Stream) |
Emits an XML document representing all of the preferences contained in this node and all of its descendants. |
| ExportSubtreeAsync(Stream) | |
| Flush() |
Forces any changes in the contents of this preference node and its descendants to the persistent store. |
| FlushAsync() | |
| Get(String, String) |
Returns the value associated with the specified key in this preference node. |
| GetBoolean(String, Boolean) |
Returns the boolean value represented by the string associated with the specified key in this preference node. |
| GetByteArray(String, Byte[]) |
Returns the byte array value represented by the string associated with the specified key in this preference node. |
| GetDouble(String, Double) |
Returns the double value represented by the string associated with the specified key in this preference node. |
| GetFloat(String, Single) |
Returns the float value represented by the string associated with the specified key in this preference node. |
| GetHashCode() |
Returns a hash code value for the object. (Inherited from Object) |
| GetInt(String, Int32) |
Returns the int value represented by the string associated with the specified key in this preference node. |
| GetLong(String, Int64) |
Returns the long value represented by the string associated with the specified key in this preference node. |
| ImportPreferences(Stream) |
Imports all of the preferences represented by the XML document on the specified input stream. |
| ImportPreferencesAsync(Stream) | |
| JavaFinalize() |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object) |
| Keys() |
Returns all of the keys that have an associated value in this preference node. |
| Name() |
Returns this preference node's name, relative to its parent. |
| Node(String) |
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. |
| NodeExists(String) |
Returns true if the named preference node exists in the same tree as this node. |
| Notify() |
Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object) |
| NotifyAll() |
Wakes up all threads that are waiting on this object's monitor. (Inherited from Object) |
| Parent() |
Returns the parent of this preference node, or |
| Put(String, String) |
Associates the specified value with the specified key in this preference node. |
| PutBoolean(String, Boolean) |
Associates a string representing the specified boolean value with the specified key in this preference node. |
| PutByteArray(String, Byte[]) |
Associates a string representing the specified byte array with the specified key in this preference node. |
| PutDouble(String, Double) |
Associates a string representing the specified double value with the specified key in this preference node. |
| PutFloat(String, Single) |
Associates a string representing the specified float value with the specified key in this preference node. |
| PutInt(String, Int32) |
Associates a string representing the specified int value with the specified key in this preference node. |
| PutLong(String, Int64) |
Associates a string representing the specified long value with the specified key in this preference node. |
| Remove(String) |
Removes the value associated with the specified key in this preference node, if any. |
| RemoveNode() |
Removes this preference node and all of its descendants, invalidating any preferences contained in the removed nodes. |
| RemoveNodeChangeListener(INodeChangeListener) |
Removes the specified |
| RemovePreferenceChangeListener(IPreferenceChangeListener) |
Removes the specified preference change listener, so it no longer receives preference change events. |
| SetHandle(IntPtr, JniHandleOwnership) |
Sets the Handle property. (Inherited from Object) |
| 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 |
| SyncAsync() | |
| SystemNodeForPackage(Class) |
<strong>WARNING:</strong> On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. |
| SystemRoot() |
<strong>WARNING:</strong> On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. |
| ToArray<T>() | (Inherited from Object) |
| ToString() |
Returns a string representation of this preferences node,
as if computed by the expression: |
| UnregisterFromRuntime() | (Inherited from Object) |
| UserNodeForPackage(Class) |
<strong>WARNING:</strong> On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. |
| UserRoot() |
<strong>WARNING:</strong> On Android, the Preference nodes corresponding to the "system" and "user" preferences are stored in sections of the file system that are inaccessible to apps. |
| Wait() |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object) |
| Wait(Int64, Int32) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wait(Int64) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
Explicit Interface Implementations
| IJavaPeerable.Disposed() | (Inherited from Object) |
| IJavaPeerable.DisposeUnlessReferenced() | (Inherited from Object) |
| IJavaPeerable.Finalized() | (Inherited from Object) |
| IJavaPeerable.JniManagedPeerState | (Inherited from Object) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) | (Inherited from Object) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from Object) |
| IJavaPeerable.SetPeerReference(JniObjectReference) | (Inherited from Object) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |