public class TLcyPreferencesTool extends ALcyTool
Support class for working with preferences. It offers three kinds of preferences, which are stored in the correct preferences store of the Lucy backend at the appropriate times:
TLcyPreferencesManager.getSystemPreferences()
for details.TLcyPreferencesManager.getCurrentUserPreferences()
for details. String longPrefix = "com.yourcompany.YourAddOn."; // only used for TLcyPreferencesManager
String shortPrefix = "YourAddOn."; // always used
TLcyPreferencesTool tool = new TLcyPreferencesTool(pathToConfigFile, longPrefix, shortPrefix);
tool.plugInto(aLucyEnv);
ALcyProperties compositeWorkspacePreferences = tool.getCompositeWorkspacePreferences();
// retrieve a preference from the workspace, user, or system preferences (in that order)
System.out.println(compositeWorkspacePreferences.getString(shortPrefix + "myKey", "a value"));
// save a preference to the workspace
compositeWorkspacePreferences.putString(shortPrefix + "myKey", "a different value");
Preferences saved in the workspace preferences of this tool are automatically stored in and
restored from the workspace. The keys and String
values of the preferences are kept
as is, the Object
values are converted to String
s using the composite
property converter (see below).
During workspace decoding, the workspace preferences are restored on the Swing Thread (the Event Dispatch Thread).
Preferences saved in the user- and system preferences of this tool will automatically be saved
in the user- and system preferences of the TLcyPreferencesManager
. The
String
values of the preferences are kept as is and the Object
values
converted to String
s as with the workspace preferences, but the keys are prefixed
with the long prefix of this tool.
The workspace preferences are stored in the workspace when the workspace is encoded and decoded, and the user and system preferences are stored when the tool is unplugged from the Lucy backend or when Lucy is shut down. This tool only saves those preferences that are changed with respect to the initial configuration.
The user and system preferences of TLcyPreferencesManager
are String
based, and for workspaces this TLcyPreferencesTool
also saves all workspace
preferences as String
s. The user, system and workspace preferences of this
TLcyPreferencesTool
however are all ALcyProperties
instances which can
accept any kind of object as value for a preference. When the preferences need to be saved, to
the workspace or to the user or system preferences of the TLcyPreferencesManager
,
this TLcyPreferencesTool
uses its TLcyCompositePropertyConverter
to
convert these values to String
s. If you need to save an Object
preference,
add an appropriate ILcyPropertyConverter
to the composite property converter.
It can also be useful to have access to the ALcyWorkspaceCodec
when converting
Object
properties to String
properties, as the
ALcyWorkspaceCodec
can give a String
identifier for some objects when
encoding a workspace. The ALcyPreferencesPropertyConverter
is an abstract class that
can retrieve the ALcyWorkspaceCodec
from the TLcyPreferencesTool
during
workspace decoding. Note that the ALcyWorkspaceCodec
is only available when the
ALcyPreferencesPropertyConverter
is being used to convert an
ALcyProperties
instance for workspace encoding. In other cases, the
ALcyWorkspaceCodec
is not available and is null
.
It is up to you to decide which preferences are system preferences, user preferences or workspace preferences. This tool only makes the distinction between these preferences with regards to priority: the workspace preferences in this tool have a higher priority than the user preferences, which in turn have a higher priority than the system preferences. This means that when a preference with the same key is available in the user preferences and in the workspace preferences, the value of the preference in the workspace preferences should be considered as the correct value.
The TLcyPreferencesTool
implements this priority in its composite preferences.
getCompositeWorkspacePreferences()
returns an ALcyProperties
instance that
tries to retrieve a value for a given key first in the workspace preferences. When the requested
preference is not available in the workspace preferences, only then will it search in the user
preferences. Finally, if the preference is not available in the user preferences either, the
system preferences are searched. All preferences saved in this composite
ALcyProperties
are saved in the workspace preferences of tool.
The method getCompositeUserPreferences()
is similar, only the returned
ALcyProperties
starts looking for a preference in the user preferences and never
looks in the workspace preferences. All preferences written to these ALcyProperties
are stored in the user preferences of this tool.
Constructor and Description |
---|
TLcyPreferencesTool(ALcyProperties aSystemDefaults,
ALcyProperties aUserDefaults,
String aConfigSource,
String aLongPrefix,
String aShortPrefix)
Creates a new
TLcyPreferencesTool that is initialised with optional (hard
coded) defaults for system and user preferences, and that optionally parses a configuration
source. |
TLcyPreferencesTool(String aConfigSource,
Class aClass)
Deprecated.
Better use the constructor with explicit long and short prefix, to avoid any
confusion.
Creates a new
TLcyPreferencesTool that parses the given configuration source. |
TLcyPreferencesTool(String aConfigSource,
String aLongPrefix,
String aShortPrefix)
Creates a new
TLcyPreferencesTool that parses the given configuration source. |
Modifier and Type | Method and Description |
---|---|
TLcyCompositePropertyConverter |
getCompositePropertyConverter()
Returns the composite property converter of this tool.
|
ALcyProperties |
getCompositeUserPreferences()
|
ALcyProperties |
getCompositeWorkspacePreferences()
|
ALcyProperties |
getSystemPreferences()
Returns the system preferences of this tool.
|
ALcyProperties |
getUserPreferences()
Returns the user preferences of this tool.
|
ALcyProperties |
getWorkspacePreferences()
Returns the workspace preferences of this tool.
|
boolean |
isTraceOn()
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
plugInto(ILcyLucyEnv aLucyEnv)
Reads the initial system and user preferences from the configuration source and performs the
necessary work to automatically save the different kinds of preferences in the correct
preferences stores.
|
static void |
setClassTraceOn(boolean aClassTraceOn)
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
setTraceOn(boolean aTraceOn)
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
setWorkspaceCodec(ALcyWorkspaceCodec aWorkspaceCodec) |
void |
unplugFrom(ILcyLucyEnv aLucyEnv)
Saves the user and system preferences of this tool to the user and system preferences of the
TLcyPreferencesManager . |
addPropertyChangeListener, addPropertyChangeListener, assertPlugged, firePropertyChange, getLongPrefix, getLongPrefixWithClassName, getLucyEnv, getShortPrefix, removePropertyChangeListener, removePropertyChangeListener
@Deprecated public TLcyPreferencesTool(String aConfigSource, Class aClass)
TLcyPreferencesTool
that parses the given configuration source.aConfigSource
- The configuration source to parse the system and user preferences from.
Must not be null
.aClass
- A representative class for using this ALcyApplicationPaneTool
,
normally an extension of ALcyAddOn
. It is used to retrieve
the long and short prefixes using getLongPrefix
and getShortPrefix
. These
prefixes are stored in workspace files, so if backward compatibility is a
concern (e.g. read an old workspace file), the given class or its name
must never change.TLcyPreferencesManager.getUserPreferencesPropertiesDecoder()
,
TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()
public TLcyPreferencesTool(String aConfigSource, String aLongPrefix, String aShortPrefix)
Creates a new TLcyPreferencesTool
that parses the given configuration source.
The long prefix must be globally unique, the short prefix is the prefix used in the
configuration files. Once chosen, they shouldn't change if backward compatibility is a concern
(for example reading old workspace files). The concatenation of the long and short
prefix has another constraint: no combination should be a substring of another one. When using
for example getLongPrefixWithClassName
as
the long prefix, this never happens.
aConfigSource
- The configuration source to parse the system and user preferences from.
Must not be null
.aLongPrefix
- The long prefix. This prefix must be globally unique. It is stored in
workspace files, so if backward compatibility is a concern (e.g. read an
old workspace file), this prefix must never change. Use for example
ALcyTool.getLongPrefixWithClassName(Class)
.aShortPrefix
- The short prefix. This prefix is used to prefix the keys that are
retrieved from the given properties (see class comment). It might be
stored in workspace files, so if backward compatibility is a concern (e.g.
read an old workspace file), this prefix must never change. Lucy add-ons
normally use ALcyTool.getShortPrefix(Class)
.TLcyPreferencesManager.getUserPreferencesPropertiesDecoder()
,
TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()
public TLcyPreferencesTool(ALcyProperties aSystemDefaults, ALcyProperties aUserDefaults, String aConfigSource, String aLongPrefix, String aShortPrefix)
Creates a new TLcyPreferencesTool
that is initialised with optional (hard
coded) defaults for system and user preferences, and that optionally parses a configuration
source.
When using the system and user defaults and config file 'sourceName.cfg', the order of all preferences
involved is listed below, as returned by getCompositeWorkspacePreferences()
.
The entry at the top has the highest priority, and the one at the bottom the lowest
sourceName.userPrefs.cfg
aUserDefaults
sourceName.cfg
aSystemDefaults
aSystemDefaults
and be sure they are always available, or
even use code to generate them.
The long prefix must be globally unique, the short prefix is the prefix used in the
configuration files. Once chosen, they shouldn't change if backward compatibility is a concern
(for example reading old workspace files). The concatenation of the long and short
prefix has another constraint: no combination should be a substring of another one. When using
for example getLongPrefixWithClassName
as
the long prefix, this never happens.
aSystemDefaults
- The (hard coded) defaults for the system preferences. Can be
null
.aUserDefaults
- The (hard coded) defaults for the user preferences. Can be
null
.aConfigSource
- The configuration source to parse the system and user preferences from.
If left null
, no parsing is performed.aLongPrefix
- The long prefix. This prefix must be globally unique. It is stored in
workspace files, so if backward compatibility is a concern (e.g. read an
old workspace file), this prefix must never change. Use for example
ALcyTool.getLongPrefixWithClassName(Class)
.aShortPrefix
- The short prefix. This prefix is used to prefix the keys that are
retrieved from the given properties (see class comment). It might be
stored in workspace files, so if backward compatibility is a concern
(e.g. read an old workspace file), this prefix must never change. Lucy
add-ons normally use ALcyTool.getShortPrefix(Class)
.TLcyPreferencesManager.getUserPreferencesPropertiesDecoder()
,
TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()
public ALcyProperties getCompositeWorkspacePreferences()
plugInto
has been called.null
.IllegalStateException
- When plugInto
has not been called yet.public ALcyProperties getCompositeUserPreferences()
plugInto
has been called.null
.IllegalStateException
- When plugInto
has not been called yet.public ALcyProperties getSystemPreferences()
TLcyPreferencesManager
.
When saving these, keys are prefixed with the long prefix of this tool (in addition to the short prefix),
and all values are converted to String
s with the composite property converter.
This method can only be called after plugInto
has been called.ALcyProperties
instance holding the system preferences of this tool.
Never null
.IllegalStateException
- When plugInto
has not been called yet.getCompositePropertyConverter()
,
TLcyPreferencesManager.getSystemPreferences()
public ALcyProperties getUserPreferences()
TLcyPreferencesManager
.
When saving these, keys are prefixed with the long prefix of this tool (in addition to the short prefix),
and all values are converted to String
s with the composite property converter.
This method can only be called after plugInto
has been called.ALcyProperties
instance holding the user preferences of this tool.
Never null
.IllegalStateException
- When plugInto
has not been called yet.getCompositePropertyConverter()
,
TLcyPreferencesManager.getCurrentUserPreferences()
public ALcyProperties getWorkspacePreferences()
String
s with the composite property converter.
This method can only be called after plugInto
has been called.
Warning: don't rely on the key order.
This method can only be called after plugInto
has been called.ALcyProperties
instance holding the workspace preferences of this tool.
Never null
.IllegalStateException
- When plugInto
has not been called yet.getCompositePropertyConverter()
,
ALcyWorkspaceCodec
public TLcyCompositePropertyConverter getCompositePropertyConverter()
Returns the composite property converter of this tool. This converter is used to transform
all values in the different preferences to String
s when saving them to the
preferences stores.
Addons using this tool are expected to register ILcyPropertyConverter
instances
if they save any kind of Object
in any of the preferences for which no default
put...
method is available. This means that for Color
,
String
arrays, etc. no ILcyPropertyConverter
needs to be
registered.
This method may be called before the plugInto
method has been
called.
TLcyCompositePropertyConverter
used to convert all values to
String
s. Never null
.public void plugInto(ILcyLucyEnv aLucyEnv)
Reads the initial system and user preferences from the configuration source and performs the necessary work to automatically save the different kinds of preferences in the correct preferences stores.
Plugs this tool. This method is usually called from
ALcyAddOn#plugInto
.
plugInto
in class ALcyTool
aLucyEnv
- The environment to plug into.TLcyPreferencesManager.getUserPreferencesPropertiesDecoder()
,
TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()
public void unplugFrom(ILcyLucyEnv aLucyEnv)
Saves the user and system preferences of this tool to the user and system preferences of the
TLcyPreferencesManager
.
Unplugs this tool. This method is usually called from
ALcyAddOn#unplugFrom
.
unplugFrom
in class ALcyTool
aLucyEnv
- The environment to unplug from, must be identical to the environment given to
plugInto
.public void setWorkspaceCodec(ALcyWorkspaceCodec aWorkspaceCodec)
@Deprecated public static void setClassTraceOn(boolean aClassTraceOn)
true
then all log messages are recorded, otherwise only
the informative, warning and error messages are recorded.aClassTraceOn
- if true then all log messages are recorded,
otherwise only the informative, warning and error messages are recorded.@Deprecated public void setTraceOn(boolean aTraceOn)
true
or false
as argument automatically turns
off tracing for all other class instances for which
setTraceOn
has not been called.
If the argument is false
then only the informative, warning
and error log messages are recorded.aTraceOn
- if true then all log messages are recorded for this
instance. If false, then only the informative, warning and
error log messages are recorded.@Deprecated public boolean isTraceOn()
true
if tracing is enabled for this class.