JsonValue (org.openidentityplatform.commons.parent 2.2.3 Documentation)

java.lang.Object
- org.forgerock.json.fluent.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.
A JSON value may have one or more transformers associated with it. Transformers apply transformations to the JSON value upon construction, and upon members as they are retrieved. Transformers are applied iteratively, in the sequence they appear within the list. If a transformer affects the value, then all transformers are re-applied, in sequence. This repeats until the value is no longer affected. Transformers are inherited by and applied to member values.

Constructor Summary

Constructors
Constructor and Description
`JsonValue(Object object)` Constructs a JSON value object with a given object.
`JsonValue(Object object, Collection<? extends JsonTransformer> transformers)` Constructs a JSON value object with a given object and transformers.
`JsonValue(Object object, JsonPointer pointer)` Constructs a JSON value object with a given object and pointer.
`JsonValue(Object object, JsonPointer pointer, Collection<? extends JsonTransformer> transformers)` Constructs a JSON value object with given object, pointer and transformers.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`add(int index, Object object)` Adds the specified value to the list.
`JsonValue`	`add(String key, Object object)` Adds the specified value.
`void`	`applyTransformers()` Applies all of the transformations to the value.
`Boolean`	`asBoolean()` Returns the JSON value as a `Boolean` object.
`Charset`	`asCharset()` Returns the JSON string value as a character set used for byte encoding/decoding.
`Double`	`asDouble()` Returns the JSON value as a `Double` object.
`<T extends Enum<T>> T`	`asEnum(Class<T> type)` Returns the JSON string value as an enum constant of the specified enum type.
`File`	`asFile()` Returns the JSON string value as a `File` object.
`Integer`	`asInteger()` Returns the JSON value as an `Integer` object.
`List<Object>`	`asList()` Returns the JSON value as a `List` object.
`<E> List<E>`	`asList(Class<E> type)` Returns the JSON value as a `List` containing objects of the specified type.
`Long`	`asLong()` Returns the JSON value as a `Long` object.
`Map<String,Object>`	`asMap()` Returns the JSON value as a `Map` object.
`Number`	`asNumber()` Returns the JSON value as a `Number` object.
`Pattern`	`asPattern()` Returns the JSON string value as a regular expression pattern.
`JsonPointer`	`asPointer()` Returns the JSON string value as a JSON pointer.
`String`	`asString()` Returns the JSON value as a `String` object.
`URI`	`asURI()` Returns the JSON string value as a uniform resource identifier.
`UUID`	`asUUID()` Returns the JSON string value as a universally unique identifier (UUID).
`void`	`clear()` Removes all child values from this JSON value, if it has any.
`JsonValue`	`clone()` Returns a shallow copy of this JSON value.
`boolean`	`contains(Object object)` Returns `true` this JSON value contains an item with the specified value.
`JsonValue`	`copy()` Returns a deep copy of this JSON value.
`JsonValue`	`defaultTo(Object object)` Defaults the JSON value to the specified value if it is currently `null`.
`JsonValue`	`expect(Class<?> type)` Called to enforce that the JSON value is of a particular type.
`JsonValue`	`get(int index)` Returns the specified child value.
`JsonValue`	`get(JsonPointer pointer)` Returns the specified child value with a pointer, relative to this value as root.
`JsonValue`	`get(String key)` Returns the specified item value.
`Object`	`getObject()` Returns the raw Java object representing this JSON value.
`JsonPointer`	`getPointer()` Returns the pointer of the JSON value in its JSON structure.
`List<JsonTransformer>`	`getTransformers()` Returns the JSON value's list of transformers.
`Object`	`getWrappedObject()` Returns a Java object representing this JSON value.
`boolean`	`isBoolean()` Returns `true` if the JSON value is a `Boolean`.
`boolean`	`isDefined(String key)` Returns `true` if this JSON value contains the specified item.
`boolean`	`isList()` Returns `true` if the JSON value is a `List`.
`boolean`	`isMap()` Returns `true` if the JSON value is a `Map`.
`boolean`	`isNull()` Returns `true` if the value is `null`.
`boolean`	`isNumber()` Returns `true` if the JSON value is a `Number`.
`boolean`	`isString()` Returns `true` if the JSON value is a `String`.
`Iterator<JsonValue>`	`iterator()` Returns an iterator over the child values that this JSON value contains.
`Set<String>`	`keys()` Returns the set of keys for this JSON value's child values.
`void`	`put(int index, Object object)` Sets the value of the specified child list element.
`void`	`put(JsonPointer pointer, Object object)` Sets the value of the value identified by the specified pointer, relative to this value as root.
`void`	`put(String key, Object object)` Sets the value of the specified member.
`void`	`remove(int index)` Removes the specified child value, shifting any subsequent elements to the left.
`void`	`remove(String key)` Removes the specified child value.
`JsonValue`	`required()` Throws a `JsonValueException` if the JSON value is `null`.
`void`	`setObject(Object object)` Sets the Java object representing this JSON value.
`int`	`size()` Returns the number of values that this JSON value contains.
`String`	`toString()` Returns a string representation of the JSON value.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Constructor Detail
  - JsonValue
```
public JsonValue(Object object,
                 JsonPointer pointer,
                 Collection<? extends JsonTransformer> transformers)
          throws JsonException
```
    Constructs a JSON value object with given object, pointer and transformers. This constructor will automatically unwrap any JsonValueWrapper and/or JsonValue objects. The pointer is inherited from the wrapped value, except if pointer is not null. The transformers are inherited from the wrapped value, except if transformers is not null.
    
    Parameters:
    
    object - the Java object representing the JSON value.
    
    pointer - the pointer to the value in a JSON structure.
    
    transformers - a list of transformers to apply the value and its members.
    
    Throws:
    
    JsonException - if a transformer failed during value initialization.
  - JsonValue
```
public JsonValue(Object object,
                 Collection<? extends JsonTransformer> transformers)
```
    Constructs a JSON value object with a given object and transformers. This constructor will automatically unwrap any JsonValueWrapper and/or JsonValue objects.
    
    Parameters:
    
    object - the Java object representing the JSON value.
    
    transformers - a list of transformers to apply the value and its members.
    
    Throws:
    
    JsonException - if a transformer failed during value initialization.
  - JsonValue
```
public JsonValue(Object object,
                 JsonPointer pointer)
```
    Constructs a JSON value object with a given object and pointer. This constructor will automatically unwrap any JsonValueWrapper and/or JsonValue objects.
    
    Parameters:
    
    object - the Java object representing the JSON value.
    
    pointer - the pointer to the value in a JSON structure.
  - JsonValue
```
public JsonValue(Object object)
```
    Constructs a JSON value object with a given object. This constructor will automatically unwrap any JsonValueWrapper and/or JsonValue objects.
    
    Parameters:
    
    object - the Java object representing JSON value.
- Method Detail
  - getObject
```
public Object getObject()
```
    Returns the raw Java object representing this JSON value.
  - getWrappedObject
```
public Object getWrappedObject()
```
    Returns a Java object representing this JSON value. If the object is a Map or List, it is wrapped with a JsonValueMap or JsonValueList object respectively. This maintains and applies transformations as these objects (and their children) are accessed.
  - setObject
```
public void setObject(Object object)
```
    Sets the Java object representing this JSON value. Does not apply transformers to the new value.
    This method will automatically unwrap any JsonValueWrapper and/or JsonValue objects. Transformers are inherited from the wrapped value. This value's pointer remains unaffected.
    
    Parameters:
    
    object - the object to set.
  - getPointer
```
public JsonPointer getPointer()
```
    Returns the pointer of the JSON value in its JSON structure.
  - getTransformers
```
public List<JsonTransformer> getTransformers()
```
    Returns the JSON value's list of transformers. This list is modifiable. Child values inherit the list when they are constructed. If any transformers are added to the list, call the applyTransformers() method to apply them to the current value.
  - applyTransformers
```
public void applyTransformers()
                       throws JsonException
```
    Applies all of the transformations to the value. If a transformer affects the value, then all transformers are re-applied. This repeats until the value is no longer affected.
    This method has an absurdly high upper-limit of Integer.MAX_VALUE iterations, beyond which a JsonException will be thrown.
    
    Throws:
    
    JsonException - if there was a failure applying transformation(s)
  - required
```
public JsonValue required()
                   throws JsonValueException
```
    Throws a JsonValueException if the JSON value is null.
    
    Returns:
    
    this JSON value.
    
    Throws:
    
    JsonValueException - if the JSON value is null.
  - expect
```
public JsonValue expect(Class<?> type)
                 throws JsonValueException
```
    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.
  - isMap
```
public boolean isMap()
```
    Returns true if the JSON value is a Map.
  - asMap
```
public Map<String,Object> asMap()
                         throws JsonValueException
```
    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.
  - isList
```
public boolean isList()
```
    Returns true if the JSON value is a List.
  - asList
```
public List<Object> asList()
                    throws JsonValueException
```
    Returns the JSON value as a List object. If the JSON value is null, this method returns null.
    
    Returns:
    
    the list value, or null if no value.
    
    Throws:
    
    JsonValueException - if the JSON value is not a List.
  - asList
```
public <E> List<E> asList(Class<E> type)
                   throws JsonValueException
```
    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.
    
    Parameters:
    
    type - the type of object that all elements are expected to be.
    
    Returns:
    
    the list value, or null if no value.
    
    Throws:
    
    JsonVaueException - if the JSON value is not a List or contains an unexpected type.
    
    NullPointerException - if type is null.
    
    JsonValueException
  - isString
```
public boolean isString()
```
    Returns true if the JSON value is a String.
  - asString
```
public String asString()
                throws JsonValueException
```
    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.
  - isNumber
```
public boolean isNumber()
```
    Returns true if the JSON value is a Number.
  - asNumber
```
public Number asNumber()
                throws JsonValueException
```
    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.
  - asInteger
```
public Integer asInteger()
                  throws JsonValueException
```
    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.
  - asDouble
```
public Double asDouble()
                throws JsonValueException
```
    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.
  - asLong
```
public Long asLong()
            throws JsonValueException
```
    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.
  - isBoolean
```
public boolean isBoolean()
```
    Returns true if the JSON value is a Boolean.
  - asBoolean
```
public Boolean asBoolean()
                  throws JsonValueException
```
    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.
  - isNull
```
public boolean isNull()
```
    Returns true if the value is null.
  - asEnum
```
public <T extends Enum<T>> T asEnum(Class<T> type)
                             throws JsonValueException
```
    Returns the JSON string value as an enum constant of the specified enum type. The string value and enum constants are compared, ignoring case considerations. If the JSON value is null, this method returns null.
    
    Parameters:
    
    type - the enum type to match constants with the value.
    
    Returns:
    
    the enum constant represented by the string value.
    
    Throws:
    
    IllegalArgumentException - if type does not represent an enum type.
    
    JsonValueException - if the JSON value does not match any of the enum's constants.
    
    NullPointerException - if type is null.
  - asFile
```
public File asFile()
            throws JsonValueException
```
    Returns the JSON string value as a File object. If the JSON value is null, this method returns null.
    
    Returns:
    
    a file represented by the string value.
    
    Throws:
    
    JsonValueException - if the JSON value is not a string.
  - asCharset
```
public Charset asCharset()
                  throws JsonValueException
```
    Returns the JSON string value as a character set used for byte encoding/decoding. If the JSON value is null, this method returns null.
    
    Returns:
    
    the character set represented by the string value.
    
    Throws:
    
    JsonValueException - if the JSON value is not a string or the character set specified is invalid.
  - asPattern
```
public Pattern asPattern()
                  throws JsonValueException
```
    Returns the JSON string value as a regular expression pattern. If the JSON value is null, this method returns null.
    
    Returns:
    
    the compiled regular expression pattern.
    
    Throws:
    
    JsonValueException - if the pattern is not a string or the value is not a valid regular expression pattern.
  - asURI
```
public URI asURI()
          throws JsonValueException
```
    Returns the JSON string value as a uniform resource identifier. If the JSON value is null, this method returns null.
    
    Returns:
    
    the URI represented by the string value.
    
    Throws:
    
    JsonValueException - if the given string violates URI syntax.
  - asPointer
```
public JsonPointer asPointer()
                      throws JsonValueException
```
    Returns the JSON string value as a JSON pointer. If the JSON value is null, this method returns null.
    
    Returns:
    
    the JSON pointer represented by the JSON value string.
    
    Throws:
    
    JsonValueException - if the JSON value is not a string or valid JSON pointer.
  - asUUID
```
public UUID asUUID()
            throws JsonValueException
```
    Returns the JSON string value as a universally unique identifier (UUID). If the JSON value is null, this method returns null.
    
    Returns:
    
    the UUID represented by the JSON value string.
    
    Throws:
    
    JsonValueException - if the JSON value is not a string or valid UUID.
  - 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.
  - size
```
public int size()
```
    Returns the number of values that this JSON value contains.
  - 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.
  - 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.
  - get
```
public JsonValue get(String key)
              throws JsonException
```
    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.
    
    Throws:
    
    JsonException - if a transformer failed to transform the child value.
  - get
```
public JsonValue get(int index)
              throws JsonException
```
    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.
    
    JsonException - if a transformer failed to transform the child value.
  - get
```
public JsonValue get(JsonPointer pointer)
              throws JsonException
```
    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.
    
    Throws:
    
    JsonException - if a transformer failed to transform the resulting value.
  - put
```
public void put(String key,
                Object object)
         throws JsonValueException
```
    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.
    
    Throws:
    
    JsonValueException - if this JSON value is not a Map or List.
    
    NullPointerException - if key is null.
  - put
```
public void put(int index,
                Object object)
         throws JsonValueException
```
    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.
    
    Throws:
    
    JsonValueException - if this JSON value is not a List or index is out of range.
  - put
```
public void put(JsonPointer pointer,
                Object object)
         throws JsonValueException
```
    Sets the value of 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.
    
    Parameters:
    
    pointer - identifies the child value to set.
    
    object - the Java object value to set.
    
    Throws:
    
    JsonValueException - if the specified pointer is invalid.
  - 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.
  - 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.
  - clear
```
public void clear()
           throws JsonValueException
```
    Removes all child values from this JSON value, if it has any.
    
    Throws:
    
    JsonValueException
  - add
```
public JsonValue add(String key,
                     Object object)
              throws JsonValueException
```
    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.
    
    Throws:
    
    JsonValueException - if not a Map or List, the Map key already exists, or the List index is out of range.
  - add
```
public void add(int index,
                Object object)
         throws JsonValueException
```
    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.
    
    Throws:
    
    JsonValueException - if this JSON value is not a List or index is out of range.
  - 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 undefined. If there are no child values, this method returns an empty set.
  - 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.
    Note: calls to the next() method may throw the runtime JsonException if any transformers fail to execute.
    
    Specified by:
    
    iterator in interface Iterable<JsonValue>
  - copy
```
public JsonValue copy()
```
    Returns a deep copy of this JSON value.
    This method applies all transformations while traversing the values's members and their members, and so on. Consequently, the returned copy does not include the transformers from this 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.
  - 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
  - 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

Class JsonValue

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

JsonValue

JsonValue

JsonValue

JsonValue

Method Detail

getObject

getWrappedObject

setObject

getPointer

getTransformers

applyTransformers

required

expect

isMap

asMap

isList

asList

asList

isString

asString

isNumber

asNumber

asInteger

asDouble

asLong

isBoolean

asBoolean

isNull

asEnum

asFile

asCharset

asPattern

asURI

asPointer

asUUID

defaultTo

size

isDefined

contains

get

get

get

put

put

put

remove

remove

clear

add

add

keys

iterator

copy

clone

toString