Module is.codion.common.model

Package is.codion.common.model.preferences

Class FilePreferences

java.lang.Object

java.util.prefs.Preferences

java.util.prefs.AbstractPreferences

is.codion.common.model.preferences.FilePreferences

public final class FilePreferences
extends AbstractPreferences

A file-based preferences implementation without length restrictions.

Supports hierarchical preferences through nested JSON structure.

Clearing the preferences instance and flushing deletes the underlying file.

A key and a child node can not share a name, both being stored in the same JSON object. Putting a value for a key naming a child node throws IllegalStateException, as does putting a value into a child node named after a key, while AbstractPreferences.get(String, String) and AbstractPreferences.remove(String) ignore child nodes.

Note that, unlike the AbstractPreferences contract, PreferenceChangeListeners are not notified of put(String, String) calls.

See Also:

• filePreferences(String)
• PREFERENCES_LOCATION
• PRETTY_PRINT
• UserPreferences

Field Summary

Fields

Modifier and Type	Field	Description
static final PropertyValue<String>	PREFERENCES_LOCATION	Provides a way to override the default (OS dependent) directory used to store the user preferences file.
static final PropertyValue<Boolean>	PRETTY_PRINT	Specifies whether JSON preference files are pretty-printed, causes significant size increase.

Fields inherited from class java.util.prefs.AbstractPreferences

lock, newNode

Fields inherited from class java.util.prefs.Preferences

MAX_KEY_LENGTH, MAX_NAME_LENGTH, MAX_VALUE_LENGTH

Method Summary

Modifier and Type	Method	Description
void	backup(String suffix)	Copies the backing file to a sibling with the given suffix appended to the filename.
protected String[]	childrenNamesSpi()
protected AbstractPreferences	childSpi(String name)
static Preferences	filePreferences(String filename)
void	flush()	Saves the changes made since the last flush or sync, once for the whole tree, re-applied on top of the file if it has been modified externally in the meantime, as sync() does.
protected void	flushSpi()
protected @Nullable String	getSpi(String key)
protected String[]	keysSpi()
void	put(String key, String value)
protected void	putSpi(String key, String value)
protected void	removeNodeSpi()
protected void	removeSpi(String key)
void	sync()	Reloads the file if it has been modified externally since it was last read or written, re-applying the changes made since the last flush or sync on top of it, and saves those changes, once for the whole tree.
protected void	syncSpi()

Methods inherited from class java.util.prefs.AbstractPreferences

absolutePath, addNodeChangeListener, addPreferenceChangeListener, cachedChildren, childrenNames, clear, exportNode, exportSubtree, get, getBoolean, getByteArray, getChild, getDouble, getFloat, getInt, getLong, isRemoved, isUserNode, keys, name, node, nodeExists, parent, putBoolean, putByteArray, putDouble, putFloat, putInt, putLong, remove, removeNode, removeNodeChangeListener, removePreferenceChangeListener, toString

Methods inherited from class java.util.prefs.Preferences

importPreferences, systemNodeForPackage, systemRoot, userNodeForPackage, userRoot

Methods inherited from class java.lang.Object

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

Field Details

PREFERENCES_LOCATION

public static final PropertyValue<String> PREFERENCES_LOCATION

Provides a way to override the default (OS dependent) directory used to store the user preferences file.

Note that changing this value after a file based preferences instance has been created has no effect on subsequent instances.

• Value type: String
• Default value: null

See Also:

• filePreferences(String)

PRETTY_PRINT

public static final PropertyValue<Boolean> PRETTY_PRINT

Specifies whether JSON preference files are pretty-printed, causes significant size increase.

Note that this value is captured when a file based preferences instance is created; changing it afterwards has no effect on that instance.

• Value type: Boolean
• Default value: false

Method Details

put

public void put(String key,
 String value)

Overrides:

put in class AbstractPreferences

filePreferences

public static Preferences filePreferences(String filename)

Parameters:

filename - the preferences filename

Returns:

a file based Preferences instance based on the given filename

backup

public void backup(String suffix)

Copies the backing file to a sibling with the given suffix appended to the filename. Does nothing in case of an in-memory instance or if the backing file does not exist.

Parameters:

suffix - the backup filename suffix

putSpi

protected void putSpi(String key,
 String value)

Specified by:

putSpi in class AbstractPreferences

getSpi

protected @Nullable String getSpi(String key)

Specified by:

getSpi in class AbstractPreferences

removeSpi

protected void removeSpi(String key)

Specified by:

removeSpi in class AbstractPreferences

keysSpi

protected String[] keysSpi()
                    throws BackingStoreException

Specified by:

keysSpi in class AbstractPreferences

Throws:

BackingStoreException

flush

public void flush()
           throws BackingStoreException

Saves the changes made since the last flush or sync, once for the whole tree, re-applied on top of the file if it has been modified externally in the meantime, as sync() does. Leaves the file untouched when there are no changes to save. AbstractPreferences.flush() would call flushSpi() on this node and on each cached descendant, saving the file once per node.

Overrides:

flush in class AbstractPreferences

Throws:

BackingStoreException - in case of an I/O error

sync

public void sync()
          throws BackingStoreException

Reloads the file if it has been modified externally since it was last read or written, re-applying the changes made since the last flush or sync on top of it, and saves those changes, once for the whole tree. AbstractPreferences.sync() would call syncSpi() on this node and on each cached descendant.

Overrides:

sync in class AbstractPreferences

Throws:

BackingStoreException - in case of an I/O error

IllegalStateException - in case this node has been removed

flushSpi

protected void flushSpi()
                 throws BackingStoreException

Specified by:

flushSpi in class AbstractPreferences

Throws:

BackingStoreException

syncSpi

protected void syncSpi()
                throws BackingStoreException

Specified by:

syncSpi in class AbstractPreferences

Throws:

BackingStoreException

childrenNamesSpi

protected String[] childrenNamesSpi()

Specified by:

childrenNamesSpi in class AbstractPreferences

childSpi

protected AbstractPreferences childSpi(String name)

Specified by:

childSpi in class AbstractPreferences

removeNodeSpi

protected void removeNodeSpi()

Specified by:

removeNodeSpi in class AbstractPreferences