Package com.blackrook.json

Class JSONObject

java.lang.Object
com.blackrook.json.JSONObject
public class JSONObject extends Object
JSON Object abstraction.
Author:
Matthew Tropiano

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    JSONObject.Type
    JavaScript type of a JSONObject.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final JSONObject
    NULL
    Null member.
    static final JSONObject
    UNDEFINED
    Undefined member.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAt(int index, JSONObject object)
    Adds a member to a specific index in this JSONObject, shifting the contents, but only if this is an array.
    void
    addMember(String name, JSONConverterSet converterSet, Object object)
    Adds a member to this JSONObject, if this is an Object type.
    void
    addMember(String name, JSONObject object)
    Adds a member to this JSONObject, if this is an Object type.
    void
    addMember(String name, Object object)
    Adds a member to this JSONObject, if this is an Object type.
    void
    append(JSONObject object)
    Appends a member to the end of this JSONObject, but only if this is an array.
    <T> T
    applyToObject(T object)
    Applies this object to an object bean / plain ol' Java object, or Array.
    <T> T
    applyToObject(T object, JSONConverterSet converterSet)
    Applies this object to an object bean / plain ol' Java object, or Array.
    static <T> JSONObject
    create(T object)
    Creates a new JSON object using the default converter set.
    static <T> JSONObject
    create(T object, JSONConverterSet converterSet)
    Creates a new JSON object using an associated specific converter set.
    static JSONObject
    createEmptyArray()
    Creates a JSONObject that represents an empty array type.
    static JSONObject
    createEmptyObject()
    Creates a JSONObject that represents an empty object type.
    JSONObject
    get(int index)
    Gets an object member of this JSONObject by index, if this is an array.
    JSONObject
    get(String memberName)
    Gets an object member of this JSONObject by name.
    boolean
    getBoolean()
    Returns the value of this JSON Object as an boolean.
    byte
    getByte()
    Returns the value of this JSON Object as a byte.
    static <E> JSONConverter<E>
    getConverter(Class<E> clazz)
    Gets a converter for a type for the default converter set.
    double
    getDouble()
    Returns the value of this JSON Object as a double.
    float
    getFloat()
    Returns the value of this JSON Object as a float.
    int
    getInt()
    Returns the value of this JSON Object as an integer.
    protected List<JSONObject>
    getList()
    Returns the underlying value as a list of objects.
    long
    getLong()
    Returns the value of this JSON Object as a long.
    protected Map<String,JSONObject>
    getMap()
    Returns the underlying value as a map of string to object.
    int
    getMemberCount()
    Gets the amount of members in this object, if this is an object.
    String[]
    getMemberNames()
    Returns an array of member names on this object, if it is Object typed.
    short
    getShort()
    Returns the value of this JSON Object as a short.
    String
    getString()
    Returns the value of this JSON Object as a String.
    JSONObject.Type
    getType()
    Gets this object's JavaScript type.
    Object
    getValue()
    Gets this object's encapsulated value.
    boolean
    hasMember(String memberName)
    Returns true if this is an object AND contains a member of a particular name.
    boolean
    isArray()
    Checks if this is Object-typed and is an array.
    boolean
    isNull()
    Checks if this is a null object.
    boolean
    isObject()
    Checks if this is Object-typed.
    boolean
    isUndefined()
    Checks if this is UNDEFINED.
    int
    length()
    Gets length of this array-typed object.
    <T> T
    newObject(Class<T> clazz)
    Creates a new instance of a class, populated with values from this object.
    <T> T
    newObject(Class<T> clazz, JSONConverterSet converterSet)
    Creates a new instance of a class, populated with values from this object.
    JSONObject
    pop()
    Removes a member from the beginning index of this JSONObject, shifting the contents, but only if this is an array.
    void
    push(JSONObject object)
    Adds a member to the beginning of this JSONObject, shifting the contents, but only if this is an array.
    JSONObject
    removeAt(int index)
    Removes a member from a specific index in this JSONObject, shifting the contents, but only if this is an array.
    boolean
    removeMember(String name)
    Removes a member from this JSONObject, if this is an Object type.
    static <E> void
    setConverter(Class<E> clazz, JSONConverter<E> converter)
    Sets a converter for a type.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • UNDEFINED

      public static final JSONObject UNDEFINED
      Undefined member. All instances of UNDEFINED are this one.

    • NULL

      public static final JSONObject NULL
      Null member. All instances of NULL are this one.

  • Method Details

    • getConverter

      public static <E> JSONConverter<E> getConverter(Class<E> clazz)
      Gets a converter for a type for the default converter set. Since 1.3.0, It is, however, preferred to use a JSONConverterSet for specifying how JSON objects get converted.
      Type Parameters:
      E - the class type.
      Parameters:
      clazz - the class to get the converter for.
      Returns:
      a converter to use for JSON conversion.
      See Also:

    • setConverter

      public static <E> void setConverter(Class<E> clazz, JSONConverter<E> converter)
      Sets a converter for a type. Since 1.3.0, It is, however, preferred to use a JSONConverterSet for specifying how JSON objects get converted.
      Type Parameters:
      E - the class type.
      Parameters:
      clazz - the class to get the converter for.
      converter - the converter to use for JSON conversion.
      See Also:

    • create

      public static <T> JSONObject create(T object)
      Creates a new JSON object using the default converter set. Since 1.3.0, It is, however, preferred to use a JSONConverterSet for specifying how JSON objects get converted.
      Type Parameters:
      T - the object type used for finding a converter.
      Parameters:
      object - the object to encapsulate.
      Returns:
      the JSONObject representing the input object.
      See Also:

    • create

      public static <T> JSONObject create(T object, JSONConverterSet converterSet)
      Creates a new JSON object using an associated specific converter set. Objects may have an internal converter.
      Type Parameters:
      T - the object type used for finding a converter.
      Parameters:
      object - the object to encapsulate.
      converterSet - the converter set to use for creating JSONObjects from Java objects.
      Returns:
      the JSONObject representing the input object.
      Since:
      1.3.0

    • createEmptyObject

      public static JSONObject createEmptyObject()
      Creates a JSONObject that represents an empty object type.
      Returns:
      a JSONObject representing a blank object.

    • createEmptyArray

      public static JSONObject createEmptyArray()
      Creates a JSONObject that represents an empty array type.
      Returns:
      a JSONObject representing an empty array.

    • getType

      public JSONObject.Type getType()
      Gets this object's JavaScript type.
      Returns:
      the object type.

    • isObject

      public boolean isObject()
      Checks if this is Object-typed.
      Returns:
      true if so, false if not.

    • isArray

      public boolean isArray()
      Checks if this is Object-typed and is an array.
      Returns:
      true if so, false if not.

    • length

      public int length()
      Gets length of this array-typed object.
      Returns:
      the length of this array if this is an array, or -1 if not an array.

    • getMemberCount

      public int getMemberCount()
      Gets the amount of members in this object, if this is an object. If this is an array, this returns its length.
      Returns:
      the member count, or 0 if not an object.
      See Also:

    • getMap

      protected Map<String,JSONObject> getMap()
      Returns the underlying value as a map of string to object.
      Returns:
      the map.

    • getList

      protected List<JSONObject> getList()
      Returns the underlying value as a list of objects.
      Returns:
      the list.

    • getMemberNames

      public String[] getMemberNames()
      Returns an array of member names on this object, if it is Object typed. This may return an array of index numbers, if this is an array under the covers.
      Returns:
      an array of member names, suitable for use with get(String), or an empty array, if this does not represent an object.

    • isNull

      public boolean isNull()
      Checks if this is a null object.
      Returns:
      true if so, false if not.

    • isUndefined

      public boolean isUndefined()
      Checks if this is UNDEFINED.
      Returns:
      true if so, false if not.

    • getValue

      public Object getValue()
      Gets this object's encapsulated value. Can be null.
      Returns:
      the underlying value.

    • hasMember

      public boolean hasMember(String memberName)
      Returns true if this is an object AND contains a member of a particular name.
      Parameters:
      memberName - the name of the member to check.
      Returns:
      true if it exists on the object, false if not or not an object.

    • get

      public JSONObject get(String memberName)
      Gets an object member of this JSONObject by name. NOTE: Arrays are objects - their member names are the index position.
      Parameters:
      memberName - the name of the member to retrieve.
      Returns:
      a JSONObject corresponding to this member, or UNDEFINED if no member by that name or this isn't a JSON Object.

    • get

      public JSONObject get(int index)
      Gets an object member of this JSONObject by index, if this is an array.
      Parameters:
      index - the index to retrieve.
      Returns:
      a JSONObject corresponding to this index, or UNDEFINED if no such index or this isn't a JSON Object or the index is out of bounds.

    • getByte

      public byte getByte()
      Returns the value of this JSON Object as a byte.
      Returns:
      the byte value, or 0 if this cannot be reasonably converted to a byte.

    • getShort

      public short getShort()
      Returns the value of this JSON Object as a short.
      Returns:
      the short value, or 0 if this cannot be reasonably converted to a short.

    • getInt

      public int getInt()
      Returns the value of this JSON Object as an integer.
      Returns:
      the integer value, or 0 if this cannot be reasonably converted to an integer.

    • getFloat

      public float getFloat()
      Returns the value of this JSON Object as a float.
      Returns:
      the float value, or 0f if this cannot be reasonably converted to a float.

    • getLong

      public long getLong()
      Returns the value of this JSON Object as a long.
      Returns:
      the long value, or 0L if this cannot be reasonably converted to a long.

    • getDouble

      public double getDouble()
      Returns the value of this JSON Object as a double.
      Returns:
      the double value, or 0.0 if this cannot be reasonably converted to a long.

    • getBoolean

      public boolean getBoolean()
      Returns the value of this JSON Object as an boolean. Non-null Objects are always true, undefined is always false.
      Returns:
      the boolean value, or false if this cannot be reasonably converted to a boolean.

    • getString

      public String getString()
      Returns the value of this JSON Object as a String. If the value of this object is undefined or null, null is returned. If this is an object, Object is returned.
      Returns:
      the string value, or false if this cannot be reasonably converted to a boolean.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • removeMember

      public boolean removeMember(String name)
      Removes a member from this JSONObject, if this is an Object type. If this is not an object (or array), this causes an error. WARNING: Array types are promoted to objects whether or not this succeeds.
      Parameters:
      name - the name of the member to remove.
      Returns:
      true if the member was removed, false if not.
      Throws:
      IllegalStateException - if this JSONObject is not an Object type (isObject() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).

    • addMember

      public void addMember(String name, JSONObject object)
      Adds a member to this JSONObject, if this is an Object type. If this is not an object, this causes an error. If this is an array type, it is promoted to an object.
      Parameters:
      name - the member name. whitespace is trimmed from this.
      object - the object value of the member.
      Throws:
      IllegalArgumentException - if name is an empty string or just whitespace.
      IllegalStateException - if this JSONObject is not an Object type (isObject() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).

    • addMember

      public void addMember(String name, Object object)
      Adds a member to this JSONObject, if this is an Object type. If this is not an object, this causes an error. If this is an array type, it is promoted to an object. Since 1.3.0, it is preferred to use a JSONConverterSet for specifying how JSON objects get converted.
      Parameters:
      name - the member name. whitespace is trimmed from this.
      object - the object value of the member.
      Throws:
      IllegalArgumentException - if name is an empty string or just whitespace.
      IllegalStateException - if this JSONObject is not an Object type (isObject() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).

    • addMember

      public void addMember(String name, JSONConverterSet converterSet, Object object)
      Adds a member to this JSONObject, if this is an Object type. If this is not an object, this causes an error. If this is an array type, it is promoted to an object.
      Parameters:
      name - the member name. whitespace is trimmed from this.
      converterSet - the converter set to use for creating JSONObjects from Java objects.
      object - the object value of the member.
      Throws:
      IllegalArgumentException - if name is an empty string or just whitespace.
      IllegalStateException - if this JSONObject is not an Object type (isObject() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).
      Since:
      1.3.0

    • append

      public void append(JSONObject object)
      Appends a member to the end of this JSONObject, but only if this is an array.
      Parameters:
      object - the object to add.
      Throws:
      IllegalStateException - if this JSONObject is not an Array type (isArray() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).
      See Also:

    • removeAt

      public JSONObject removeAt(int index)
      Removes a member from a specific index in this JSONObject, shifting the contents, but only if this is an array.
      Parameters:
      index - the index to remove.
      Returns:
      the JSONObject at that index or null if no object at that index.
      Throws:
      IllegalStateException - if this JSONObject is not an Array type (isArray() is false) or is null (isNull() is true) or is UNDEFINED (isUndefined() is true).
      See Also:

    • pop

      public JSONObject pop()
      Removes a member from the beginning index of this JSONObject, shifting the contents, but only if this is an array.
      Returns:
      the JSONObject at index 0 or null if this is empty.
      Throws:
      IllegalStateException - if this JSONObject is not an array type.
      See Also:

    • addAt

      public void addAt(int index, JSONObject object)
      Adds a member to a specific index in this JSONObject, shifting the contents, but only if this is an array.
      Parameters:
      index - the index into the array.
      object - the object to add.
      Throws:
      IllegalStateException - if this JSONObject is not an array type.
      See Also:

    • push

      public void push(JSONObject object)
      Adds a member to the beginning of this JSONObject, shifting the contents, but only if this is an array.
      Parameters:
      object - the object to add.
      Throws:
      IllegalStateException - if this JSONObject is not an array type.
      See Also:

    • newObject

      public <T> T newObject(Class<T> clazz)
      Creates a new instance of a class, populated with values from this object. Since 1.3.0, it is preferred to use a JSONConverterSet for specifying how JSON objects get converted.

      This JSON object is applied via the target object's public fields and setter methods, if this is an object and the target class is not a primitive or autoboxed primitive.

      For instance, if there is a member on this object called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      If the input object is an array, then the contents of the indices are replaced, up to the length of the input array or this JSON array, whichever's shorter.

      Type Parameters:
      T - the return type.
      Parameters:
      clazz - the class to instantiate and apply.
      Returns:
      a new instance of this object, or null if this object's value is null (see isNull().
      Throws:
      RuntimeException - if the object cannot be created.
      JSONConversionException - if an error occurs during conversion/application.

    • newObject

      public <T> T newObject(Class<T> clazz, JSONConverterSet converterSet)
      Creates a new instance of a class, populated with values from this object.

      This JSON object is applied via the target object's public fields and setter methods, if this is an object and the target class is not a primitive or autoboxed primitive.

      For instance, if there is a member on this object called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      If the input object is an array, then the contents of the indices are replaced, up to the length of the input array or this JSON array, whichever's shorter.

      Type Parameters:
      T - the return type.
      Parameters:
      clazz - the class to instantiate and apply.
      converterSet - the converter set to use for certain specific object types.
      Returns:
      a new instance of this object, or null if this object's value is null (see isNull().
      Throws:
      RuntimeException - if the object cannot be created.
      JSONConversionException - if an error occurs during conversion/application.
      Since:
      1.3.0

    • applyToObject

      public <T> T applyToObject(T object)
      Applies this object to an object bean / plain ol' Java object, or Array. Since 1.3.0, it is preferred to use a JSONConverterSet for specifying how JSON objects get converted.

      This JSON object is applied via the target object's public fields and setter methods, if an object.

      For instance, if there is a member on this object called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      If the input object is an array, then the contents of the indices are replaced, up to the length of the input array or this JSON array, whichever's shorter.

      Type Parameters:
      T - the return type.
      Parameters:
      object - the object to set the fields/indices of.
      Returns:
      the input object.
      Throws:
      JSONConversionException - if an error occurs during conversion/application.

    • applyToObject

      public <T> T applyToObject(T object, JSONConverterSet converterSet)
      Applies this object to an object bean / plain ol' Java object, or Array.

      This JSON object is applied via the target object's public fields and setter methods, if an object.

      For instance, if there is a member on this object called "color", its value will be applied via the public field "color" or the setter "setColor()". Public fields take precedence over setters.

      If the input object is an array, then the contents of the indices are replaced, up to the length of the input array or this JSON array, whichever's shorter.

      Type Parameters:
      T - the return type.
      Parameters:
      object - the object to set the fields/indices of.
      converterSet - the converter set to use for certain specific object types.
      Returns:
      the input object.
      Throws:
      JSONConversionException - if an error occurs during conversion/application.
      Since:
      1.3.0