Class JsonObject

  • All Implemented Interfaces:
    Jsonable, java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.String,​java.lang.Object>

    public class JsonObject
    extends java.util.HashMap<java.lang.String,​java.lang.Object>
    implements Jsonable
    JsonObject is a common non-thread safe data format for string to data mappings. The contents of a JsonObject are only validated as JSON values on serialization. Meaning all values added to a JsonObject must be recognized by the Jsoner for it to be a true 'JsonObject', so it is really a JsonableHashMap that will serialize to a JsonObject if all of its contents are valid JSON.
    Since:
    2.0.0
    See Also:
    Jsoner, Serialized Form
    • Nested Class Summary

      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>
      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>
    • Constructor Summary

      Constructors 
      Constructor Description
      JsonObject()
      Instantiates an empty JsonObject.
      JsonObject​(java.util.Map<java.lang.String,​?> map)
      Instantiate a new JsonObject by accepting a map's entries, which could lead to de/serialization issues of the resulting JsonObject since the entry values aren't validated as JSON values.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.math.BigDecimal getBigDecimal​(JsonKey key)
      A convenience method that assumes there is a BigDecimal, Number, or String at the given key.
      java.math.BigDecimal getBigDecimalOrDefault​(JsonKey key)
      A convenience method that assumes there is a BigDecimal, Number, or String at the given key.
      java.lang.Boolean getBoolean​(JsonKey key)
      A convenience method that assumes there is a Boolean or String value at the given key.
      java.lang.Boolean getBooleanOrDefault​(JsonKey key)
      A convenience method that assumes there is a Boolean or String value at the given key.
      java.lang.Byte getByte​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Byte getByteOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      <T extends java.util.Collection<?>>
      T
      getCollection​(JsonKey key)
      A convenience method that assumes there is a Collection at the given key.
      <T extends java.util.Collection<?>>
      T
      getCollectionOrDefault​(JsonKey key)
      A convenience method that assumes there is a Collection at the given key.
      java.lang.Double getDouble​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Double getDoubleOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Float getFloat​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Float getFloatOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Integer getInteger​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Integer getIntegerOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Long getLong​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Long getLongOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      <T extends java.util.Map<?,​?>>
      T
      getMap​(JsonKey key)
      A convenience method that assumes there is a Map at the given key.
      <T extends java.util.Map<?,​?>>
      T
      getMapOrDefault​(JsonKey key)
      A convenience method that assumes there is a Map at the given key.
      java.lang.Short getShort​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.Short getShortOrDefault​(JsonKey key)
      A convenience method that assumes there is a Number or String value at the given key.
      java.lang.String getString​(JsonKey key)
      A convenience method that assumes there is a Boolean, Number, or String value at the given key.
      java.lang.String getStringOrDefault​(JsonKey key)
      A convenience method that assumes there is a Boolean, Number, or String value at the given key.
      void put​(JsonKey key, java.lang.Object value)
      Convenience method that calls put for the given key and value.
      JsonObject putAllChain​(java.util.Map<java.lang.String,​java.lang.Object> map)
      Calls putAll for the given map, but returns the JsonObject for chaining calls.
      JsonObject putChain​(JsonKey key, java.lang.Object value)
      Convenience method that calls put for the given key and value, but returns the JsonObject for chaining calls.
      JsonObject putChain​(java.lang.String key, java.lang.Object value)
      Calls put for the given key and value, but returns the JsonObject for chaining calls.
      java.lang.Object remove​(JsonKey key)
      Convenience method that calls remove for the given key.
      boolean remove​(JsonKey key, java.lang.Object value)
      Convenience method that calls remove for the given key and value.
      void requireKeys​(JsonKey... keys)
      Ensures the given keys are present.
      java.lang.String toJson()
      Serialize to a JSON formatted string.
      void toJson​(java.io.Writer writable)
      Serialize to a JSON formatted stream.
      • Methods inherited from class java.util.HashMap

        clear, clone, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, forEach, get, getOrDefault, isEmpty, keySet, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size, values
      • Methods inherited from class java.util.AbstractMap

        equals, hashCode, toString
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.Map

        equals, hashCode
    • Constructor Detail

      • JsonObject

        public JsonObject()
        Instantiates an empty JsonObject.
      • JsonObject

        public JsonObject​(java.util.Map<java.lang.String,​?> map)
        Instantiate a new JsonObject by accepting a map's entries, which could lead to de/serialization issues of the resulting JsonObject since the entry values aren't validated as JSON values.
        Parameters:
        map - represents the mappings to produce the JsonObject with.
    • Method Detail

      • getBigDecimal

        public java.math.BigDecimal getBigDecimal​(JsonKey key)
        A convenience method that assumes there is a BigDecimal, Number, or String at the given key. If a Number is there its Number#toString() is used to construct a new BigDecimal(String). If a String is there it is used to construct a new BigDecimal(String).
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a BigDecimal representing the value paired with the key.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        BigDecimal, Object.toString(), JsonKey
      • getBigDecimalOrDefault

        public java.math.BigDecimal getBigDecimalOrDefault​(JsonKey key)
        A convenience method that assumes there is a BigDecimal, Number, or String at the given key. If a Number is there its Number#toString() is used to construct a new BigDecimal(String). If a String is there it is used to construct a new BigDecimal(String).
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a BigDecimal representing the value paired with the key or JsonKey#getValue() if the key isn't present.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        BigDecimal, Object.toString(), JsonKey
      • getBoolean

        public java.lang.Boolean getBoolean​(JsonKey key)
        A convenience method that assumes there is a Boolean or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Boolean representing the value paired with the key.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getBooleanOrDefault

        public java.lang.Boolean getBooleanOrDefault​(JsonKey key)
        A convenience method that assumes there is a Boolean or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Boolean representing the value paired with the key or JsonKey#getValue() if the key isn't present.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getByte

        public java.lang.Byte getByte​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Byte representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.byteValue(), JsonKey
      • getByteOrDefault

        public java.lang.Byte getByteOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Byte representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.byteValue(), JsonKey
      • getCollection

        public <T extends java.util.Collection<?>> T getCollection​(JsonKey key)
        A convenience method that assumes there is a Collection at the given key.
        Type Parameters:
        T - the kind of collection to expect at the key. Note unless manually added, collection values will be a JsonArray.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Collection representing the value paired with the key.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getCollectionOrDefault

        public <T extends java.util.Collection<?>> T getCollectionOrDefault​(JsonKey key)
        A convenience method that assumes there is a Collection at the given key.
        Type Parameters:
        T - the kind of collection to expect at the key. Note unless manually added, collection values will be a JsonArray.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Collection representing the value paired with the key or JsonKey#getValue() if the key isn't present..
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getDouble

        public java.lang.Double getDouble​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Double representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.doubleValue(), JsonKey
      • getDoubleOrDefault

        public java.lang.Double getDoubleOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Double representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.doubleValue(), JsonKey
      • getFloat

        public java.lang.Float getFloat​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Float representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.floatValue(), JsonKey
      • getFloatOrDefault

        public java.lang.Float getFloatOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Float representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.floatValue(), JsonKey
      • getInteger

        public java.lang.Integer getInteger​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        an Integer representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.intValue(), JsonKey
      • getIntegerOrDefault

        public java.lang.Integer getIntegerOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        an Integer representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.intValue(), JsonKey
      • getLong

        public java.lang.Long getLong​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Long representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.longValue(), JsonKey
      • getLongOrDefault

        public java.lang.Long getLongOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Long representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.longValue(), JsonKey
      • getMap

        public <T extends java.util.Map<?,​?>> T getMap​(JsonKey key)
        A convenience method that assumes there is a Map at the given key.
        Type Parameters:
        T - the kind of map to expect at the key. Note unless manually added, Map values will be a JsonObject.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Map representing the value paired with the key.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getMapOrDefault

        public <T extends java.util.Map<?,​?>> T getMapOrDefault​(JsonKey key)
        A convenience method that assumes there is a Map at the given key.
        Type Parameters:
        T - the kind of map to expect at the key. Note unless manually added, Map values will be a JsonObject.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Map representing the value paired with the key or JsonKey#getValue() if the key isn't present.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getShort

        public java.lang.Short getShort​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Short representing the value paired with the key (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.shortValue(), JsonKey
      • getShortOrDefault

        public java.lang.Short getShortOrDefault​(JsonKey key)
        A convenience method that assumes there is a Number or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a Short representing the value paired with the key or JsonKey#getValue() if the key isn't present (which may involve rounding or truncation).
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        java.lang.NumberFormatException - if a String isn't a valid representation of a BigDecimal or if the Number represents the double or float Infinity or NaN.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        Number.shortValue(), JsonKey
      • getString

        public java.lang.String getString​(JsonKey key)
        A convenience method that assumes there is a Boolean, Number, or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a String representing the value paired with the key.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • getStringOrDefault

        public java.lang.String getStringOrDefault​(JsonKey key)
        A convenience method that assumes there is a Boolean, Number, or String value at the given key.
        Parameters:
        key - representing where the value ought to be paired with.
        Returns:
        a String representing the value paired with the key or JsonKey#getValue() if the key isn't present.
        Throws:
        java.lang.ClassCastException - if the value didn't match the assumed return type.
        Since:
        2.3.0 to utilize JsonKey
        See Also:
        JsonKey
      • put

        public void put​(JsonKey key,
                        java.lang.Object value)
        Convenience method that calls put for the given key and value.
        Parameters:
        key - represents the JsonKey used for the value's association in the map.
        value - represents the key's association in the map.
        Since:
        3.1.1 to use JsonKey instead of calling JsonKey#getKey() each time.
        See Also:
        Map.put(Object, Object)
      • putAllChain

        public JsonObject putAllChain​(java.util.Map<java.lang.String,​java.lang.Object> map)
        Calls putAll for the given map, but returns the JsonObject for chaining calls.
        Parameters:
        map - represents the map to be copied into the JsonObject.
        Returns:
        the JsonObject to allow chaining calls.
        Since:
        3.1.0 for inline instantiation.
        See Also:
        Map.putAll(Map)
      • putChain

        public JsonObject putChain​(JsonKey key,
                                   java.lang.Object value)
        Convenience method that calls put for the given key and value, but returns the JsonObject for chaining calls.
        Parameters:
        key - represents the JsonKey used for the value's association in the map.
        value - represents the key's association in the map.
        Returns:
        the JsonObject to allow chaining calls.
        Since:
        3.1.1 to use JsonKey instead of calling JsonKey#getKey() each time.
        See Also:
        Map.put(Object, Object)
      • putChain

        public JsonObject putChain​(java.lang.String key,
                                   java.lang.Object value)
        Calls put for the given key and value, but returns the JsonObject for chaining calls.
        Parameters:
        key - represents the value's association in the map.
        value - represents the key's association in the map.
        Returns:
        the JsonObject to allow chaining calls.
        Since:
        3.1.0 for inline instantiation.
        See Also:
        Map.put(Object, Object)
      • remove

        public java.lang.Object remove​(JsonKey key)
        Convenience method that calls remove for the given key.
        Parameters:
        key - represents the value's association in the map.
        Returns:
        an object representing the removed value or null if there wasn't one.
        Since:
        3.1.1 to use JsonKey instead of calling JsonKey#getKey() each time.
        See Also:
        Map.remove(Object)
      • remove

        public boolean remove​(JsonKey key,
                              java.lang.Object value)
        Convenience method that calls remove for the given key and value.
        Parameters:
        key - represents the value's association in the map.
        value - represents the expected value at the given key.
        Returns:
        a boolean, which is true if the value was removed. It is false otherwise.
        Since:
        3.1.1 to use JsonKey instead of calling JsonKey#getKey() each time.
        See Also:
        Map.remove(Object, Object)
      • requireKeys

        public void requireKeys​(JsonKey... keys)
        Ensures the given keys are present.
        Parameters:
        keys - represents the keys that must be present.
        Throws:
        java.util.NoSuchElementException - if any of the given keys are missing.
        Since:
        2.3.0 to ensure critical keys are in the JsonObject.
      • toJson

        public java.lang.String toJson()
        Description copied from interface: Jsonable
        Serialize to a JSON formatted string.
        Specified by:
        toJson in interface Jsonable
        Returns:
        a string, formatted in JSON, that represents the Jsonable.
      • toJson

        public void toJson​(java.io.Writer writable)
                    throws java.io.IOException
        Description copied from interface: Jsonable
        Serialize to a JSON formatted stream.
        Specified by:
        toJson in interface Jsonable
        Parameters:
        writable - where the resulting JSON text should be sent.
        Throws:
        java.io.IOException - when the writable encounters an I/O error.