Interface JSONObject

All Superinterfaces:
Formattable, Iterable<JSONValue>, JSONValue
All Known Implementing Classes:
JSONObjectImpl
@ClassVersion(sourceVersion="$Id: JSONObject.java 1258 2026-06-04 18:33:06Z tquadrat $") @API(status=STABLE, since="0.25.0") public sealed interface JSONObject extends Iterable<JSONValue>, JSONValue permits JSONObjectImpl

The definition of a JSON object.

Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: JSONObject.java 1258 2026-06-04 18:33:06Z tquadrat $
Since:
0.25.0
UML Diagram
UML Diagram for "org.tquadrat.foundation.jsonbuilder.JSONObject"⁠

UML Diagram for "org.tquadrat.foundation.jsonbuilder.JSONObject"

UML Diagram for "org.tquadrat.foundation.jsonbuilder.JSONObject"⁠

  • Method Details

    • contains

      boolean contains(String name)

      Checks if a specified member is present as a child of this object. This will not test if that child is the JSON literal null, This needs to be tested separately.

      Parameters:
      name - The name of the member to check for.
      Returns:
      true if there is a member with the given name, false if not.

    • get

      Optional<JSONValue> get(String name)

      Returns the value of the member with the specified name in this object.

      Parameters:
      name - The name of the member whose value is to be returned.
      Returns:
      An instance of Optional that holds the value.

    • getArray

      default JSONArray getArray(String name, JSONArray defaultValue) throws IllegalStateException

      Convenience method that returns the value with the specified name as a JSONArray.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a JSON Array.

    • getBigDecimal

      default BigDecimal getBigDecimal(String name, BigDecimal defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a BigDecimal.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid BigDecimal.

    • getBigInteger

      default BigInteger getBigInteger(String name, BigInteger defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a BigInteger.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid BigInteger.

    • getBoolean

      default boolean getBoolean(String name, boolean defaultValue) throws IllegalStateException

      Convenience method that returns the value with the specified name as a boolean.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a boolean.

    • getDouble

      default double getDouble(String name, double defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a double.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid double.

    • getFloat

      default float getFloat(String name, float defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a float.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid float.

    • getInt

      default int getInt(String name, int defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a int.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid int.

    • getLong

      default long getLong(String name, long defaultValue) throws IllegalStateException, NumberFormatException

      Convenience method that returns the value with the specified name as a long.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a number.
      NumberFormatException - The member exists, and it is a number, but cannot be parsed to a valid long.

    • getObject

      default JSONObject getObject(String name, JSONObject defaultValue) throws IllegalStateException

      Convenience method that returns the value with the specified name as a JSONObject.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a JSON Object.

    • getString

      default String getString(String name, String defaultValue) throws IllegalStateException

      Convenience method that returns the value with the specified name as a String.

      Parameters:
      name - The name of the member whose value is to be returned.
      defaultValue - The value to be returned if the requested member is missing; can be null.
      Returns:
      The value of the member with the specified name, or the given default value if this object does not contain a member with that name.
      Throws:
      IllegalStateException - The member exists, but it is not a String.

    • isEmpty

      boolean isEmpty()
      Checks whether this object has members.
      Returns:
      true if the object does not have any members, false otherwise.

    • merge

      JSONObject merge(JSONObject object)

      Copies all members of the specified object into this object. When the specified object contains members with names that also exist in this object, the existing values in this object will be replaced by the corresponding values in the specified object.

      Parameters:
      object - The object to merge.
      Returns:
      This object itself, to enable method chaining.

    • names

      SequencedCollection<String> names()

      Returns the names of the members of this object in document order.

      The return value is backed by this object and will reflect subsequent changes. It cannot be used to modify this object. Attempts to modify the returned data structure will result in an exception.

      Returns:
      The names.

    • remove

      JSONObject remove(String name)

      Removes a member with the specified name from this object. If this object does not contain a member with the specified name, the object is not modified.

      Parameters:
      name - The name of the member to remove.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, BigDecimal value)

      Sets the value of the member with the specified name to the JSON representation of the specified BigDecimal value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, BigInteger value)

      Sets the value of the member with the specified name to the JSON representation of the specified BigInteger value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      default JSONObject set(String name, boolean value)

      Sets the value of the member with the specified name to the JSON representation of the specified boolean value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      <T extends Dimension> JSONObject set(String name, DimensionedValue<T> value, T targetUnit)

      Sets the value of the member with the specified name to the JSON representation of the specified DimensionedValue value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Type Parameters:
      T - The type of the dimension for the value.
      Parameters:
      name - The name of the member to replace or to add.
      value - The value.
      targetUnit - The dimension for the output.
      Returns:
      This object itself, to enable method chaining.
      See Also:

    • set

      JSONObject set(String name, double value)

      Sets the value of the member with the specified name to the JSON representation of the specified double value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, Double value)

      Sets the value of the member with the specified name to the JSON representation of the specified Double value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, float value)

      Sets the value of the member with the specified name to the JSON representation of the specified float value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, Float value)

      Sets the value of the member with the specified name to the JSON representation of the specified Float value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, int value)

      Sets the value of the member with the specified name to the JSON representation of the specified int value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, Integer value)

      Sets the value of the member with the specified name to the JSON representation of the specified Integer value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, JSONValue value)

      Sets the value of the member with the specified name to the specified JSONValue value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, long value)

      Sets the value of the member with the specified name to the JSON representation of the specified long value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, Long value)

      Sets the value of the member with the specified name to the JSON representation of the specified Long value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • set

      JSONObject set(String name, String value)

      Sets the value of the member with the specified name to the JSON representation of the specified String value.

      If this object does not contain a member with this name, a new member is added at the end of the object.

      Parameters:
      name - The name of the member to replace or to add.
      value - The value to set to the member.
      Returns:
      This object itself, to enable method chaining.

    • setArray

      JSONArray setArray(String name)

      Sets a new empty instance of JSONArray to this object and returns that.

      Parameters:
      name - The name of the member.
      Returns:
      The freshly created JSONArray.

    • setObject

      JSONObject setObject(String name)

      Sets a new empty instance of JSONObject to this object and returns that.

      Parameters:
      name - The name of the member.
      Returns:
      The freshly created JSONObject.

    • size

      int size()

      Returns the number of members (name/value pairs) in this object.

      Returns:
      The number of members in this object.