The following features are supported:
A Preference instance is a hash map holding different values. It is stored alongside your application (SharedPreferences on Android, LocalStorage on GWT, on the desktop a Java Preferences file in a ".prefs" directory will be created, and on iOS an NSMutableDictionary will be written to the given file). CAUTION: On the desktop platform, all libgdx applications share the same ".prefs" directory. To avoid collisions use specific names like "com.myname.game1.settings" instead of "settings"
Changes to a preferences instance will be cached in memory until {@link #flush()} is invoked.
Use {@link Application#getPreferences(String)} to look up a specific preferences instance. Note that on several backends thepreferences name will be used as the filename, so make sure the name is valid for a filename.
@author mzechnerUser preferences are placed into session scope by this app's implementation of {@link hirondelle.web4j.security.LoginTasks}.
<?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 {@link PreferencesFactory} implementation. Every Java(TM) SE implementation must providesome 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:
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.
If a PreferencesFactory implementation class file has been installed in a jar file that is visible to the {@link 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.
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.
boolean = falsedouble = 0.0float = 0.0fint = 0long = 0LString = "" (the empty string)Internally, all properties values (in both layers) are stored as strings. Standard conversions to and from numeric and boolean types are performed on demand.
The typical usage is to establish the defaults for all known properties and then restore previously stored values for properties whose values were explicitly set. The existing settings can be changed and new properties can be set (setValue). If the values specified is the same as the default value, the explicit setting is deleted from the top layer. It is also possible to reset a property value back to the default value using setToDefault. After the properties have been modified, the properties with explicit settings are written to disk. The default values are never saved. This two-tiered approach to saving and restoring property setting minimizes the number of properties that need to be persisted; indeed, the normal starting state does not require storing any properties at all. It also makes it easy to use different default settings in different environments while maintaining just those property settings the user has adjusted.
A property change event is reported whenever a property's value actually changes (either through setValue, setToDefault). Note, however, that manipulating default values (with setDefault) does not cause any events to be reported.
Clients may instantiate this class. This class was not designed to be subclassed.
The implementation is based on a pair of internal java.util.Properties objects, one holding explicitly set values (set using setValue), the other holding the default values (set using setDefaultValue). The load and store methods persist the non-default property values to streams (the default values are not saved).
If a client sets a default value to be equivalent to the default-default for that type, the value is still known to the preference store as having a default value. That is, the name will still be returned in the result of the defaultPropertyNames and contains methods.
Initial Date: 05.08.2005
@author Felix
This interface allows applications to store and retrieve user and system preference 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.
For each bundle, there is a separate tree of nodes for each user, and one for system preferences. The precise description of "user" and "system" will vary from one bundle to another. Typical information stored in the user preference tree might include font choice, and color choice for a bundle which interacts with the user via a servlet. Typical information stored in the system preference tree might include installation data, or things like high score information for a game program.
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 {@code String} object (""). Everyother 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 {@code "/"}. Children of the root node have absolute path names of {@code "/" + } <node name> .All other nodes have absolute path names of <parent's absolute path name> {@code + "/" + } <node name> . Note that allabsolute 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:
Note finally that:
Each {@code Preference} node has zero or more properties associated with it,where a property consists of a name and a value. The bundle writer is free to choose any appropriate names for properties. Their values can be of type {@code String}, {@code long}, {@code int}, {@code boolean}, {@code byte[]}, {@code float}, or {@code double} but they can always be accessed as if theywere {@code String} objects.
All node name and property name comparisons are case-sensitive.
All of the methods that modify preference 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 {@code flush} method may be used to synchronously force updates tothe backing store.
Implementations must automatically attempt to flush to the backing store any pending updates for a bundle's preferences when the bundle is stopped or otherwise ungets the Preferences Service.
The methods in this class may be invoked concurrently by multiple threads in a single Java Virtual Machine (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. @noimplement @author $Id: faefeec3c75c0a45324035226f71728f69358cd4 $
| |
| |
| |