The preferences are a flat set of key-value pairs. The keys are
always strings, while the values can be complex objects (with complex
XML representation). It is very easy to use or add simple preferences
via the classes {@link
com.infopark.cm.htmlgui.browse.preference.BooleanPreference}, {@link
com.infopark.cm.htmlgui.browse.preference.StringPreference}, {@link
com.infopark.cm.htmlgui.browse.preference.EnumPreference}, and {@link
com.infopark.cm.htmlgui.browse.preference.IntegerPreference}. Even
lists and maps can be easily created with {@link
com.infopark.cm.htmlgui.browse.preference.ListPreference} and {@link
com.infopark.cm.htmlgui.browse.preference.MapPreference}. Support for
"black box" XML data, that is processed separately, is provided by
{@link com.infopark.cm.htmlgui.browse.preference.XmlPreference}.
Each {@link com.infopark.cm.htmlgui.browse.preference.Preference} may
either belong to a {@link
com.infopark.cm.htmlgui.browse.preference.Role}, or it is a
non-role, "global" preferences. Still, all preferences are per
user. The Role
provides defaults if the value is not
defined in the user config. If the value is marked as "fixed" in the
current Role
the value stored in the user config is
even ignored. Note that "fixedness" and this shadowing rule only
applies to the "top-level" preferences, because the innards of complex
preference values are handled by the respective {@link
com.infopark.cm.htmlgui.browse.preference.Preference} implementation.
All public access to a preference must go through the methods provided by the session-singleton {@link com.infopark.cm.htmlgui.browse.preference.Preferences} instance. Trying to access a value by an unknown key will always cause an exception.
This means in detail:
Preference
knows how to build the
value, for example, the {@link
com.infopark.cm.htmlgui.browse.preference.IntegerPreference} has got
an Integer
as value. If you want to add a new preference,
the following steps should be followed:
String
is sufficient. In the latter
case you can simply use a class like {@link
com.infopark.cm.htmlgui.browse.preference.StringPreference} to create
your preference with a name.
Role
it must implement the {@link
com.infopark.cm.htmlgui.browse.preference.RolePreference}
interface, which basically means it must be able to deeply clone
itself.
guiConfig.xml
if it is part of a preference,
guiPreferences.xml
otherwise.