Package org.rapidcontext.core.data

Class Dict

java.lang.Object
org.rapidcontext.core.data.Dict
public class Dict extends Object
A general data dictionary. Compared to the standard Map interface, this class provides a number of improvements;
  • Access Methods -- Methods to provide easy access to integer, boolean and string values without casting.
  • Sealing -- Simple creation of read-only objects.
  • Deep Copies -- Provides a meaningful way to clone or copy data.
  • Serialization -- Utility classes are available for serializing to JSON, XML, etc.
  • Debug Info -- The toString() method provides a more usable default implementation.
A dictionary is more or less a hash table with name and value pairs. The names are non-empty strings and values may have any type, but recommended types are String, Integer, Boolean, Dict and Array. Circular or self-referencing structures should not be used, since most data serialization cannot handle them.
Version:
1.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected static final String[]
    OFF
    All the recognized false values.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Dict()
    Creates a new empty dictionary.
    Dict(int initialCapacity)
    Creates a new empty dictionary.

  • Method Summary

    Modifier and Type
    Method
    Description
    Dict
    add(String key, Object value)
    Adds a dictionary value using the specified key if possible.
    boolean
    containsKey(String key)
    Checks if the specified key is defined in this dictionary.
    boolean
    containsValue(Object value)
    Checks if the specified value is contained in this dictionary.
    protected static <T> T
    convert(Object value, Class<T> clazz)
    Converts a value to a specified object class.
    Dict
    copy()
    Creates a copy of this dictionary.
    boolean
    equals(Object obj)
    Checks if this dictionary is identical to another one.
    static Dict
    from(Map<?,?> map)
    Creates a new dictionary containing all entries in a map.
    Object
    get(String key)
    Returns the dictionary value for the specified key.
    <T> T
    get(String key, Class<T> clazz)
    Returns the dictionary value for the specified key.
    <T> T
    get(String key, Class<T> clazz, T defaultValue)
    Returns the dictionary value for the specified key.
    Object
    get(String key, Object defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(key, Object.class, defaultValue) instead.
    Array
    getArray(String key)
    Returns the dictionary array value for the specified key.
    boolean
    getBoolean(String key, boolean defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(key, Boolean.class, defaultValue) instead.
    Date
    getDate(String key, Date defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(key, Date.class, defaultValue) instead.
    Dict
    getDict(String key)
    Returns the dictionary dictionary value for the specified key.
    int
    getInt(String key, int defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(key, Integer.class, defaultValue) instead.
    String
    getString(String key, String defaultValue)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use get(key, String.class, defaultValue) instead.
    int
    hashCode()
    Returns a hash code for this object.
    boolean
    isSealed()
    Checks if this dictionary is sealed.
    String
    keyOf(Object value)
    Returns the first dictionary key having the specified value.
    String[]
    keys()
    Returns an array with all the defined dictionary key names.
    Dict
    merge(Dict dict)
    Modifies all keys provided in another dictionary.
    Dict
    remove(String key)
    Deletes the specified dictionary key and its value.
    void
    seal(boolean recursive)
    Seals this dictionary and prohibits further modifications.
    Dict
    set(String key, Object value)
    Modifies or defines the dictionary value for the specified key.
    Dict
    setAll(Dict dict)
    Modifies or defines all keys from another dictionary.
    Dict
    setBoolean(String key, boolean value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use set(key, value) with auto-boxing instead.
    Dict
    setDefault(String key, Object value)
    Sets a dictionary value if not already defined.
    Dict
    setIfNull(String key, Supplier<Object> supplier)
    Sets a dictionary value if not already defined.
    Dict
    setInt(String key, int value)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use set(key, value) with auto-boxing instead.
    int
    size()
    Returns the size of the dictionary, i.e.
    Stream<Map.Entry<String,Object>>
    stream()
    Returns a stream of all entries in the dictionary.
    <T> Stream<Map.Entry<String,T>>
    stream(Class<T> clazz)
    Returns a stream of all entries in the dictionary.
    String
    toString()
    Returns a string representation of this object.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • OFF

      protected static final String[] OFF
      All the recognized false values.

  • Constructor Details

    • Dict

      public Dict()
      Creates a new empty dictionary.

    • Dict

      public Dict(int initialCapacity)
      Creates a new empty dictionary. By default a dictionary is created with a null key map, but if this constructor is used the map will be initialized with the specified capacity.
      Parameters:
      initialCapacity - the initial dictionary capacity

  • Method Details

    • convert

      protected static <T> T convert(Object value, Class<T> clazz)
      Converts a value to a specified object class. The value is either converted (as below) or casted.

      If the object class is String (and the value isn't), the string representation will be returned. Any Date object will instead be converted to "\@millis".

      If the object class is Boolean (and the value isn't), the string representation that does not equal "", "0", "f", "false", "no" or "off" is considered true.

      If the object class is Integer or Long (and the value isn't), a numeric conversion of the string representation will be attempted.

      If the object class is Date (and the value isn't), a number conversion (to milliseconds) of the string representation (excluding any '@' prefix) will be attempted.

      Type Parameters:
      T - the object type to return
      Parameters:
      value - the object value
      clazz - the object class
      Returns:
      the converted or casted value
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number

    • from

      public static Dict from(Map<?,?> map)
      Creates a new dictionary containing all entries in a map. All map keys will be converted to String via Objects.toString(). Any iterable or map values will be converted to Array or Dict recursively.
      Parameters:
      map - the map to copy
      Returns:
      a new array with all provided entries

    • equals

      public boolean equals(Object obj)
      Checks if this dictionary is identical to another one. The two dictionaries will be considered equal if they have the same size and all keys and values are equal.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with
      Returns:
      true if the two dictionaries are equal, or false otherwise

    • hashCode

      public int hashCode()
      Returns a hash code for this object.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code for this object

    • toString

      public String toString()
      Returns a string representation of this object.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this object

    • stream

      public Stream<Map.Entry<String,Object>> stream()
      Returns a stream of all entries in the dictionary.
      Returns:
      the entry object stream

    • stream

      public <T> Stream<Map.Entry<String,T>> stream(Class<T> clazz)
      Returns a stream of all entries in the dictionary.
      Type Parameters:
      T - the value object type to return
      Parameters:
      clazz - the value object class
      Returns:
      the entry object stream
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:

    • copy

      public Dict copy()
      Creates a copy of this dictionary. The copy is a "deep copy", as all dictionary and array values will be recursively copied.
      Returns:
      a deep copy of this object

    • isSealed

      public boolean isSealed()
      Checks if this dictionary is sealed.
      Returns:
      true if this dictionary has been sealed, or false otherwise

    • seal

      public void seal(boolean recursive)
      Seals this dictionary and prohibits further modifications. If the seal is applied recursively, any dictionary or array values in this object will also be sealed. Once sealed, this instance is an immutable read-only object.
      Parameters:
      recursive - the recursive flag

    • size

      public int size()
      Returns the size of the dictionary, i.e. the number of keys in it.
      Returns:
      the size of the dictionary, or zero (0) if empty

    • containsKey

      public boolean containsKey(String key)
      Checks if the specified key is defined in this dictionary. Note that a key name may be defined but still contain a null value.
      Parameters:
      key - the key name
      Returns:
      true if the key is defined, or false otherwise

    • containsValue

      public boolean containsValue(Object value)
      Checks if the specified value is contained in this dictionary. Note that equals() comparison is used, so only simple values may be checked.
      Parameters:
      value - the value to check for
      Returns:
      true if the value exists, or false otherwise

    • keyOf

      public String keyOf(Object value)
      Returns the first dictionary key having the specified value. Note that equals() comparison is used, so only simple values may be checked.
      Parameters:
      value - the value to check for
      Returns:
      the dictionary key name, or null if the value wasn't found

    • keys

      public String[] keys()
      Returns an array with all the defined dictionary key names. The keys are ordered as originally added to this object.
      Returns:
      an array with all dictionary key names

    • get

      public Object get(String key)
      Returns the dictionary value for the specified key.
      Parameters:
      key - the dictionary key name
      Returns:
      the dictionary key value, or null if the key or value is not defined

    • get

      public <T> T get(String key, Class<T> clazz)
      Returns the dictionary value for the specified key. The value is either converted or casted to a specified object class.
      Type Parameters:
      T - the object type to return
      Parameters:
      key - the dictionary key name
      clazz - the object class
      Returns:
      the dictionary key value value, or null if the key or value is not defined
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:

    • get

      @Deprecated(forRemoval=true) public Object get(String key, Object defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(key, Object.class, defaultValue) instead.
      Returns the dictionary value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead.
      Parameters:
      key - the dictionary key name
      defaultValue - the default value
      Returns:
      the dictionary key value value, or the default value if the key or value is not defined

    • get

      public <T> T get(String key, Class<T> clazz, T defaultValue)
      Returns the dictionary value for the specified key. The value is either converted or casted to a specified object class. If the key is not defined or if the value is set to null, a default value will be returned instead.
      Type Parameters:
      T - the object type to return
      Parameters:
      key - the dictionary key name
      clazz - the object class
      defaultValue - the default value
      Returns:
      the dictionary key value value, or the default value if the key or value is not defined
      Throws:
      ClassCastException - if the wasn't possible to cast to the specified object class
      NumberFormatException - if the value wasn't possible to parse as a number
      See Also:

    • getString

      @Deprecated(forRemoval=true) public String getString(String key, String defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(key, String.class, defaultValue) instead.
      Returns the dictionary string value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a string, the toString() method will be called.
      Parameters:
      key - the dictionary key name
      defaultValue - the default value
      Returns:
      the dictionary key value, or the default value if the key or value is not defined

    • getBoolean

      @Deprecated(forRemoval=true) public boolean getBoolean(String key, boolean defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(key, Boolean.class, defaultValue) instead.
      Returns the dictionary boolean value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a boolean, any object that does not equal "", "0", "f", "false", "no" or "off" is considered true.
      Parameters:
      key - the dictionary key name
      defaultValue - the default value
      Returns:
      the dictionary key value, or the default value if the key or value is not defined

    • getInt

      @Deprecated(forRemoval=true) public int getInt(String key, int defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(key, Integer.class, defaultValue) instead.
      Returns the dictionary integer value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a number, a conversion of the toString() value of the object will be attempted.
      Parameters:
      key - the dictionary key name
      defaultValue - the default value
      Returns:
      the dictionary key value, or the default value if the key or value is not defined
      Throws:
      NumberFormatException - if the value wasn't possible to parse as an integer

    • getDate

      @Deprecated(forRemoval=true) public Date getDate(String key, Date defaultValue)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use get(key, Date.class, defaultValue) instead.
      Returns the dictionary date value for the specified key. If the key is not defined or if the value is set to null, a default value will be returned instead. If the value object is not a date, a numeric conversion of the string value (excluding any '@' prefix) will be attempted.
      Parameters:
      key - the dictionary key name
      defaultValue - the default value
      Returns:
      the dictionary key value, or the default value if the key or value is not defined
      Throws:
      NumberFormatException - if the value didn't contain a valid date, number or numeric string

    • getDict

      public Dict getDict(String key) throws ClassCastException
      Returns the dictionary dictionary value for the specified key. If the value is not a dictionary, an exception will be thrown.
      Parameters:
      key - the dictionary key name
      Returns:
      the dictionary key value, or an empty dictionary if the key or value is not defined
      Throws:
      ClassCastException - if the value is not a dictionary

    • getArray

      public Array getArray(String key) throws ClassCastException
      Returns the dictionary array value for the specified key. If the value is not an array, an exception will be thrown.
      Parameters:
      key - the dictionary key name
      Returns:
      the dictionary key value, or an empty array if the key or value is not defined
      Throws:
      ClassCastException - if the value is not an array

    • set

      public Dict set(String key, Object value) throws NullPointerException, UnsupportedOperationException
      Modifies or defines the dictionary value for the specified key.
      Parameters:
      key - the dictionary key name
      value - the value to set
      Returns:
      this dictionary for chained operations
      Throws:
      NullPointerException - if the key is null or an empty string
      UnsupportedOperationException - if this object has been sealed

    • setDefault

      public Dict setDefault(String key, Object value)
      Sets a dictionary value if not already defined.
      Parameters:
      key - the dictionary key name
      value - the value to set
      Returns:
      this dictionary for chained operations
      Throws:
      NullPointerException - if the key is null or an empty string
      UnsupportedOperationException - if this object has been sealed

    • setIfNull

      public Dict setIfNull(String key, Supplier<Object> supplier)
      Sets a dictionary value if not already defined.
      Parameters:
      key - the dictionary key name
      supplier - the supplier of the value
      Returns:
      this dictionary for chained operations
      Throws:
      NullPointerException - if the key is null or an empty string
      UnsupportedOperationException - if this object has been sealed

    • setBoolean

      @Deprecated(forRemoval=true) public Dict setBoolean(String key, boolean value) throws NullPointerException, UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use set(key, value) with auto-boxing instead.
      Modifies or defines the boolean dictionary value for the specified key.
      Parameters:
      key - the dictionary key name
      value - the value to set
      Returns:
      this dictionary for chained operations
      Throws:
      NullPointerException - if the key is null or an empty string
      UnsupportedOperationException - if this object has been sealed

    • setInt

      @Deprecated(forRemoval=true) public Dict setInt(String key, int value) throws NullPointerException, UnsupportedOperationException
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use set(key, value) with auto-boxing instead.
      Modifies or defines the integer dictionary value for the specified key.
      Parameters:
      key - the dictionary key name
      value - the value to set
      Returns:
      this dictionary for chained operations
      Throws:
      NullPointerException - if the key is null or an empty string
      UnsupportedOperationException - if this object has been sealed

    • setAll

      public Dict setAll(Dict dict)
      Modifies or defines all keys from another dictionary. If one of the keys already exists, it will be overwritten with the value from the specified dictionary.
      Parameters:
      dict - the dictionary to copy from
      Returns:
      this dictionary for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed

    • add

      public Dict add(String key, Object value) throws UnsupportedOperationException
      Adds a dictionary value using the specified key if possible. If the key is already in use, a new unique key will be generated instead. This will ensure that an existing value will not be overwritten.
      Parameters:
      key - the suggested dictionary key name
      value - the value to set
      Returns:
      this dictionary for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed

    • merge

      public Dict merge(Dict dict)
      Modifies all keys provided in another dictionary. If the value for a key is null, the key will be removed. Otherwise the key will be added or overwritten.
      Parameters:
      dict - the dictionary to copy from
      Returns:
      this dictionary for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed

    • remove

      public Dict remove(String key) throws UnsupportedOperationException
      Deletes the specified dictionary key and its value.
      Parameters:
      key - the dictionary key name
      Returns:
      this dictionary for chained operations
      Throws:
      UnsupportedOperationException - if this object has been sealed