Class DbPreferencesFactory

java.lang.Object
org.tentackle.dbms.prefs.DbPreferencesFactory
All Implemented Interfaces:
PreferencesFactory, org.tentackle.prefs.PersistedPreferencesFactory

@Service(org.tentackle.prefs.PersistedPreferencesFactory.class) public class DbPreferencesFactory extends Object implements org.tentackle.prefs.PersistedPreferencesFactory
Repository and factory for database backed preferences.

The DbPreferencesFactory implements PersistedPreferencesFactory which in turn extends PreferencesFactory. As such, it can be used as a drop-in replacement for the default JRE preferences factory. By default, however, it is available to the application only via PersistedPreferencesFactory.getInstance(), which is the preferred way for tentackle applications to use preferences.

Author:
harald
  • Constructor Details

    • DbPreferencesFactory

      public DbPreferencesFactory()
      Creates the factory.
  • Method Details

    • getInstance

      public static DbPreferencesFactory getInstance()
      Gets the factory singleton.
      Returns:
      the factory
    • invalidate

      public void invalidate()
      Specified by:
      invalidate in interface org.tentackle.prefs.PersistedPreferencesFactory
    • isAutoSync

      public boolean isAutoSync()
      Specified by:
      isAutoSync in interface org.tentackle.prefs.PersistedPreferencesFactory
    • setAutoSync

      public void setAutoSync(boolean autoSync)
      Specified by:
      setAutoSync in interface org.tentackle.prefs.PersistedPreferencesFactory
    • isReadOnly

      public boolean isReadOnly()
      Specified by:
      isReadOnly in interface org.tentackle.prefs.PersistedPreferencesFactory
    • setReadOnly

      public void setReadOnly(boolean readOnly)
      Specified by:
      setReadOnly in interface org.tentackle.prefs.PersistedPreferencesFactory
    • isSystemOnly

      public boolean isSystemOnly()
      Specified by:
      isSystemOnly in interface org.tentackle.prefs.PersistedPreferencesFactory
    • setSystemOnly

      public void setSystemOnly(boolean systemOnly)
      Specified by:
      setSystemOnly in interface org.tentackle.prefs.PersistedPreferencesFactory
    • getSystemRoot

      public DbPreferences getSystemRoot()
      Specified by:
      getSystemRoot in interface org.tentackle.prefs.PersistedPreferencesFactory
    • getUserRoot

      public DbPreferences getUserRoot()
      Specified by:
      getUserRoot in interface org.tentackle.prefs.PersistedPreferencesFactory
    • userNodeForPackage

      public DbPreferences userNodeForPackage(Class<?> c)
      Specified by:
      userNodeForPackage in interface org.tentackle.prefs.PersistedPreferencesFactory
    • systemNodeForPackage

      public DbPreferences systemNodeForPackage(Class<?> c)
      Specified by:
      systemNodeForPackage in interface org.tentackle.prefs.PersistedPreferencesFactory
    • systemRoot

      public DbPreferences systemRoot()
      Specified by:
      systemRoot in interface PreferencesFactory
    • userRoot

      public DbPreferences userRoot()
      Specified by:
      userRoot in interface PreferencesFactory
    • getSerial

      public long getSerial(String user)
      Gets the current serial version of given user- or system root.
      Parameters:
      user - the username, null or "" if system
      Returns:
      the serial, 0 if no such root loaded
    • addPreferenceChangeListener

      public void addPreferenceChangeListener(DbPreferences node, PreferenceChangeListener pcl)
      Adds a preferences changed listener.

      Notice that when a node is removed, its listeners will not be removed. So, if the node is added again, the listeners are still there. Listeners have to be removed by the application explicitly.

      Parameters:
      node - the node
      pcl - the listener
    • removePreferenceChangeListener

      public void removePreferenceChangeListener(DbPreferences node, PreferenceChangeListener pcl)
      Removes a preferences changed listener.
      Parameters:
      node - the node
      pcl - the listener
    • addNodeChangeListener

      public void addNodeChangeListener(DbPreferences node, NodeChangeListener ncl)
      Adds a node listener.

      Notice that when a node is removed, its listeners will not be removed. So, if the node is added again, the listeners are still there. Listeners have to be removed by the application explicitly.

      Parameters:
      node - the node
      ncl - the listener
    • removeNodeChangeListener

      public void removeNodeChangeListener(DbPreferences node, NodeChangeListener ncl)
      Removes a node listener.
      Parameters:
      node - the node
      ncl - the listener
    • nodeChanged

      public void nodeChanged(DbPreferences node)
      Invokes listeners when a node is added or removed.
      Parameters:
      node - the added or removed node
    • keyChanged

      public void keyChanged(DbPreferences node, DbPreferencesKey key)
      Invokes listeners when a key is added, updated or removed.
      Parameters:
      node - the node holding the key
      key - the changed key
    • flush

      public void flush(DbPreferences node, boolean sync) throws BackingStoreException
      Flushes a node and all of its sub-nodes to the backing store.

      The change listeners are invoked once the flush completed, without holding the monitor of this factory. If the flush fails, they are not invoked at all.

      If the session is running a transaction, the flush joins it and the modified rows stay locked in the database until the transaction ends. So does the write lock of this factory, see acquireWriteLock(Db).

      Parameters:
      node - the preferences node
      sync - true if load modifications from storage before flush
      Throws:
      BackingStoreException - if failed
    • getRootTree

      public DbPreferences getRootTree(Db db, String user)
      Gets the root node for given user and all of its sub-nodes and keys at once.
      Parameters:
      db - the optional db, null if request a db temporarily
      user - the username, null or empty if system user
      Returns:
      the root node, never null
    • checkAllPreferences

      public void checkAllPreferences(Db db)
      Checks all preferences and tries to fix if possible.
      The method is provided since DbPreferencesNode and DbPreferencesKey provide no referential integrity via database-enforced foreign keys, but only at application level.
      Invoke this method, whenever the database has been modified manually via SQL.
      Parameters:
      db - the session (must be local)
    • nodeName

      protected String nodeName(Class<?> clazz)
      Returns the absolute path name of the node corresponding to the package of the specified object.
      Parameters:
      clazz - the class
      Returns:
      the path name
      Throws:
      IllegalArgumentException - if the package has no preferences node associated with it
    • removeRoot

      protected void removeRoot(DbPreferences node)
      Removes a root node of given node from the repository.
      Parameters:
      node - the root node or one of its sub-nodes
    • updateRepository

      protected void updateRepository(Db db, long nodeMaxSerial, long keyMaxSerial)
      Updates the repository.
      Invoked whenever the data in prefnode or prefkey has changed.

      The change listeners are invoked once the repository is updated, without holding the monitor of this factory.

      Parameters:
      db - the session
      nodeMaxSerial - the new table serial for prefnodes
      keyMaxSerial - the new table serial for prefkeys
    • scheduleUpdate

      protected void scheduleUpdate(long nodeMaxSerial, long keyMaxSerial)
      Schedules the update of the repository on behalf of the modification tracker.

      The repository is not updated by the tracker thread, since it must not wait for the monitor of this factory. The thread holding the monitor may wait for the tracker thread, for example to configure the modification counter in a flush, and both would wait for each other until the tracker's wait interval elapsed. Instead, the update is performed by a separate thread, using the session of requestDb(boolean, boolean). Updates scheduled while the thread is still running are merged.

      Parameters:
      nodeMaxSerial - the new table serial for prefnodes, 0 if unchanged
      keyMaxSerial - the new table serial for prefkeys, 0 if unchanged
    • requestDb

      protected Db requestDb(boolean forUser, boolean forWrite)
      Requests for a session to work with.
      By default, the thread-local session is used. If there is no thread-local session, a session cloned from the modification tracker's session is used, see getFallbackDb().

      In preparation for replication layers, a requested session must be released after use.

      Parameters:
      forUser - true if a user session is required (no modification tracker fallback)
      forWrite - true if the session is used for writing (flush), else read
      Returns:
      the session
    • releaseDb

      protected void releaseDb(Db db)
      Releases the session after use.
      Parameters:
      db - the session
    • getUserName

      protected String getUserName()
      Gets the current username.
      Returns:
      the username