Package ca.corbett.extras.properties

Class Properties

java.lang.Object
ca.corbett.extras.properties.Properties
Direct Known Subclasses:
FileBasedProperties
public class Properties extends Object
Provides a wrapper around java's Properties class, with convenience methods that abstract away the type conversions that callers would otherwise have to worry about. Specifically, the java.util.Properties class handles everything as Strings, which is great for simple name/value pairs, but when you want to start storing integers, booleans, color values, and etc, you have to worry about converting everything to and from Strings. This class abstracts that for you and provides easy convenience methods.

NOTE: All setters in this wrapper guard against null values so that we never pass a null into java.util.Properties#setProperty, which would otherwise cause a NullPointerException in the underlying Hashtable.

Since:
2022-05-10
Author:
scorbo2

  • Field Details

  • Constructor Details

    • Properties

      public Properties()
      Creates a new, empty Properties object.

  • Method Details

    • getPropertyNames

      public List<String> getPropertyNames()
      Returns a sorted list of property names currently stored in this Properties object. Implementation note: a copy of the list is returned to avoid client modification headaches.
      Returns:
      A list of unique property names.

    • remove

      public void remove(String name)
      Removes the property with the given name, if any.
      Parameters:
      name - The property name.

    • setString

      public void setString(String name, String value)
      Sets a String name/value pair. Replaces any previous value for the given name. If value is null, we do not write into the underlying Properties to avoid NPE.
      Parameters:
      name - The property name.
      value - The property value.

    • getString

      public String getString(String name, String defaultValue)
      Retrieves the String value of the named property, if any. If the stored value is explicitly blank, then a blank string is returned. If you wish to treat blank strings the same as null/missing values, then invoke getString(name, defaultValue, true) instead of this method.
      Parameters:
      name - The property name.
      defaultValue - A value to receive if no such named property exists.
      Returns:
      The value of the named property, or defaultValue if no such property exists.

    • getString

      public String getString(String name, String defaultValue, boolean defaultIfBlank)
      Retrieves the String value of the named property, if any. If defaultIfBlank is true, then explicit blank String values in the saved property will be handled the same way as if the property had a null/missing value. That is, the given defaultValue will be returned instead of the blank string.
      Parameters:
      name - The property name.
      defaultValue - A value to receive if the value is missing or invalid.
      defaultIfBlank - true to treat blank string values the same as null values.
      Returns:
      The value of the named property, or defaultValue, based on the stored value, as described above.

    • setInteger

      public void setInteger(String name, Integer value)
      Sets an Integer property. Replaces any previous value for the given property name. If value is null, ignore (do not write).
      Parameters:
      name - The property name.
      value - The property value.

    • getInteger

      public Integer getInteger(String name, Integer defaultValue)
      Attempts to retrieve an Integer value for the named property. If no such named property exists, or if the stored value cannot be converted to an Integer, then defaultValue is returned.
      Parameters:
      name - The property name.
      defaultValue - A value to receive if no such property exists.
      Returns:
      The value of the named property, or defaultValue if no such property or not an int.

    • setBoolean

      public void setBoolean(String name, Boolean value)
      Sets a Boolean value for the given property name. Replaces any previous value for the named property. If value is null, ignore.
      Parameters:
      name - The property name.
      value - The property value.

    • getBoolean

      public Boolean getBoolean(String name, Boolean defaultValue)
      Attempts to retrieve a Boolean value for the named property. If no such named property exists, then defaultValue is returned. Any of the following values will be considered valid boolean "true" values: "true", "1", "yes", "on", or "enabled". Any other property value will be considered "false".
      Parameters:
      name - The property name.
      defaultValue - A value to receive if no such property exists.
      Returns:
      The value of the named property, or defaultValue if no such property exists.

    • setFloat

      public void setFloat(String name, Float value)
      Sets a Float property. Replaces any previous value for the given property name. If value is null, ignore.
      Parameters:
      name - The property name.
      value - The property value.

    • getFloat

      public Float getFloat(String name, Float defaultValue)
      Attempts to retrieve a Float value for the named property. If no such named property exists, or if the stored value cannot be converted to a Float, then defaultValue is returned.
      Parameters:
      name - The property name.
      defaultValue - A value to receive if no such property exists.
      Returns:
      The value of the named property, or defaultValue if no such property or not a float.

    • setDouble

      public void setDouble(String name, Double value)
      Sets a Double property. Replaces any previous value for the given property name. If value is null, ignore.
      Parameters:
      name - The property name.
      value - The property value.

    • getDouble

      public Double getDouble(String name, Double defaultValue)
      Attempts to retrieve a Double value for the named property. If no such named property exists, or if the stored value cannot be converted to a Double, then defaultValue is returned.
      Parameters:
      name - The property name.
      defaultValue - A value to receive if no such property exists.
      Returns:
      The value of the named property, or defaultValue if no such property or not a double.

    • setColor

      public void setColor(String name, Color value)
      Sets a Color property. Replaces any previous value for the given property name. Color values are written as Strings in the form "0xAARRGGBB". If value is null, ignore.
      Parameters:
      name - The property name.
      value - The property value.

    • getColor

      public Color getColor(String name, Color defaultValue)
      Attempts to retrieve a Color value for the named property. If no such named property exists, then defaultValue is returned. Color values may be stored as Strings in the form "0xAARRGGBB", or "0xRRGGBB" with no alpha value, or in the legacy format of a simple integer representation of the rgb value (deprecated but will still be read here).
      Parameters:
      name - The property name
      defaultValue - The value to receive if no such property exists.
      Returns:
      The value of the named property, or defaultValue if no such property exists.

    • setFont

      public void setFont(String name, Font value)
      Sets a Font value, replacing any previous value with that name. If value is null, ignore. Internally, Font objects are split into five properties:
      • font family name
      • font face name
      • is bold
      • is italic
      • point size
      These are transparently read back into a single Font instance by the getFont() method.
      Parameters:
      name - The name of the property to set.
      value - The Font object to set.

    • getFont

      public Font getFont(String name, Font defaultValue)
      Reads the various Font properties associated with the given name and returns a Font object that encapsulates them. For example, getFont("myFont" ...) will actually look for five different properties:
      • myFont_familyName
      • myFont_faceName
      • myFont_isBold
      • myFont_isItalic
      • myFont_pointSize
      This is transparent to the caller, as we simply return a Font object here.
      Parameters:
      name - The property name of this font.
      defaultValue - A Font to use if the named property does not exist.
      Returns:
      A Font object loaded from props, or defaultValue if something went wrong.

    • encodeColor

      public static String encodeColor(Color color)
      Encodes the given Color to a String in the format 0xAARRGGBB, where AA is the alpha value from 00 to FF, RR is the red value, GG is the green value, and BB is the blue value.

    • decodeColor

      public static Color decodeColor(String input) throws NumberFormatException
      Attempts to decode a Color value from the given String. The formats accepted are:
      • "0xAARRGGBB" (alpha, red, green blue)
      • "0xRRGGBB" (red, green, blue with implied full opacity)
      • an integer rgb value as received from Color.getRGB()
      If the input is null or empty, you'll get null. You may also get a NumberFormatException if the given string makes no sense.
      Throws:
      NumberFormatException

    • createFontFromAttributes

      public static Font createFontFromAttributes(String fontFamilyName, boolean isBold, boolean isItalic, int pointSize)
      Translate between discrete font style properties and the weird way that java.awt.Font represents them.