Interface PropertyMap
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.
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interfaceBuilder forPropertyMap.static interfaceA value that can be stored in a property map.static interfaceDeprecated.static classDeprecated.If necessary, catch ClassCastException instead. -
Method Summary
Modifier and TypeMethodDescriptionbooleanbooleanbooleancontainsAll(Collection<?> keys) booleancontainsBoolean(String key) booleanbooleancontainsByte(String key) booleancontainsByteList(String key) booleancontainsColor(String key) booleancontainsColorList(String key) booleancontainsDimension(String key) booleanbooleancontainsDouble(String key) booleancontainsDoubleList(String key) booleancontainsFloat(String key) booleancontainsFloatList(String key) booleancontainsInteger(String key) booleanbooleancontainsKey(String key) booleancontainsLong(String key) booleancontainsLongList(String key) booleancontainsNumber(String key) booleancontainsNumberList(String key) booleancontainsPoint(String key) booleancontainsPointList(String key) booleanbooleanbooleancontainsRectangle(String key) booleanbooleancontainsShort(String key) booleancontainsShortList(String key) booleancontainsString(String key) <E extends Enum<E>>
booleancontainsStringForEnum(String key, Class<E> enumType) booleancontainsStringList(String key) <E extends Enum<E>>
booleancontainsStringListForEnumList(String key, Class<E> enumType) booleancontainsUUID(String key) booleancontainsUUIDList(String key) copy()Deprecated.getAffineTransform(String key, AffineTransform aDefault) getAffineTransformList(String key, AffineTransform... defaults) getAffineTransformList(String key, Iterable<AffineTransform> defaults) getAsNumber(String key, Number aDefault) Retrieve a numerical value, without checking its specific type.getAsNumberList(String key, Iterable<Number> defaults) getAsNumberList(String key, Number... defaults) getAsOpaqueValue(String key) getBoolean(String key) Deprecated.booleangetBoolean(String key, boolean aDefault) getBoolean(String key, Boolean aDefault) Deprecated.Boolean[]getBooleanArray(String key) Deprecated.Boolean[]getBooleanArray(String key, Boolean[] aDefault) Deprecated.boolean[]getBooleanList(String key, boolean... defaults) getBooleanList(String key, Iterable<Boolean> defaults) bytebyte[]getByteList(String key, byte... defaults) getByteList(String key, Iterable<Byte> defaults) getColorList(String key, Color... defaults) getColorList(String key, Iterable<Color> defaults) getDimension(String key, Dimension aDefault) getDimensionList(String key, Dimension... defaults) getDimensionList(String key, Iterable<Dimension> defaults) Deprecated.doubleDeprecated.Double[]getDoubleArray(String key) Deprecated.Double[]getDoubleArray(String key, Double[] aDefault) Deprecated.double[]getDoubleList(String key, double... defaults) getDoubleList(String key, Iterable<Double> defaults) floatfloat[]getFloatList(String key, float... defaults) getFloatList(String key, Iterable<Float> defaults) Deprecated.Deprecated.Integer[]getIntArray(String key) Deprecated.Integer[]getIntArray(String key, Integer[] aDefault) Deprecated.intgetInteger(String key, int aDefault) int[]getIntegerList(String key, int... defaults) getIntegerList(String key, Iterable<Integer> defaults) getKeys()Deprecated.Deprecated.longDeprecated.Long[]getLongArray(String key) Deprecated.Long[]getLongArray(String key, Long[] aDefault) Deprecated.long[]getLongList(String key, long... defaults) getLongList(String key, Iterable<Long> defaults) getPointList(String key, Point... defaults) getPointList(String key, Iterable<Point> defaults) getPropertyMap(String key) Deprecated.getPropertyMap(String key, PropertyMap aDefault) getPropertyMapList(String key, Iterable<PropertyMap> defaults) getPropertyMapList(String key, PropertyMap... defaults) Class<?> getPropertyType(String key) Deprecated.getRectangle(String key, Rectangle aDefault) getRectangleList(String key, Rectangle... defaults) getRectangleList(String key, Iterable<Rectangle> defaults) shortshort[]getShortList(String key, short... defaults) getShortList(String key, Iterable<Short> defaults) Deprecated.String[]getStringArray(String key) Deprecated.String[]getStringArray(String key, String[] aDefault) Deprecated.<E extends Enum<E>>
EgetStringAsEnum(String key, Class<E> enumType, E aDefault) Get a string value, converted to an enum value.getStringList(String key, Iterable<String> defaults) getStringList(String key, String... defaults) getStringListAsEnumList(String key, Class<E> enumType, E... defaults) getStringListAsEnumList(String key, Class<E> enumType, Iterable<E> defaults) Get a collection of strings, converted to a collection of enum values.getUUIDList(String key, Iterable<UUID> defaults) getUUIDList(String key, UUID... defaults) getValueAsString(String key, String aDefault) Class<?> getValueTypeForKey(String key) Return a class indicating the type of the value for the given key.booleanisEmpty()keySet()Return an unmodifiable set containing all of the keys.merge(PropertyMap alt) Deprecated.voidDeprecated.booleanSave to a file as JSON.intsize()toJSON()Create a JSON representation of this property map.
-
Method Details
-
copyBuilder
PropertyMap.Builder copyBuilder() -
keySet
-
containsKey
-
containsAll
-
isEmpty
boolean isEmpty() -
size
int size() -
getValueTypeForKey
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 thatint.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- ifkeyis not found
-
getAsOpaqueValue
-
getValueAsString
-
containsBoolean
-
getBoolean
Deprecated. -
getBoolean
Deprecated. -
getBoolean
-
containsBooleanList
-
getBooleanList
-
getBooleanList
-
containsByte
-
getByte
-
containsByteList
-
getByteList
-
getByteList
-
containsShort
-
getShort
-
containsShortList
-
getShortList
-
getShortList
-
containsInteger
-
getInteger
-
containsIntegerList
-
getIntegerList
-
getIntegerList
-
containsLong
-
getLong
Deprecated. -
getLong
Deprecated. -
getLong
-
containsLongList
-
getLongList
-
getLongList
-
containsFloat
-
getFloat
-
containsFloatList
-
getFloatList
-
getFloatList
-
containsDouble
-
getDouble
Deprecated. -
getDouble
Deprecated. -
getDouble
-
containsDoubleList
-
getDoubleList
-
getDoubleList
-
containsNumber
-
getAsNumber
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
longused to be stored as anint). 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 propertyaDefault- Default value to be used if the property was not a number or not found- Returns:
- Number value of the property
-
containsNumberList
-
getAsNumberList
-
getAsNumberList
-
containsString
-
getString
Deprecated. -
getString
-
containsStringList
-
getStringList
-
getStringList
-
containsUUID
-
getUUID
-
containsUUIDList
-
getUUIDList
-
getUUIDList
-
containsColor
-
getColor
-
containsColorList
-
getColorList
-
getColorList
-
containsAffineTransform
-
getAffineTransform
-
containsAffineTransformList
-
getAffineTransformList
-
getAffineTransformList
-
containsPropertyMap
-
getPropertyMap
Deprecated. -
getPropertyMap
-
containsPropertyMapList
-
getPropertyMapList
-
getPropertyMapList
-
containsRectangle
-
getRectangle
-
containsRectangleList
-
getRectangleList
-
getRectangleList
-
containsDimension
-
getDimension
-
containsDimensionList
-
getDimensionList
-
getDimensionList
-
containsPoint
-
getPoint
-
containsPointList
-
getPointList
-
getPointList
-
containsStringForEnum
-
getStringAsEnum
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,aDefaultwill be returned.- Type Parameters:
E- the enum class- Parameters:
key- the property keyenumType- the enum classaDefault- 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
-
getStringListAsEnumList
-
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,defaultswill be returned.- Type Parameters:
E- the enum class- Parameters:
key- the property keyenumType- the enum classdefaults- 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
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 tooverwrite- if false and file exists, don't write and return falsecreateBackup- 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
Deprecated. -
getStringArray
Deprecated. -
getStringArray
Deprecated. -
getInt
Deprecated. -
getInt
Deprecated. -
getIntArray
Deprecated. -
getIntArray
Deprecated. -
getLongArray
Deprecated. -
getLongArray
Deprecated. -
getDoubleArray
Deprecated. -
getDoubleArray
Deprecated. -
getBooleanArray
Deprecated. -
getBooleanArray
Deprecated. -
merge
Deprecated. -
getKeys
Deprecated. -
getPropertyType
Deprecated. -
save
-