Package ca.corbett.extras.properties

Class PropertiesManager

java.lang.Object
ca.corbett.extras.properties.PropertiesManager
public class PropertiesManager extends Object
Provides a highly configurable wrapper around a set of related properties, along with ways to manage them and present them to the user for viewing and modification. The intention is that all applications go through an instance of this class so that application preferences are handled in a consistent way. This can be used for managing properties of any supported type in a generic and configurable way.

PropertiesManager can be used directly, but the more typical case is for applications to use AppProperties (or a derived class), which binds together a PropertiesManager instance with an ExtensionManager instance. AppProperties is extremely useful in saving a lot of work for client code. Specifically, AppProperties can handle the auto-generation of a PropertiesDialog for viewing and editing your application's properties.

For more information, refer to the swing-extras book, or check out the built-in demo application that comes with this library!

Since:
swing-extras 1.8, 2024-12-30
Author:
scorbo2

  • Field Details

    • logger

      protected static final Logger logger

    • propertiesInstance

      protected final Properties propertiesInstance

    • properties

      protected final List<AbstractProperty> properties

    • name

      protected final String name

  • Constructor Details

    • PropertiesManager

      public PropertiesManager(File propsFile, List<AbstractProperty> props, String name)
      Creates a PropertiesManager instance backed onto the given File object, and a list of AbstractProperty objects that we will manage.
      Parameters:
      propsFile - The properties file. Does not need to exist - will be created on save()
      props - A List of AbstractProperty instances to be managed by this class.
      name - A name for this property collection. Comment header for the props file.

    • PropertiesManager

      public PropertiesManager(Properties propsInstance, List<AbstractProperty> props, String name)
      Creates a PropertiesManager instance backed onto the given Properties object (which may be a FileBasedProperties instance for disk persistence, or a Properties instance for in-memory), and a list of AbstractProperty objects that we will manage.
      Parameters:
      propsInstance - Any instance of Properties. Will be used for storing and retrieving.
      props - A List of AbstractProperty instances to be managed by this class.
      name - A name for this property collection. Comment header for the propsInstance file.

  • Method Details

    • getName

      public String getName()
      Returns the name of this PropertiesManager. This String is used as a comment header when writing properties files (assuming our Properties instance is a FileBasedProperties).
      Returns:
      The name of this PropertiesManager.

    • getCategories

      public List<String> getCategories()
      Returns a list of all property categories of all non-hidden properties in this PropertiesManager, in the order they were given to the constructor. We don't sort them alphabetically so that applications can define their own preferred order.
      Returns:
      A list of one or more property categories.

    • getSubcategories

      public List<String> getSubcategories(String category)
      Returns a list of all subcategories contained within the named property category. If the specified category does not exist, the list will be empty.
      Parameters:
      category - The name of the category to check.
      Returns:
      A list of zero or more subcategories for the named category.

    • getPropertiesInstance

      public Properties getPropertiesInstance()
      Returns the underlying Properties instance that this manager manages. This can be a shorthand for getting access to specific properties. For example, instead of: 
         IntegerProperty someInt = (IntegerProperty)propsManager.getProperty("a.b.c");
   if (someInt != null) {
     return someInt.getValue();
   }
   return someDefaultValue;
      You can instead do: 
         return propsManager.getPropertiesInstance().getInteger("a.b.c", someDefaultValue);
      Returns:
      the Properties instance that this manager manages.

    • getProperties

      public List<AbstractProperty> getProperties(String category, String subCategory)
      Returns a list of all non-hidden PropertyFields in the given category and subcategory. The list may be empty if either the category or subcategory do not exist.
      Parameters:
      category - The name of the property category to check.
      subCategory - The name of the subcategory to check.
      Returns:
      A list of all AbstractProperty objects in that category/subcategory.

    • getProperty

      public AbstractProperty getProperty(String fullyQualifiedName)
      Returns a specific AbstractProperty by its fully qualified name, if it exists.
      Parameters:
      fullyQualifiedName - The identifier of the property in question.
      Returns:
      The property object, or null if not found.

    • load

      public void load() throws Exception
      Loads the value of each of our properties from the Properties instance we were supplied in our constructor, overwriting any current values. The current values of our properties are used as default values in the event that the property in question is not present in the Properties instance.
      Throws:
      Exception - If our Properties instance is file based, we might get an IOException.

    • save

      public void save()
      Saves the value of each of our properties to the Properties instance we were supplied in the constructor, overwriting any previously saved values. The output list will be alphabetically sorted by fully qualified property name, making for a (hopefully) easy to read properties file.

      Note: If our Properties instance is not a FileBasedProperties instance, then this method will update the Properties instance in memory, but will not persist anything to disk. Persistence is up to the caller in that case.

    • updateFromDialog

      public void updateFromDialog(PropertiesDialog dialog)
      Copies all property values from the given PropertiesDialog (assuming the dialog was validated and closed via the OK button) and updates our properties with those values. This will also invoke save() automatically, so if our Properties instance is file based, the updated values are persisted to disk.
      Parameters:
      dialog - The PropertiesDialog in question.

    • generateDialog

      public PropertiesDialog generateDialog(Window owner, String dialogTitle)
      Generates a PropertiesDialog for the current properties list. You can use setAlignment() and setBorderPanel() on the generated dialog to customize the FormPanel layout options.

      Note: As of swing-extras 2.8, this method will return a PropertiesDialog based on ActionPanel navigation. Use the generateClassicDialog() method if you want the older tabbed pane style dialog instead.

      Parameters:
      owner - The owner Window for the dialog.
      dialogTitle - The title of the dialog.
      Returns:
      A PropertiesDialog instance, populated and ready to be shown.

    • generateDialog

      public PropertiesDialog generateDialog(Window owner, String dialogTitle, boolean addPanelHeaders)
      Generates a PropertiesDialog for the current properties list. You can use setAlignment() and setBorderPanel() on the generated dialog to customize the FormPanel layout options.

      Note: As of swing-extras 2.8, this method will return a PropertiesDialog based on ActionPanel navigation. Use the generateClassicDialog() method if you want the older tabbed pane style dialog instead.

      Parameters:
      owner - The owner Window for the dialog.
      dialogTitle - The title of the dialog.
      addPanelHeaders - true to show auto-generated header labels for each FormPanel.
      Returns:
      A PropertiesDialog instance, populated and ready to be shown.

    • generateClassicDialog

      public PropertiesDialog generateClassicDialog(Window owner, String dialogTitle, boolean alwaysShowSubcategoryLabels)
      Generates a PropertiesDialog for the current properties list. You can use setAlignment() and setBorderPanel() on the generated dialog to customize the FormPanel layout options.

      Note: This method generates a PropertiesDialog based on the older tabbed pane style dialog. For the newer, ActionPanel-based dialog, use the generateDialog() method instead.

      Parameters:
      owner - The owner Window for the dialog.
      dialogTitle - The title of the dialog.
      alwaysShowSubcategoryLabels - true to show subcategory labels even if there's only one subcategory in a category.
      Returns:
      A PropertiesDialog instance, populated and ready to be shown.

    • getCategories

      public static List<String> getCategories(List<AbstractProperty> props)
      Extracts and returns a list of all top-level property categories for all non-hidden properties in the given list, in the order that they are discovered within that list. We don't sort the category list so that applications can define their own preferred order.
      Parameters:
      props - A list of properties to scan.
      Returns:
      A List of unique top-level category names for all non-hidden properties that were found.

    • getSubcategories

      public static List<String> getSubcategories(String category, List<AbstractProperty> props)
      Scans the given property list and returns a list of all subcategories within the named category have at least one non-hidden property. If the specified category does not exist, the list will be empty.
      Parameters:
      category - The name of the category to check.
      props - The list of properties to scan. Hidden or disabled properties will be ignored.
      Returns:
      A list of zero or more subcategories for the named category.

    • getProperties

      public static List<AbstractProperty> getProperties(List<AbstractProperty> props, String category, String subCategory)
      Scans the given properties list and returns a list of all non-hidden properties that belong to the given category and subcategory.
      Parameters:
      props - The list of properties to scan
      category - The top-level category to check
      subCategory - The subcategory to check
      Returns:
      A List of zero or more AbstractProperties that match the search parameters.