Module org.autogui

Package org.autogui.base.mapping

Class GuiPreferences

java.lang.Object

org.autogui.base.mapping.GuiPreferences

Direct Known Subclasses:

GuiPreferences.GuiPreferencesWithPaths

public class GuiPreferences
extends Object

the Preferences holder associated to a GuiMappingContext. Each child is also held by GuiMappingContext. The class has a GuiPreferences.GuiValueStore. It also has a list of history values.

        pack/Type/  //root-context, in a case of GuiReprObjectPane(pack.Type)
                    //otherwise, "org/autogui/base/mapping/pack_Type"
            "$default"/
               propName = value... //regular preferences entries
               ...
               "$value" = ... //current value, which will precede to history values
               "$history"/
                  "0"/    //key-index
                     "index" = ...
                     "value" = ...
                     "time"  = ... //Instant.toString()
                  ...
               propertyName/   //the name of a sub-context
                  ...
            "$launchPrefs" = "..." //value of "$uuid", "" or "empty"
            "$saved"/
               "$0"/
                 "$name" = ...
                 "$uuid" = "..." //a value from UUID.randomUUID()
                 ... //same structure as "$default"
               ...
   

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GuiPreferences.GuiPreferencesWithPaths	a subclass of prefs for custom usage with supplying specific sub-paths.
static class	GuiPreferences.GuiValueStore	the abstract definition of key-value store.
static class	GuiPreferences.GuiValueStoreDefault	the concrete implementation of the store by Preferences
static class	GuiPreferences.GuiValueStoreImmutable
static class	GuiPreferences.GuiValueStoreOnMemory	an on-memory impl.
static class	GuiPreferences.HistoryValueEntry	an entry of the value history, consisting of a value, an index and a time-stamp, associated with a key-index.
static class	GuiPreferences.HistoryValueEntryJsonSupported	JSON entry for JSON support object
static class	GuiPreferences.HistoryValueEntryOnMemory	an on-memory impl.
static interface	GuiPreferences.PreferencesJsonSupport	the interface for supporting user-defined prefs: a context-object that implements the interface always saves/loads prefs via the interface.
static class	GuiPreferences.PreferencesLock	the entire lock object for the preferences
static interface	GuiPreferences.PreferencesStoreChangeListener
static enum	GuiPreferences.PreferencesStoreChangeSpecialValue

Field Summary

Fields

Modifier and Type	Field	Description
protected Map<GuiMappingContext,GuiPreferences>	children
protected GuiMappingContext	context
protected int	historyValueLimit
protected List<GuiPreferences.HistoryValueEntry>	historyValues
protected List<GuiPreferences.HistoryValueEntry>	historyValuesFree
static final String	KEY_CURRENT_VALUE	the key for getCurrentValue()
static final String	KEY_DEFAULT	the key for the default GuiPreferences node under the root
static final String	KEY_HISTORY	the key for the history node containing GuiPreferences.HistoryValueEntry under GuiPreferences
static final String	KEY_HISTORY_ENTRY_INDEX	the key for the int index of GuiPreferences.HistoryValueEntry
static final String	KEY_HISTORY_ENTRY_TIME	the key for the string Instant value of GuiPreferences.HistoryValueEntry
static final String	KEY_HISTORY_ENTRY_VALUE	the key for the JSON string value of GuiPreferences.HistoryValueEntry
static final String	KEY_LAUNCH_PREFS	the key for the string uuid refering a saved GuiPreferences under the root
static final String	KEY_NAME	the key for the string name of GuiPreferences
static final String	KEY_SAVED	the key for saved node containing sub-nodes of GuiPreferences under the root
static final String	KEY_UUID	the key for the string UUID of GuiPreferences
protected GuiPreferences.PreferencesLock	lock
protected GuiPreferences	parent
protected List<GuiPreferences.PreferencesStoreChangeListener>	storeChangeListeners
protected GuiPreferences.GuiValueStore	valueStore

Constructor Summary

Constructors

Constructor	Description
GuiPreferences(GuiMappingContext context)
GuiPreferences(GuiPreferences.GuiValueStore valueStore, GuiMappingContext context)
GuiPreferences(GuiPreferences parent, GuiMappingContext context)

Method Summary

Modifier and Type	Method	Description
void	addHistoryValue(Object value)	add a value to the history.
void	addHistoryValue(Object value, Instant optionalTime)
GuiPreferences	addNewSavedStoreAsRoot()
void	addStoreChangeListener(GuiPreferences.PreferencesStoreChangeListener listener)
void	clearAll()	after calling the method, the preferences will be invalidated
void	clearHistories()
void	clearHistoriesTree()
void	clearHistoriesTree(boolean clearPrefs)
GuiPreferences	copyInitAsRoot()
GuiPreferences	copyOnMemory(GuiPreferences parent)
GuiPreferences	copyOnMemoryAsRoot()
static GuiPreferences.GuiValueStore	copyOnMemoryStore(GuiPreferences src, GuiPreferences prefs, GuiPreferences.GuiValueStore store, boolean putToParent)
GuiPreferences.HistoryValueEntry	createHistoryValueEntry(Object value)
protected List<GuiPreferences.HistoryValueEntry>	createHistoryValuesByLoad()
void	fromJson(Map<String,Object> json)
protected void	fromJsonChildNodes(GuiPreferences.GuiValueStore store, Map<String,Object> json)
GuiPreferences	getChild(GuiMappingContext context)
GuiMappingContext	getContext()
Object	getCurrentValue()
Object	getCurrentValueAsJsonSupported()	loads prefs JSON object for GuiPreferences.PreferencesJsonSupport.setPrefsJson(Map)
GuiPreferences	getDescendant(GuiMappingContext descendantContext)
GuiPreferences.HistoryValueEntry	getHistoryValue(Object value)
protected GuiPreferences.HistoryValueEntry	getHistoryValueForStoredValue(Object v)
GuiPreferences.HistoryValueEntry	getHistoryValueFree()
int	getHistoryValueLimit()
List<GuiPreferences.HistoryValueEntry>	getHistoryValues()	loaded history values the size of the list is up to historyValueLimit all entries have valid indices, !=-1, ordered, but might not start from 0 can be sorted by indices; the larger indices are recent entries their keyIndex are meaningless, just unique key for node
List<GuiPreferences.HistoryValueEntry>	getHistoryValuesFree()
int	getHistoryValueUnusedKeyIndex()
String	getLaunchPrefsAsRoot()
String	getName()
GuiPreferences	getParent()
GuiPreferences.GuiValueStore	getPreferencesNodeAsRoot()
List<GuiPreferences>	getSavedStoreListAsRoot()	"$default/" ...
List<GuiPreferences.PreferencesStoreChangeListener>	getStoreChangeListeners()
static int	getStoreValueMaxLength()
GuiPreferences.GuiValueStore	getValueStore()
GuiPreferences.GuiValueStore	getValueStoreRootFromRepresentation()
boolean	isContextTypeIsJsonSupport()
void	load()
void	loadHistoryValues()	load or create historyValues: it's size becomes up to historyValueLimit and sorted by index.
protected void	loadNodes(GuiPreferences.GuiValueStore store, Collection<String> keys)
GuiPreferences.PreferencesLock	lock()
void	notifyStoreChange(String key, Object value)
void	notifyStoreChange(GuiPreferences preferences, String key, Object value)
void	overwriteByAnotherPrefs(GuiPreferences prefs)
void	overwriteToEmpty()
void	removeHistories(Collection<GuiPreferences.HistoryValueEntry> loadedValuesRemoved)
void	removeStoreChangeListener(GuiPreferences.PreferencesStoreChangeListener listener)
void	resetAsRoot()
protected void	setChild(GuiMappingContext context, GuiPreferences child)
void	setCurrentValue(Object value)
void	setCurrentValueAsJsonSupported(Object json)	saves the given JSON as a prefs entry
void	setHistoryValues(List<GuiPreferences.HistoryValueEntry> es)	sort es by index,
void	setLaunchPrefsAsRoot(String uuid)
void	syncHistoryValues()
void	syncHistoryValues(boolean resetIndex)
Map<String,Object>	toJson()
static String	toStoreKey(String key)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

context

protected GuiMappingContext context

parent

protected GuiPreferences parent

children

protected Map<GuiMappingContext,GuiPreferences> children

valueStore

protected GuiPreferences.GuiValueStore valueStore

historyValues

protected List<GuiPreferences.HistoryValueEntry> historyValues

historyValuesFree

protected List<GuiPreferences.HistoryValueEntry> historyValuesFree

historyValueLimit

protected int historyValueLimit

storeChangeListeners

protected List<GuiPreferences.PreferencesStoreChangeListener> storeChangeListeners

lock

protected GuiPreferences.PreferencesLock lock

Since:

1.6

KEY_DEFAULT

public static final String KEY_DEFAULT

the key for the default GuiPreferences node under the root

See Also:

• Constant Field Values

KEY_CURRENT_VALUE

public static final String KEY_CURRENT_VALUE

the key for getCurrentValue()

See Also:

• Constant Field Values

KEY_LAUNCH_PREFS

public static final String KEY_LAUNCH_PREFS

the key for the string uuid refering a saved GuiPreferences under the root

See Also:

• Constant Field Values

KEY_SAVED

public static final String KEY_SAVED

the key for saved node containing sub-nodes of GuiPreferences under the root

See Also:

• Constant Field Values

KEY_NAME

public static final String KEY_NAME

the key for the string name of GuiPreferences

See Also:

• Constant Field Values

KEY_UUID

public static final String KEY_UUID

the key for the string UUID of GuiPreferences

See Also:

• Constant Field Values

KEY_HISTORY

public static final String KEY_HISTORY

the key for the history node containing GuiPreferences.HistoryValueEntry under GuiPreferences

See Also:

• Constant Field Values

KEY_HISTORY_ENTRY_INDEX

public static final String KEY_HISTORY_ENTRY_INDEX

the key for the int index of GuiPreferences.HistoryValueEntry

See Also:

• Constant Field Values

KEY_HISTORY_ENTRY_VALUE

public static final String KEY_HISTORY_ENTRY_VALUE

the key for the JSON string value of GuiPreferences.HistoryValueEntry

See Also:

• Constant Field Values

KEY_HISTORY_ENTRY_TIME

public static final String KEY_HISTORY_ENTRY_TIME

the key for the string Instant value of GuiPreferences.HistoryValueEntry

See Also:

• Constant Field Values

Constructor Details

GuiPreferences

public GuiPreferences(GuiMappingContext context)

GuiPreferences

public GuiPreferences(GuiPreferences parent,
 GuiMappingContext context)

GuiPreferences

public GuiPreferences(GuiPreferences.GuiValueStore valueStore,
 GuiMappingContext context)

Method Details

isContextTypeIsJsonSupport

public boolean isContextTypeIsJsonSupport()

Returns:

the type of the context of the prefs is GuiPreferences.PreferencesJsonSupport

Since:

1.5

copyInitAsRoot

public GuiPreferences copyInitAsRoot()

getStoreValueMaxLength

public static int getStoreValueMaxLength()

toStoreKey

public static String toStoreKey(String key)

getChild

public GuiPreferences getChild(GuiMappingContext context)

Parameters:

context - the parent

Returns:

a child preference for context

setChild

protected void setChild(GuiMappingContext context,
 GuiPreferences child)

getName

public String getName()

getContext

public GuiMappingContext getContext()

getParent

public GuiPreferences getParent()

getDescendant

public GuiPreferences getDescendant(GuiMappingContext descendantContext)

Parameters:

descendantContext - a descendant context of the context returned by getContext(), can be getContext() itself

Returns:

a descendant preference associated with the descendantContext

getValueStore

public GuiPreferences.GuiValueStore getValueStore()

Returns:

Preferences based value-store. if it has parent, node for context's name of the parent, otherwise, node for context's object-type (user-node "/pack/ObjType") or node for (pack of this type)+"/"+(context's name).

getValueStoreRootFromRepresentation

public GuiPreferences.GuiValueStore getValueStoreRootFromRepresentation()

getPreferencesNodeAsRoot

public GuiPreferences.GuiValueStore getPreferencesNodeAsRoot()

resetAsRoot

public void resetAsRoot()

lock

public GuiPreferences.PreferencesLock lock()

Returns:

lock object with holding the lock

Since:

1.6

getSavedStoreListAsRoot

public List<GuiPreferences> getSavedStoreListAsRoot()

            "$default/"
               ...
            "$launchPrefs" = "..."
            "$saved/"
               "$0/"
                  "$name" = "prefs yyyy/mm/dd hh:mm"
                  "$uuid" = "..." //checked
                  ...
               "$1/"
               ...
 

Returns:

saved preferences

getLaunchPrefsAsRoot

public String getLaunchPrefsAsRoot()

Returns:

"": value of "$uuid", "" (default) or "empty" (empty)

setLaunchPrefsAsRoot

public void setLaunchPrefsAsRoot(String uuid)

addNewSavedStoreAsRoot

public GuiPreferences addNewSavedStoreAsRoot()

setCurrentValue

public void setCurrentValue(Object value)

setCurrentValueAsJsonSupported

public void setCurrentValueAsJsonSupported(Object json)

saves the given JSON as a prefs entry

Parameters:

json - the saved object

Since:

1.5

getCurrentValue

public Object getCurrentValue()

getCurrentValueAsJsonSupported

public Object getCurrentValueAsJsonSupported()

loads prefs JSON object for GuiPreferences.PreferencesJsonSupport.setPrefsJson(Map)

Returns:

loaded JSON object

Since:

1.5

addHistoryValue

public void addHistoryValue(Object value)

add a value to the history.

1. it first loads the existing history if not yet loaded, by loadHistoryValues().
2. it finds an existing entry or a create new entry by getHistoryValue(Object). the entire number of entries always keeps under historyValueLimit.
3. The entry moves to the end of the history as the latest value, by setting the max index + 1 as it's index.
4. set keyIndex if -1; those are new entries and no exsting nodes
5. if the max index overs 100 x historyValueLimit, reset all indices from 0

Parameters:

value - the new entry value

addHistoryValue

public void addHistoryValue(Object value,
 Instant optionalTime)

getHistoryValueLimit

public int getHistoryValueLimit()

syncHistoryValues

public void syncHistoryValues()

syncHistoryValues

public void syncHistoryValues(boolean resetIndex)

setHistoryValues

public void setHistoryValues(List<GuiPreferences.HistoryValueEntry> es)

sort es by index,

Parameters:

es - entries from another prefs

getHistoryValueUnusedKeyIndex

public int getHistoryValueUnusedKeyIndex()

overwriteByAnotherPrefs

public void overwriteByAnotherPrefs(GuiPreferences prefs)

overwriteToEmpty

public void overwriteToEmpty()

load

public void load()

loadNodes

protected void loadNodes(GuiPreferences.GuiValueStore store,
 Collection<String> keys)

getHistoryValues

public List<GuiPreferences.HistoryValueEntry> getHistoryValues()

loaded history values

• the size of the list is up to historyValueLimit
• all entries have valid indices, !=-1, ordered, but might not start from 0
• can be sorted by indices; the larger indices are recent entries
• their keyIndex are meaningless, just unique key for node

Returns:

loaded history-values

getHistoryValue

public GuiPreferences.HistoryValueEntry getHistoryValue(Object value)

Parameters:

value - the entry value (raw-object)

Returns:

a new entry (keyIndex == -1), an existing entry (index!=-1; removed from historyValues), or an existing free entry (index==-1; removed from historyValuesFree); the value is set to JSON of the given value; the obtained entry is temporarly not parted in both historyValues and historyValuesFree.

getHistoryValueForStoredValue

protected GuiPreferences.HistoryValueEntry getHistoryValueForStoredValue(Object v)

getHistoryValueFree

public GuiPreferences.HistoryValueEntry getHistoryValueFree()

Returns:

a new entry (keyIndex == -1), an existing entry (index!=-1; removed from historyValues), or an existing free entry (index==-1; removed from historyValuesFree); the obtained entry is temporarly not parted in both historyValues and historyValuesFree.

getHistoryValuesFree

public List<GuiPreferences.HistoryValueEntry> getHistoryValuesFree()

loadHistoryValues

public void loadHistoryValues()

load or create historyValues: it's size becomes up to historyValueLimit and sorted by index. The new entries have -1 indices.

createHistoryValuesByLoad

protected List<GuiPreferences.HistoryValueEntry> createHistoryValuesByLoad()

createHistoryValueEntry

public GuiPreferences.HistoryValueEntry createHistoryValueEntry(Object value)

clearAll

public void clearAll()

after calling the method, the preferences will be invalidated

clearHistoriesTree

public void clearHistoriesTree()

clearHistoriesTree

public void clearHistoriesTree(boolean clearPrefs)

clearHistories

public void clearHistories()

removeHistories

public void removeHistories(Collection<GuiPreferences.HistoryValueEntry> loadedValuesRemoved)

notifyStoreChange

public void notifyStoreChange(String key,
 Object value)

notifyStoreChange

public void notifyStoreChange(GuiPreferences preferences,
 String key,
 Object value)

getStoreChangeListeners

public List<GuiPreferences.PreferencesStoreChangeListener> getStoreChangeListeners()

addStoreChangeListener

public void addStoreChangeListener(GuiPreferences.PreferencesStoreChangeListener listener)

removeStoreChangeListener

public void removeStoreChangeListener(GuiPreferences.PreferencesStoreChangeListener listener)

toJson

public Map<String,Object> toJson()

copyOnMemoryAsRoot

public GuiPreferences copyOnMemoryAsRoot()

copyOnMemory

public GuiPreferences copyOnMemory(GuiPreferences parent)

Parameters:

parent - the parent which is already an on-memory instance or null

Returns:

the copied preferences whose value-store is a GuiPreferences.GuiValueStoreOnMemory

copyOnMemoryStore

public static GuiPreferences.GuiValueStore copyOnMemoryStore(GuiPreferences src,
 GuiPreferences prefs,
 GuiPreferences.GuiValueStore store,
 boolean putToParent)

fromJson

public void fromJson(Map<String,Object> json)

fromJsonChildNodes

protected void fromJsonChildNodes(GuiPreferences.GuiValueStore store,
 Map<String,Object> json)