Package com.invirgance.convirgance.json

Class JSONObject

java.lang.Object
com.invirgance.convirgance.json.JSONObject
All Implemented Interfaces:
Map<String,Object>
public class JSONObject extends Object implements Map<String,Object>
A JSON object implementation that represents a collection of key-value pairs. Provides methods for parsing, manipulating, and serializing JSON data while maintaining optional key ordering.
Author:
jbanes

  • Constructor Details

    • JSONObject

      public JSONObject()
      Creates a new JSONObject with ordering set to false.

    • JSONObject

      public JSONObject(boolean ordered)
      Creates a JSONObject and sets its ordering.
      Parameters:
      ordered - The ordering state to set.

    • JSONObject

      public JSONObject(String json)
      Creates a JSONObject by parsing the provided JSON string. Initializes the internal map, ordering state, and ordered keys collection from the parsed content.
      Parameters:
      json - The JSON string to parse.
      Throws:
      ConvirganceException - if an error occurs during JSON parsing.

    • JSONObject

      public JSONObject(Map<String,Object> map)
      Creates a JSONObject based on the provided map parameter. If the map is an instance of JSONObject and is ordered, this JSONObject will inherit the ordering and its ordered keys.
      Parameters:
      map - A map of key-value pairs.

  • Method Details

    • isOrdered

      public boolean isOrdered()
      Returns if ordering is maintained on the insert of keys
      Returns:
      true (ordered) or false (unordered).

    • setOrdered

      public void setOrdered(boolean ordered)
      Controls whether this object's map maintains key order
      Parameters:
      ordered - true to enable key ordering, false to disable it.

    • size

      public int size()
      Returns the number of entries in this Map
      Specified by:
      size in interface Map<String,Object>
      Returns:
      the count of entries

    • isEmpty

      public boolean isEmpty()
      Returns true if this Map is empty
      Specified by:
      isEmpty in interface Map<String,Object>
      Returns:
      true if empty, otherwise false.

    • isNull

      public boolean isNull(String key)
      Checks if a key's value is null including if the key is not present
      Parameters:
      key - the key to check
      Returns:
      true if the key is not present or the key's value is null

    • containsKey

      public boolean containsKey(Object key)
      Used to check if the JSONObject contains a key
      Specified by:
      containsKey in interface Map<String,Object>
      Parameters:
      key - the key to check
      Returns:
      true if the key is present

    • containsValue

      public boolean containsValue(Object value)
      Used to check if the JSONObject contains a given value.
      Specified by:
      containsValue in interface Map<String,Object>
      Parameters:
      value - the value to look for
      Returns:
      true if the value is present

    • get

      public Object get(Object key)
      Gets the value for the provided key
      Specified by:
      get in interface Map<String,Object>
      Parameters:
      key - the key to look up
      Returns:
      the key's value or null if not present

    • getBoolean

      public boolean getBoolean(String key) throws ConvirganceException
      Attempts to coerce the key's value to a Boolean. If the key's value is of type Boolean its value will be returned. For String values, uses Boolean.parseBoolean() which: - Returns true only if the string equals "true" (case-insensitive) - Returns false for all other string values including "false", "yes", "no", "1", "0"
      Parameters:
      key - A key.
      Returns:
      The value parsed to a Boolean.
      Throws:
      ConvirganceException - When the key doesn't exist or key's value is not of type Boolean, String or is null.

    • getBoolean

      public boolean getBoolean(String key, boolean defaultValue) throws ConvirganceException
      Gets the Boolean equivalent of value for the given key with a given default alternative. Returns true if the value is already a Boolean. Otherwise if the value is a String, Boolean.parseBoolean() is used (case-insensitive) If the value is null or the given key doesn't exist the default value is returned.
      Parameters:
      key - The Key to check.
      defaultValue - A Boolean to return if the keys value is null.
      Returns:
      The key's value parsed with Boolean.parseBoolean(). Otherwise if the key's value is null defaultValue will be returned.
      Throws:
      ConvirganceException - When the key's value is not of type null, Boolean or String.

    • getDouble

      public double getDouble(String key) throws ConvirganceException
      Gets the value associated with the specified key as a Double. If the key's value is a Double its returned. If the key's value is a String we pass the toString() of value to Double.parseDouble()
      Parameters:
      key - The key whose associated value is to be retrieved.
      Returns:
      The key's value or a String coerced into a Double.
      Throws:
      ConvirganceException - When the key or key's value is null, or its type cannot be coerced to a Double.

    • getDouble

      public double getDouble(String key, double defaultValue) throws ConvirganceException
      Gets the value associated with the specified key as a Double returning the provided default if the value or key is null. If the key's value is a Double its returned. If the key's value is a String we pass the toString() of value to Double.parseDouble() Otherwise if the key or key's value was null, defaultValue is returned.
      Parameters:
      key - The key whose associated value is to be retrieved.
      defaultValue - The default Double value to return if the key's value is null.
      Returns:
      The key's value parsed to Double, or defaultValue if value or key is null.
      Throws:
      ConvirganceException - When the key's value cannot be converted to a Double.

    • getInt

      public int getInt(String key) throws ConvirganceException
      Gets the value associated with the specified key as a Int. Returns value if its already an Int. Otherwise we use Integer.parseInt() and the toString() of value.
      Parameters:
      key - The key whose associated value is to be retrieved.
      Returns:
      The key's value parsed to Int.
      Throws:
      ConvirganceException - When the key's value cannot be converted to a Int. Or the key itself is null.

    • getInt

      public int getInt(String key, int defaultValue) throws ConvirganceException
      Gets the value associated with the specified key as a Int returning the provided default if the value is null. If value is null or the key doesn't exist defaultValue is returned. Otherwise if value is of type Int, it will be returned unchanged.
      Parameters:
      key - The key whose associated value is to be retrieved.
      defaultValue - The default Int value to return if the key's value is null.
      Returns:
      The key's value parsed to Int, or defaultValue when value is null.
      Throws:
      ConvirganceException - When the key's value cannot be converted to a Int.

    • getLong

      public long getLong(String key) throws ConvirganceException
      Gets the value associated with the specified key as a Long. Returns value if its already an Long. Otherwise we use Long.parseLong() and the toString() of value.
      Parameters:
      key - The key whose associated value is to be retrieved.
      Returns:
      The key's value parsed to Long.
      Throws:
      ConvirganceException - When the key's value cannot be converted to a Long. Or the key itself is null.

    • getLong

      public long getLong(String key, long defaultValue) throws ConvirganceException
      Gets the value associated with the specified key as a Long returning the provided default if the value is null. If value is null or the key doesn't exist defaultValue is returned. Otherwise if value is of type Long, it will be returned unchanged.
      Parameters:
      key - The key whose associated value is to be retrieved.
      defaultValue - The default Long value to return if the key's value is null.
      Returns:
      The key's value parsed to Long, or defaultValue when value is null.
      Throws:
      ConvirganceException - When the key's value cannot be converted to a Long.

    • getJSONArray

      public JSONArray getJSONArray(String key) throws ConvirganceException
      Gets a key's value returning a JSONArray, returning null on a null key value.
      Parameters:
      key - A key whose value is JSON.
      Returns:
      Value converted to JSONArray or null.
      Throws:
      ConvirganceException - When the value is not of type JSONArray.

    • getJSONArray

      public JSONArray getJSONArray(String key, JSONArray defaultValue) throws ConvirganceException
      Gets a key's value returning a JSONArray, returning null on a null key value.
      Parameters:
      key - A key whose value is JSON.
      defaultValue - A JSONArray to return when value is null.
      Returns:
      Value converted to JSONArray or null.
      Throws:
      ConvirganceException - When the value is not of type JSONArray or is not null.

    • getJSONObject

      public JSONObject getJSONObject(String key) throws ConvirganceException
      Gets the value for a key. Returning null or the value as a JSONObject.
      Parameters:
      key - The key.
      Returns:
      The key's value as a JSONObject or null.
      Throws:
      ConvirganceException - When the key's value is not of type JSONObject.

    • getJSONObject

      public JSONObject getJSONObject(String key, JSONObject defaultValue) throws ConvirganceException
      Gets the value for a key. Returning the provided default if the key's value is null. Otherwise the key's value as a JSONObject.
      Parameters:
      key - The key.
      defaultValue - The default to use when the key's value is null.
      Returns:
      The key's value as a JSONObject, or the provided default.
      Throws:
      ConvirganceException - When the key's value is not of type JSONObject and is not null.

    • getString

      public String getString(String key)
      Gets the keys value and returns its string representation. Returns null if the key's value is null.
      Parameters:
      key - The key.
      Returns:
      A string representation of the key's value or null.

    • getString

      public String getString(String key, String defaultValue)
      Gets the key's value and returns its string representation. Otherwise returns the provided default value if the key doesn't exist or the key's value is null.
      Parameters:
      key - The key.
      defaultValue - The value to return if the key is missing or the key's value is null.
      Returns:
      A string representation of the key's value or the provided defaultValue.

    • put

      public Object put(String key, Object value)
      Adds or updates a key value pair for the JSONObject.
      Specified by:
      put in interface Map<String,Object>
      Parameters:
      key - The key.
      value - The value.
      Returns:
      The replaced value or null.

    • remove

      public Object remove(Object key)
      Removes a key value pair from the JSONObject.
      Specified by:
      remove in interface Map<String,Object>
      Parameters:
      key - The key to remove.
      Returns:
      The removed value, or null.

    • putAll

      public void putAll(Map<? extends String,? extends Object> map)
      Adds all the provided key value pairs to the JSONObject.
      Specified by:
      putAll in interface Map<String,Object>
      Parameters:
      map - A map consisting of keys and values.

    • clear

      public void clear()
      Clears the keys value pairs.
      Specified by:
      clear in interface Map<String,Object>

    • keySet

      public Set<String> keySet()
      Returns a set of the keys.
      Specified by:
      keySet in interface Map<String,Object>
      Returns:
      A set view of the keys.

    • values

      public Collection<Object> values()
      Returns all the values contained by the JSONObject.
      Specified by:
      values in interface Map<String,Object>
      Returns:
      All of the values.

    • entrySet

      public Set<Map.Entry<String,Object>> entrySet()
      Specified by:
      entrySet in interface Map<String,Object>

    • toString

      public String toString()
      Returns the string representation of the JSONObject in JSON notation
      Overrides:
      toString in class Object
      Returns:
      a JSON string
      Throws:
      ConvirganceException - if an error occurs while serializing the object to JSON

    • toString

      public String toString(int indent)
      Converts this JSONObject to a formatted JSON string with specified indentation
      Parameters:
      indent - the number of spaces to use for each level of indentation
      Returns:
      a formatted JSON string representation of this object
      Throws:
      ConvirganceException - if an error occurs while serializing the object to JSON

    • equals

      public boolean equals(Object obj)
      Returns true if obj is also a JSONObject and contains the same list of key/value pairs. Key ordering is not taken into account.
      Specified by:
      equals in interface Map<String,Object>
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare to
      Returns:
      true if the passed in object is equal to this object

    • hashCode

      public int hashCode()
      Creates stable hash code based on the key/value pairs in this object
      Specified by:
      hashCode in interface Map<String,Object>
      Overrides:
      hashCode in class Object
      Returns:
      a hashed representation of this object