Package org.forgerock.json

Class JsonValue

java.lang.Object
org.forgerock.json.JsonValue
All Implemented Interfaces:
Cloneable, Iterable<JsonValue>
public class JsonValue extends Object implements Cloneable, Iterable<JsonValue>
Represents a value in a JSON object model structure. JSON values are represented with standard Java objects: String, Number, Map, List, Boolean and null.

  • Constructor Details

    • JsonValue

      public JsonValue(Object object)
      Constructs a JSON value object with a given object. This constructor will automatically unwrap JsonValue objects.
      Parameters:
      object - the Java object representing the JSON value.

    • JsonValue

      public JsonValue(Object object, JsonPointer pointer)
      Constructs a JSON value object with a given object and pointer. This constructor will automatically unwrap JsonValue objects.
      Parameters:
      object - the Java object representing the JSON value.
      pointer - the pointer to the value in a JSON structure.

  • Method Details

    • array

      public static List<Object> array(Object... objects)
      Returns a mutable JSON array containing the provided objects. This method is provided as a convenience method for constructing JSON arrays. Example usage: 
       JsonValue value = json(array(1, 2, 3));
      Parameters:
      objects - The array elements.
      Returns:
      A JSON array.

    • fieldIfNotNull

      public static Map.Entry<String,Object> fieldIfNotNull(String key, Object value)
      Returns a JSON field for inclusion in a JSON object using object only if its value is not null. Example usage: 
       JsonValue value = json(object(fieldIfNotNull("uid", getUid()));

      Note: This feature depends on the object(java.util.Map.Entry...) method that checks if the entry is not null before including it into the map.

      Parameters:
      key - The JSON field name.
      value - The JSON field value (may be null).
      Returns:
      The JSON field for inclusion in a JSON object or null.
      See Also:

    • field

      public static Map.Entry<String,Object> field(String key, Object value)
      Returns a JSON field for inclusion in a JSON object using object. This method is provided as a convenience method for constructing JSON objects. Example usage: 
       JsonValue value = json(object(field("uid", "bjensen"), field("age", 30)));
      Parameters:
      key - The JSON field name.
      value - The JSON field value.
      Returns:
      The JSON field for inclusion in a JSON object.

    • json

      public static JsonValue json(Object object)
      Returns a JSON value whose content is the provided object. This method is provided as a convenience method for constructing JSON objects, instead of using JsonValue(Object). Example usage: 
       JsonValue value =
         json(object(field("uid", "bjensen"),
                     field("roles", array("sales", "marketing"))));
      Parameters:
      object - the Java object representing the JSON value.
      Returns:
      The JSON value.

    • json

      public static JsonValue json(Object object, JsonPointer pointer)
      Returns a JSON value whose content is the provided object and whose pointer is the provided pointer. This method is provided as a convenience method for constructing JSON objects, instead of using JsonValue(Object, JsonPointer). Example usage: 
       JsonValue value =
         json(object(field("uid", "bjensen"),
                     field("roles", array("sales", "marketing"))),
                    pointer("/users/0"));
      Parameters:
      object - the Java object representing the JSON value.
      pointer - the pointer to the value in a JSON structure.
      Returns:
      The JSON value.

    • object

      @SafeVarargs public static Map<String,Object> object(Map.Entry<String,Object>... fields)
      Returns a JSON object comprised of the provided JSON fields. This method is provided as a convenience method for constructing JSON objects. Example usage: 
       JsonValue value = json(object(field("uid", "bjensen"), field("age", 30)));
      Parameters:
      fields - The list of fields to include in the JSON object. null elements are allowed, but are not included in the returned map (this makes it easier to include optional elements).
      Returns:
      The JSON object.

    • object

      public static Map<String,Object> object(int size)
      Produces an empty JSON object pre-allocated for size fields. This method is provided as a convenience method for constructing JSON objects. Example usage: 
       JsonValue value = json(object(20));
 for (Map.Entry<String, Object> entry : someMap.entrySet()) {
     value.put(entry.getKey(), entry.getValue());
 }
      Parameters:
      size - The size of the JSON object to allocate.
      Returns:
      The [empty] JSON object.

    • toIndex

      public static int toIndex(String key)
      Returns the key as an list index value. If the string does not represent a valid list index value, then -1 is returned.
      Parameters:
      key - the key to be converted into an list index value.
      Returns:
      the converted index value, or -1 if invalid.

    • add

      public JsonValue add(int index, Object object)
      Adds the specified value to the list. Adding a value to a list shifts any existing elements at or above the specified index to the right by one.
      Parameters:
      index - the List index of the value to add.
      object - the java object to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if this JSON value is not a List or index is out of range.

    • add

      public JsonValue add(JsonPointer pointer, Object object)
      Adds the value identified by the specified pointer, relative to this value as root. If doing so would require the creation of a new object or list, a JsonValueException will be thrown.

      NOTE: values may be added to a list using the reserved JSON pointer token "-". For example, the pointer "/a/b/-" will add a new element to the list referenced by "/a/b".

      Parameters:
      pointer - identifies the child value to add.
      object - the Java object value to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the specified pointer is invalid.

    • add

      public JsonValue add(Object object)
      Adds the specified value to the end of the list. This method is equivalent to the following code: 
       add(size(), object);
      Parameters:
      object - the java object to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if this JSON value is not a List.

    • add

      public JsonValue add(String key, Object object)
      Adds the specified value.

      If adding to a list value, the specified key must be parseable as an unsigned base-10 integer and be less than or equal to the list size. Adding a value to a list shifts any existing elements at or above the specified index to the right by one.

      Parameters:
      key - the Map key or List index to add.
      object - the Java object to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if not a Map or List, the Map key already exists, or the List index is out of range.

    • addIfNotNull

      public JsonValue addIfNotNull(String key, Object object)
      Adds the specified object value only if it is not null

      For further usage information, see documentation for add(String, Object).

      Parameters:
      key - the Map key or List index to add.
      object - the Java object to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if not a Map or List, the Map key already exists, or the List index is out of range.

    • addPermissive

      public JsonValue addPermissive(JsonPointer pointer, Object object)
      Adds the value identified by the specified pointer, relative to this value as root. Missing parent objects or lists will be created on demand.

      NOTE: values may be added to a list using the reserved JSON pointer token "-". For example, the pointer "/a/b/-" will add a new element to the list referenced by "/a/b".

      Parameters:
      pointer - identifies the child value to add.
      object - the Java object value to add.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the specified pointer is invalid.

    • asBoolean

      public Boolean asBoolean()
      Returns the JSON value as a Boolean object. If the value is null, this method returns null.
      Returns:
      the boolean value.
      Throws:
      JsonValueException - if the JSON value is not a boolean type.

    • asDouble

      public Double asDouble()
      Returns the JSON value as a Double object. This may involve rounding. If the JSON value is null, this method returns null.
      Returns:
      the double-precision floating point value.
      Throws:
      JsonValueException - if the JSON value is not a number.

    • asInteger

      public Integer asInteger()
      Returns the JSON value as an Integer object. This may involve rounding or truncation. If the JSON value is null, this method returns null.
      Returns:
      the integer value.
      Throws:
      JsonValueException - if the JSON value is not a number.

    • asCollection

      public Collection<Object> asCollection()
      Returns the JSON value as a Collection object. If the JSON value is null, this method returns null.
      Returns:
      the collection value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a Collection.

    • asList

      public List<Object> asList()
      Returns the JSON value as a List object. If the JSON value is null, this method returns null. The returned List is not a copy : any interaction with it will affect the JsonValue.
      Returns:
      the list value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a List.

    • asCollection

      public <E> Collection<E> asCollection(Class<E> type)
      Returns the JSON value as a Collection containing objects of the specified type. If the value is null, this method returns null. If any of the elements of the collection are not null and not of the specified type, JsonValueException is thrown. The returned Collection is not a copy : any interaction with it will affect the JsonValue.
      Type Parameters:
      E - the type of elements in this collection
      Parameters:
      type - the type of object that all elements are expected to be.
      Returns:
      the collection value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a Collection or contains an unexpected type.
      NullPointerException - if type is null.

    • asList

      public <E> List<E> asList(Class<E> type)
      Returns the JSON value as a List containing objects of the specified type. If the value is null, this method returns null. If any of the elements of the list are not null and not of the specified type, JsonValueException is thrown. The returned List is not a copy : any interaction with it will affect the JsonValue.
      Type Parameters:
      E - the type of elements in this list
      Parameters:
      type - the type of object that all elements are expected to be.
      Returns:
      the list value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a List or contains an unexpected type.
      NullPointerException - if type is null.

    • as

      public <V, E extends Exception> V as(Function<JsonValue,V,E> transformFunction) throws E
      Returns the JSON value as an object whose type (and value) is specified by a transformation function. It is up to the transformation function to transform/enforce source types of the elements in the Json source element and to decide what to do depending on the kind of JsonValue : if it is null, a String, a List, or Map. If the type-transformation cannot occur, the exception specified by the transformation function is thrown.
      Type Parameters:
      V - the type of element
      E - the type of exception thrown by the transformation function
      Parameters:
      transformFunction - a Function to transform the JsonValue element to the desired type
      Returns:
      the value, or null if no value.
      Throws:
      E - if the JsonValue element cannot be transformed
      NullPointerException - if transformFunction is null.

    • asAsync

      public <V, E extends Exception> Promise<V,E> asAsync(AsyncFunction<JsonValue,V,E> transformFunction)
      Returns the JSON value as a promised object whose type (and value) is specified by a transformation function. It is up to the transformation function to transform/enforce source types of the elements in the Json source element and to decide what to do depending on the kind of JsonValue : if it is null, a String, a List, or Map. If the type-transformation cannot occur, the exception specified by the transformation function is thrown.
      Type Parameters:
      V - the type of element
      E - the type of exception thrown by the transformation function
      Parameters:
      transformFunction - a Function to transform the JsonValue element to the desired type
      Returns:
      the promise of the value, the final value may be null, but the promise itself can't. In case of exception the result promise is failed and contains the exception.

    • asLong

      public Long asLong()
      Returns the JSON value as a Long object. This may involve rounding or truncation. If the JSON value is null, this method returns null.
      Returns:
      the long integer value.
      Throws:
      JsonValueException - if the JSON value is not a number.

    • asMap

      public Map<String,Object> asMap()
      Returns the JSON value as a Map object. If the JSON value is null, this method returns null.
      Returns:
      the map value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a Map.

    • asMap

      public <V> Map<String,V> asMap(Class<V> type)
      Returns the JSON value as a Map containing objects of the specified type. If the value is null, this method returns null. If any of the values of the map are not null and not of the specified type, JsonValueException is thrown.
      Type Parameters:
      V - the type of values in this map
      Parameters:
      type - the type of object that all values are expected to be.
      Returns:
      the map value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a Map or contains an unexpected type.
      NullPointerException - if type is null.

    • asMapOfList

      public <E> Map<String,List<E>> asMapOfList(Class<E> elementType)
      Returns the JSON value as a Map containing a collection of objects of the specified type. If the value is null, this method returns null. If any of the values of the map are not null and not of the specified type, JsonValueException is thrown.
      Type Parameters:
      E - the type of elements in the collection
      Parameters:
      elementType - the type of object that all collection elements are expected to be.
      Returns:
      the map value, or null if no value.
      Throws:
      JsonValueException - if the JSON value is not a Map or contains an unexpected type.
      NullPointerException - if type is null.

    • asNumber

      public Number asNumber()
      Returns the JSON value as a Number object. If the JSON value is null, this method returns null.
      Returns:
      the numeric value.
      Throws:
      JsonValueException - if the JSON value is not a number.

    • asString

      public String asString()
      Returns the JSON value as a String object. If the JSON value is null, this method returns null.
      Returns:
      the string value.
      Throws:
      JsonValueException - if the JSON value is not a string.

    • clear

      public void clear()
      Removes all child values from this JSON value, if it has any.

    • clone

      public JsonValue clone()
      Returns a shallow copy of this JSON value. If this JSON value contains a Map or a List object, the returned JSON value will contain a shallow copy of the original contained object.

      The new value's members can be modified without affecting the original value. Modifying the member's members will almost certainly affect the original value. To avoid this, use the copy() method to return a deep copy of the JSON value.

      This method does not traverse the value's members, nor will it apply any transformations.

      Overrides:
      clone in class Object
      Returns:
      a shallow copy of this JSON value.

    • contains

      public boolean contains(Object object)
      Returns true this JSON value contains an item with the specified value.
      Parameters:
      object - the object to seek within this JSON value.
      Returns:
      true if this value contains the specified member value.

    • copy

      public JsonValue copy()
      Returns a deep copy of this JSON value.

      Note: This method is recursive, and currently has no ability to detect or correct for structures containing cyclic references. Processing such a structure will result in a StackOverflowError being thrown.

      Returns:
      a deep copy of this JSON value.

    • defaultTo

      public JsonValue defaultTo(Object object)
      Defaults the JSON value to the specified value if it is currently null.
      Parameters:
      object - the object to default to.
      Returns:
      this JSON value or a new JSON value containing the default value.

    • expect

      public JsonValue expect(Class<?> type)
      Called to enforce that the JSON value is of a particular type. A value of null is allowed.
      Parameters:
      type - the class that the underlying value must have.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the value is not the specified type.

    • get

      public JsonValue get(int index)
      Returns the specified child value. If this JSON value is not a List or if no such child exists, then a JSON value containing a null is returned.
      Parameters:
      index - index of child element value to return.
      Returns:
      the child value, or a JSON value containing null.
      Throws:
      JsonValueException - if index is negative.

    • get

      public JsonValue get(JsonPointer pointer)
      Returns the specified child value with a pointer, relative to this value as root. If the specified child value does not exist, then null is returned.
      Parameters:
      pointer - the JSON pointer identifying the child value to return.
      Returns:
      the child value, or null if no such value exists.

    • get

      public JsonValue get(String key)
      Returns the specified item value. If no such member value exists, then a JSON value containing null is returned.
      Parameters:
      key - the Map key or List index identifying the item to return.
      Returns:
      a JSON value containing the value or null.

    • getObject

      public Object getObject()
      Returns the raw Java object representing this JSON value.
      Returns:
      the raw Java object representing this JSON value.

    • getPointer

      public JsonPointer getPointer()
      Returns the pointer of the JSON value in its JSON structure.
      Returns:
      the pointer of the JSON value in its JSON structure.

    • isBoolean

      public boolean isBoolean()
      Returns true if the JSON value is a Boolean.
      Returns:
      true if the JSON value is a Boolean.

    • isDefined

      public boolean isDefined(String key)
      Returns true if this JSON value contains the specified item.
      Parameters:
      key - the Map key or List index of the item to seek.
      Returns:
      true if this JSON value contains the specified member.
      Throws:
      NullPointerException - if key is null.

    • isCollection

      public boolean isCollection()
      Returns true if the JSON value is a Collection.
      Returns:
      true if the JSON value is a Collection.

    • isList

      public boolean isList()
      Returns true if the JSON value is a List.
      Returns:
      true if the JSON value is a List.

    • isMap

      public boolean isMap()
      Returns true if the JSON value is a Map.
      Returns:
      true if the JSON value is a Map.

    • isNull

      public boolean isNull()
      Returns true if the value is null.
      Returns:
      true if the value is null.

    • isNotNull

      public boolean isNotNull()
      Returns true if the value is not null.
      Returns:
      true if the value is not null.

    • isNumber

      public boolean isNumber()
      Returns true if the JSON value is a Number.
      Returns:
      true if the JSON value is a Number.

    • isString

      public boolean isString()
      Returns true if the JSON value is a String.
      Returns:
      true if the JSON value is a String.

    • iterator

      public Iterator<JsonValue> iterator()
      Returns an iterator over the child values that this JSON value contains. If this value is a Map, then the order of the resulting child values is undefined. Calling the Iterator.remove() method of the returned iterator will throw a UnsupportedOperationException.
      Specified by:
      iterator in interface Iterable<JsonValue>
      Returns:
      an iterator over the child values that this JSON value contains.

    • keys

      public Set<String> keys()
      Returns the set of keys for this JSON value's child values. If this value is a Map, then the order of the resulting keys is the same as the underlying Map implementation. If there are no child values, this method returns an empty set.
      Returns:
      the set of keys for this JSON value's child values.

    • put

      public JsonValue put(int index, Object object)
      Sets the value of the specified child list element.
      Parameters:
      index - the List index identifying the child value to set.
      object - the Java value to assign to the list element.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if this JSON value is not a List or index is out of range.

    • putIfNotNull

      public JsonValue putIfNotNull(String key, Object object)
      Sets the value of the specified member, only if it is not null.

      For further usage information, see documentation for put(String, Object).

      Parameters:
      key - the Map key or List index identifying the child value to set.
      object - the object value to assign to the member.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if this JSON value is not a Map or List.
      NullPointerException - if key is null.

    • put

      public JsonValue put(JsonPointer pointer, Object object)
      Sets the value identified by the specified pointer, relative to this value as root. If doing so would require the creation of a new object or list, a JsonValueException will be thrown.

      NOTE: values may be added to a list using the reserved JSON pointer token "-". For example, the pointer "/a/b/-" will add a new element to the list referenced by "/a/b".

      Parameters:
      pointer - identifies the child value to set.
      object - the Java object value to set.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the specified pointer is invalid.

    • put

      public JsonValue put(String key, Object object)
      Sets the value of the specified member.  

      If setting a list element, the specified key must be parseable as an unsigned base-10 integer and be less than or equal to the size of the list.

      Parameters:
      key - the Map key or List index identifying the child value to set.
      object - the object value to assign to the member.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if this JSON value is not a Map or List.
      NullPointerException - if key is null.

    • putPermissive

      public JsonValue putPermissive(JsonPointer pointer, Object object)
      Sets the value identified by the specified pointer, relative to this value as root. Missing parent objects or lists will be created on demand.

      NOTE: values may be added to a list using the reserved JSON pointer token "-". For example, the pointer "/a/b/-" will add a new element to the list referenced by "/a/b".

      Parameters:
      pointer - identifies the child value to set.
      object - the Java object value to set.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the specified pointer is invalid.

    • remove

      public void remove(int index)
      Removes the specified child value, shifting any subsequent elements to the left. If the JSON value is not a List, calling this method has no effect.
      Parameters:
      index - the List index identifying the child value to remove.

    • remove

      public void remove(JsonPointer pointer)
      Removes the specified child value with a pointer, relative to this value as root. If the specified child value is not defined, calling this method has no effect.
      Parameters:
      pointer - the JSON pointer identifying the child value to remove.

    • remove

      public void remove(String key)
      Removes the specified child value. If the specified child value is not defined, calling this method has no effect.
      Parameters:
      key - the Map key or List index identifying the child value to remove.

    • required

      public JsonValue required()
      Throws a JsonValueException if the JSON value is null.
      Returns:
      this JSON value.
      Throws:
      JsonValueException - if the JSON value is null.

    • setObject

      public void setObject(Object object)
      Sets the Java object representing this JSON value.

      This method will automatically unwrap JsonValue objects.

      Parameters:
      object - the object to set.

    • size

      public int size()
      Returns the number of values that this JSON value contains.
      Returns:
      the number of values that this JSON value contains.

    • toString

      public String toString()
      Returns a string representation of the JSON value. The result resembles—but is not guaranteed to conform to—JSON syntax. This method does not apply transformations to the value's children.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the JSON value.

    • isEqualTo

      public boolean isEqualTo(JsonValue other)
      Performs a deep comparison of this JSON value with another JSON value, and returns whether the two objects are identical. Fails fast in that a false is returned as soon as a difference is detected.

      Note: Only values recognisable as JSON primitives (Map, List, Number, Boolean, String and null) are supported.

      Parameters:
      other - another value.
      Returns:
      whether the two objects are equal.
      Throws:
      NullPointerException - if other is null.
      IllegalArgumentException - if this or the other value contains non-JSON primitive values.

    • diff

      public JsonValue diff(JsonValue target)
      Performs a deep comparison of this JSON vlaue with another JSON value, and produces a JSON Patch value, which contains the operations necessary to modify the current value to arrive at the target value.
      Parameters:
      target - the intended target value.
      Returns:
      the resulting JSON Patch value.
      Throws:
      NullPointerException - if either of original or target are null.

    • patch

      public void patch(JsonValue patch)
      Applies a set of modifications in a JSON patch value to the current object, resulting in the intended target value. In the event of a failure, this method does not revert any modifications applied up to the point of failure.
      Parameters:
      patch - the JSON Patch value, specifying the modifications to apply to the original value.
      Throws:
      JsonValueException - if application of the patch failed.

    • merge

      public JsonValue merge(JsonValue other)
      Creates a new JSON value which combines the contents this JSON value with another.

      If there are any matching pointers in the two JSON values, then the value in other overrides the value in this.

      Parameters:
      other - Another JSON value which should be merged with this one.
      Returns:
      a new JSON value which combines the contents of this JSON value and other.

    • stream

      public Stream<JsonValue> stream()
      Construct a Stream from this JsonValue object.
      Returns:
      A Stream of JsonValue-wrapped Objects.