Interface PropertyMap


public interface PropertyMap
An immutable typed key-value store for various settings.

A property map can store string-keyed values of various primitive types, nested property maps, and uniformly typed (ordered) collections of values. Because it is immutable, it can be passed around between objects without worrying about thread safety. Null values cannot be stored

To create a PropertyMap, use PropertyMaps.builder().

Property maps can be converted to a specific JSON format and back in a type-preserving manner.

Property maps are similar in concept to Properties but stores typed values rather than just strings, and supports storage of nested property maps.

Methods to access primitive types

PropertyMap pm = ...
pm.containsLong("key"); // - true if "key" exists and type is long
pm.getLong("key", 0L);  // - 0L if "key" is missing
                        // Throws ClassCastException if value is wrong type
pm.containsLongList("key2"); // - true if "key2" exists and type is
                          // collection of longs
pm.getLongList("key2")       // - long[] {} if "key2" is missing
                          // Throws ClassCastException if value is wrong type
pm.getLongList("key2", 0L, 1L, 2L) // - long[] { 0, 1, 2 } if "key2" is missing
pm.getLongList("key2", new ArrayList<Long>());
                          // Return List<Long>, or
                          // the empty arraylist
pm.getLongList("key2", null); // - (List<Long>) null if "key2" missing
Note that, for the collections (plural) get methods, the returned value is an array (long[] if the default value was given as an array or varargs, whereas it is a list (List<long>) if the default value was given as any collection or iterable. The same pattern applies to boolean, byte, short, int, long, float, and double. (No char or void, this is intentional.)

Methods to access primitive types

pm.containsString("key3");
pm.getString("key3", "foo");
pm.containsStringList("key4");
// The following both return List<String>:
pm.getStringList("key4", "a", "b", "c"); // Default = List of "a", "b", "c"
pm.getStringList("key4", listOfStrings);
This differs from the case of primitive types in that the collection (plural) get methods return a List regardless of the type of the default value. The same pattern applies to String, Color, AffineTransform, Rectangle, Dimension, Point, and nested PropertyMap.

Methods to access enum types
Enum values can be stored by automatically converting to String. See containsStringForEnum(String, Class), containsStringListForEnumList(String, Class), getStringAsEnum(String, Class, E), and getStringListAsEnumList(String, Class, E...). This is useful for storing multiple-choice settings.

For how to insert values of the various types, see PropertyMap.Builder.

  • Method Details

    • copyBuilder

      PropertyMap.Builder copyBuilder()
    • keySet

      Set<String> keySet()
      Return an unmodifiable set containing all of the keys.
      Returns:
      the set of keys
    • containsKey

      boolean containsKey(String key)
    • containsAll

      boolean containsAll(Collection<?> keys)
    • isEmpty

      boolean isEmpty()
    • size

      int size()
    • getValueTypeForKey

      Class<?> getValueTypeForKey(String key)
      Return a class indicating the type of the value for the given key.

      This method is intended for special code that handles serialization or conversion of property maps. In most cases, code that uses PropertyMap as a container for settings or data should use a fixed, pre-determined type for each key.

      For object (non-primitive) types, the class is returned (e.g. String.class, PropertyMap.class).

      For primitive types, the primitive type class is returned (e.g. int.class, float.class). Note that int.class != Integer.class.

      For collection (plural) types, the corresponding array type is returned (e.g. int[].class, String[].class).

      Keys stored as "EnumAsString" return String.class.

      Parameters:
      key - Key to the property
      Returns:
      the class representing the type of the value for key
      Throws:
      IllegalArgumentException - if key is not found
    • getAsOpaqueValue

      PropertyMap.OpaqueValue getAsOpaqueValue(String key)
    • getValueAsString

      String getValueAsString(String key, String aDefault)
    • containsBoolean

      boolean containsBoolean(String key)
    • getBoolean

      @Deprecated Boolean getBoolean(String key)
      Deprecated.
    • getBoolean

      @Deprecated Boolean getBoolean(String key, Boolean aDefault)
      Deprecated.
    • getBoolean

      boolean getBoolean(String key, boolean aDefault)
    • containsBooleanList

      boolean containsBooleanList(String key)
    • getBooleanList

      boolean[] getBooleanList(String key, boolean... defaults)
    • getBooleanList

      List<Boolean> getBooleanList(String key, Iterable<Boolean> defaults)
    • containsByte

      boolean containsByte(String key)
    • getByte

      byte getByte(String key, byte aDefault)
    • containsByteList

      boolean containsByteList(String key)
    • getByteList

      byte[] getByteList(String key, byte... defaults)
    • getByteList

      List<Byte> getByteList(String key, Iterable<Byte> defaults)
    • containsShort

      boolean containsShort(String key)
    • getShort

      short getShort(String key, short aDefault)
    • containsShortList

      boolean containsShortList(String key)
    • getShortList

      short[] getShortList(String key, short... defaults)
    • getShortList

      List<Short> getShortList(String key, Iterable<Short> defaults)
    • containsInteger

      boolean containsInteger(String key)
    • getInteger

      int getInteger(String key, int aDefault)
    • containsIntegerList

      boolean containsIntegerList(String key)
    • getIntegerList

      int[] getIntegerList(String key, int... defaults)
    • getIntegerList

      List<Integer> getIntegerList(String key, Iterable<Integer> defaults)
    • containsLong

      boolean containsLong(String key)
    • getLong

      @Deprecated Long getLong(String key)
      Deprecated.
    • getLong

      @Deprecated Long getLong(String key, Long aDefault)
      Deprecated.
    • getLong

      long getLong(String key, long aDefault)
    • containsLongList

      boolean containsLongList(String key)
    • getLongList

      long[] getLongList(String key, long... defaults)
    • getLongList

      List<Long> getLongList(String key, Iterable<Long> defaults)
    • containsFloat

      boolean containsFloat(String key)
    • getFloat

      float getFloat(String key, float aDefault)
    • containsFloatList

      boolean containsFloatList(String key)
    • getFloatList

      float[] getFloatList(String key, float... defaults)
    • getFloatList

      List<Float> getFloatList(String key, Iterable<Float> defaults)
    • containsDouble

      boolean containsDouble(String key)
    • getDouble

      @Deprecated Double getDouble(String key)
      Deprecated.
    • getDouble

      @Deprecated Double getDouble(String key, Double aDefault)
      Deprecated.
    • getDouble

      double getDouble(String key, double aDefault)
    • containsDoubleList

      boolean containsDoubleList(String key)
    • getDoubleList

      double[] getDoubleList(String key, double... defaults)
    • getDoubleList

      List<Double> getDoubleList(String key, Iterable<Double> defaults)
    • containsNumber

      boolean containsNumber(String key)
    • getAsNumber

      Number getAsNumber(String key, Number aDefault)
      Retrieve a numerical value, without checking its specific type.

      This method may be useful for providing backward compatibility (for example, if a value currently stored as a long used to be stored as an int). It should not be used when the type-specific get method can be used.

      Code that calls this method should be prepared to handle any of the following types correctly: Byte, Short, Integer, Long, Float, Double.

      Parameters:
      key - Key to the property
      aDefault - Default value to be used if the property was not a number or not found
      Returns:
      Number value of the property
    • containsNumberList

      boolean containsNumberList(String key)
    • getAsNumberList

      List<Number> getAsNumberList(String key, Number... defaults)
    • getAsNumberList

      List<Number> getAsNumberList(String key, Iterable<Number> defaults)
    • containsString

      boolean containsString(String key)
    • getString

      @Deprecated String getString(String key)
      Deprecated.
    • getString

      String getString(String key, String aDefault)
    • containsStringList

      boolean containsStringList(String key)
    • getStringList

      List<String> getStringList(String key, String... defaults)
    • getStringList

      List<String> getStringList(String key, Iterable<String> defaults)
    • containsUUID

      boolean containsUUID(String key)
    • getUUID

      UUID getUUID(String key, UUID aDefault)
    • containsUUIDList

      boolean containsUUIDList(String key)
    • getUUIDList

      List<UUID> getUUIDList(String key, UUID... defaults)
    • getUUIDList

      List<UUID> getUUIDList(String key, Iterable<UUID> defaults)
    • containsColor

      boolean containsColor(String key)
    • getColor

      Color getColor(String key, Color aDefault)
    • containsColorList

      boolean containsColorList(String key)
    • getColorList

      List<Color> getColorList(String key, Color... defaults)
    • getColorList

      List<Color> getColorList(String key, Iterable<Color> defaults)
    • containsAffineTransform

      boolean containsAffineTransform(String key)
    • getAffineTransform

      AffineTransform getAffineTransform(String key, AffineTransform aDefault)
    • containsAffineTransformList

      boolean containsAffineTransformList(String key)
    • getAffineTransformList

      List<AffineTransform> getAffineTransformList(String key, AffineTransform... defaults)
    • getAffineTransformList

      List<AffineTransform> getAffineTransformList(String key, Iterable<AffineTransform> defaults)
    • containsPropertyMap

      boolean containsPropertyMap(String key)
    • getPropertyMap

      @Deprecated PropertyMap getPropertyMap(String key)
      Deprecated.
    • getPropertyMap

      PropertyMap getPropertyMap(String key, PropertyMap aDefault)
    • containsPropertyMapList

      boolean containsPropertyMapList(String key)
    • getPropertyMapList

      List<PropertyMap> getPropertyMapList(String key, PropertyMap... defaults)
    • getPropertyMapList

      List<PropertyMap> getPropertyMapList(String key, Iterable<PropertyMap> defaults)
    • containsRectangle

      boolean containsRectangle(String key)
    • getRectangle

      Rectangle getRectangle(String key, Rectangle aDefault)
    • containsRectangleList

      boolean containsRectangleList(String key)
    • getRectangleList

      List<Rectangle> getRectangleList(String key, Rectangle... defaults)
    • getRectangleList

      List<Rectangle> getRectangleList(String key, Iterable<Rectangle> defaults)
    • containsDimension

      boolean containsDimension(String key)
    • getDimension

      Dimension getDimension(String key, Dimension aDefault)
    • containsDimensionList

      boolean containsDimensionList(String key)
    • getDimensionList

      List<Dimension> getDimensionList(String key, Dimension... defaults)
    • getDimensionList

      List<Dimension> getDimensionList(String key, Iterable<Dimension> defaults)
    • containsPoint

      boolean containsPoint(String key)
    • getPoint

      Point getPoint(String key, Point aDefault)
    • containsPointList

      boolean containsPointList(String key)
    • getPointList

      List<Point> getPointList(String key, Point... defaults)
    • getPointList

      List<Point> getPointList(String key, Iterable<Point> defaults)
    • containsStringForEnum

      <E extends Enum<E>> boolean containsStringForEnum(String key, Class<E> enumType)
    • getStringAsEnum

      <E extends Enum<E>> E getStringAsEnum(String key, Class<E> enumType, E aDefault)
      Get a string value, converted to an enum value.

      The property map does not record the specific class of enum values. It is the caller's responsibility to specify the correct enum class.

      If the value stored in the property map is not one of the allowed values for enumType, aDefault will be returned.

      Type Parameters:
      E - the enum class
      Parameters:
      key - the property key
      enumType - the enum class
      aDefault - a default value to return if the key is missing or the stored value is an enum but not a known value for the given enum class.
      Returns:
      the enum value for key
    • containsStringListForEnumList

      <E extends Enum<E>> boolean containsStringListForEnumList(String key, Class<E> enumType)
    • getStringListAsEnumList

      <E extends Enum<E>> List<E> getStringListAsEnumList(String key, Class<E> enumType, E... defaults)
    • getStringListAsEnumList

      <E extends Enum<E>> List<E> getStringListAsEnumList(String key, Class<E> enumType, Iterable<E> defaults)
      Get a collection of strings, converted to a collection of enum values.

      The property map does not record the specific class of enum values. It is the caller's responsibility to specify the correct enum class.

      Unless all of the values stored in the property map are allowed values of enumType, defaults will be returned.

      Type Parameters:
      E - the enum class
      Parameters:
      key - the property key
      enumType - the enum class
      defaults - a default collection
      Returns:
      the list of enum values for key
    • toJSON

      String toJSON()
      Create a JSON representation of this property map.

      To create a property map back from the JSON representation, see PropertyMaps.fromJSON(String).

      Returns:
      the JSON-serialized contents
    • saveJSON

      boolean saveJSON(File file, boolean overwrite, boolean createBackup) throws IOException
      Save to a file as JSON.

      To create a property map back from the saved file, see PropertyMaps.loadJSON(File).

      Parameters:
      file - the file to write to
      overwrite - if false and file exists, don't write and return false
      createBackup - if true and overwriting, first rename the existing file by appending "~" to its name
      Returns:
      true if the file was successfully written
      Throws:
      IOException - if there was an error writing to the file
    • copy

    • getStringArray

      @Deprecated String[] getStringArray(String key)
      Deprecated.
    • getStringArray

      @Deprecated String[] getStringArray(String key, String[] aDefault)
      Deprecated.
    • getInt

      @Deprecated Integer getInt(String key)
      Deprecated.
    • getInt

      @Deprecated Integer getInt(String key, Integer aDefault)
      Deprecated.
    • getIntArray

      @Deprecated Integer[] getIntArray(String key)
      Deprecated.
    • getIntArray

      @Deprecated Integer[] getIntArray(String key, Integer[] aDefault)
      Deprecated.
    • getLongArray

      @Deprecated Long[] getLongArray(String key)
      Deprecated.
    • getLongArray

      @Deprecated Long[] getLongArray(String key, Long[] aDefault)
      Deprecated.
    • getDoubleArray

      @Deprecated Double[] getDoubleArray(String key)
      Deprecated.
    • getDoubleArray

      @Deprecated Double[] getDoubleArray(String key, Double[] aDefault)
      Deprecated.
    • getBooleanArray

      @Deprecated Boolean[] getBooleanArray(String key)
      Deprecated.
    • getBooleanArray

      @Deprecated Boolean[] getBooleanArray(String key, Boolean[] aDefault)
      Deprecated.
    • merge

      Deprecated.
    • getKeys

      @Deprecated Set<String> getKeys()
      Deprecated.
    • getPropertyType

      @Deprecated Class<?> getPropertyType(String key)
      Deprecated.
    • save

      @Deprecated void save(String path) throws IOException
      Deprecated.
      Throws:
      IOException