JSNode (inversion-api 0.9.27.1 API)

java.lang.Object
- io.inversion.utils.JSNode

All Implemented Interfaces:

java.util.Map<java.lang.String,java.lang.Object>

Direct Known Subclasses:

JSArray
```
public class JSNode
extends java.lang.Object
implements java.util.Map<java.lang.String,java.lang.Object>
```
Yet another JavaScript/JSON map object representation with a few superpowers.
Inversion encourages working with JSON data structures abstractly instead of transcoding them into a concrete Java object model. So JSNode and JSArray were designed to make it as easy as possible to work with JSON in its "native form."
JSNode and JSArray are a one stop shop for:
- Parsing and printing JSON
- Finding elements of a document with JSONPath and JSONPointer
- Diff and patching with JSONPatch
Property name case is preserved but considered case insensitive when accessing a property by name.
Property iteration or is preserved based on insertion order.
It is possible to create a document with a child JSNode appearing multiple times in the document including circular reference loops. When printing a document, if a JSNode has previously been printed AND it has an 'href' property, instead of erroring, the printer will write an '@link' property pointing to the previously printed href. If the JSNode does not have an 'href' an error will be thrown.
Under the covers this Jackson is used as the json parser.
See Also:

JSArray, JSONPath, JSONPointer, JSONPatch

Nested Class Summary
- Nested classes/interfaces inherited from interface java.util.Map
  java.util.Map.Entry<K,V>

Constructor Summary

Constructors
Constructor and Description
`JSNode()` Creates an empty JSNode.
`JSNode(java.util.Map nameValuePairs)` Creates a JSNode with `nameValuePairs` as the initial properties.
`JSNode(java.lang.Object... nameValuePairs)` Creates a JSNode with `nameValuePairs` as the initial properties.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`JSArray`	`asArray()` Similar to #asList() but instead of returning a List, it returns a this JSNode as the only item in a JSArray.
`java.util.List`	`asList()` Returns this object as the only element in a list.
`java.util.Map<? extends java.lang.String,? extends java.lang.Object>`	`asMap()`
`java.util.List<JSNode>`	`asNodeList()` Returns this object as the only element in a List
`void`	`clear()` Removes all properties
`boolean`	`containsKey(java.lang.Object name)`
`boolean`	`containsValue(java.lang.Object value)` Checks all property values for equality to `value`
`JSNode`	`copy()` Makes a deep copy of this JSNode by stringifying/parsing.
`JSArray`	`diff(JSNode source)`
`java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>>`	`entrySet()`
`java.lang.Object`	`find(java.lang.String pathExpression)` Convenience overloading of `findAll(String, int)` that returns the first item found
`JSArray`	`findAll(java.lang.String pathExpression)` Convenience overloading of `findAll(String, int)`
`JSArray`	`findAll(java.lang.String pathExpression, int qty)` A heroically permissive finder supporting JSON Pointer, JSONPath and a simple 'dot and wildcard' type of system like so: 'propName.childPropName..skippedGenerationPropsName.4.fifthArrayNodeChildPropsName.*.recursivelyFoundPropsName'.
`java.util.List<JSNode>`	`findAllNodes(java.lang.String pathExpression)` Convenience overloading of `findAll(String, int)`
`JSArray`	`findArray(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`boolean`	`findBoolean(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`double`	`findDouble(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`int`	`findInt(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`long`	`findLong(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`JSNode`	`findNode(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`java.lang.String`	`findString(java.lang.String pathExpression)` Convenience overloading of `find(String)`
`java.lang.Object`	`get(java.lang.Object name)`
`JSArray`	`getArray(java.lang.String name)` Convenience overloading of `get(Object)`
`boolean`	`getBoolean(java.lang.String name)` Convenience overloading of `get(Object)`
`double`	`getDouble(java.lang.String name)` Convenience overloading of `get(Object)`
`int`	`getInt(java.lang.String name)` Convenience overloading of `get(Object)`
`long`	`getLong(java.lang.String name)` Convenience overloading of `get(Object)`
`JSNode`	`getNode(java.lang.String name)` Convenience overloading of `get(Object)`
`java.lang.String`	`getString(java.lang.String name)` Convenience overloading of `get(Object)`
`boolean`	`hasProperty(java.lang.String name)`
`boolean`	`isArray()` Easy alternative to 'instanceof' to differentiate JSNode from JSArray (which subclasses JSNode).
`boolean`	`isEmpty()`
`java.util.Set<java.lang.String>`	`keySet()`
`static java.lang.Object`	`parseJson(java.lang.String json)` Turns a JSON string in to JSNode (maps), JSArray (lists), String numbers and booleans.
`static JSArray`	`parseJsonArray(java.lang.String json)` Utility overloading of `parseJson(String)` to cast the return as a JSArray
`static JSNode`	`parseJsonNode(java.lang.String json)` Utility overloading of `parseJson(String)` to cast the return as a JSNode
`void`	`patch(JSArray patches)`
`java.lang.Object`	`put(java.lang.String name, java.lang.Object value)`
`void`	`putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> map)`
`java.lang.Object`	`putFirst(java.lang.String name, java.lang.Object value)` Vanity method to make sure the attributes prints out first
`java.lang.Object`	`remove(java.lang.Object name)`
`java.lang.Object`	`removeAll(java.lang.String... names)` Removes all properties with `names`.
`int`	`size()`
`void`	`sortKeys()` Changes the property name iteration order from insertion order to alphabetic order.
`java.util.stream.Stream`	`stream()` Convenience method that calls asList().stream().
`java.util.stream.Stream`	`streamAll()`
`java.lang.String`	`toString()`
`java.lang.String`	`toString(boolean pretty)` Prints the JSNode with properties written out in their original case.
`java.lang.String`	`toString(boolean pretty, boolean lowercasePropertyNames)` Prints the JSNode
`java.util.Collection`	`values()`
`JSNode`	`with(java.lang.Object... nvPairs)`

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

Methods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

- Constructor Detail
  - JSNode
```
public JSNode()
```
    Creates an empty JSNode.
  - JSNode
```
public JSNode(java.lang.Object... nameValuePairs)
```
    Creates a JSNode with nameValuePairs as the initial properties.
    The first and every other element in nameValuePairs should be a string.
    
    Parameters:
    
    nameValuePairs - the name value pairs to add
    
    See Also:
    
    with(Object...)
  - JSNode
```
public JSNode(java.util.Map nameValuePairs)
```
    Creates a JSNode with nameValuePairs as the initial properties.
    
    Parameters:
    
    nameValuePairs - the name value pairs to add
    
    See Also:
    
    putAll(Map)
- Method Detail
  - parseJson
```
public static java.lang.Object parseJson(java.lang.String json)
```
    Turns a JSON string in to JSNode (maps), JSArray (lists), String numbers and booleans.
    Jackson is the underlying parser
    
    Parameters:
    
    json - the json string to parse
    
    Returns:
    
    a String, number, boolean, JSNode or JSArray
  - parseJsonNode
```
public static JSNode parseJsonNode(java.lang.String json)
                            throws java.lang.ClassCastException
```
    Utility overloading of parseJson(String) to cast the return as a JSNode
    
    Parameters:
    
    json - the json string to parse
    
    Returns:
    
    the result of parsing the json document cast to a JSNode
    
    Throws:
    
    java.lang.ClassCastException - if the result of parsing is not a JSNode
  - parseJsonArray
```
public static JSArray parseJsonArray(java.lang.String json)
```
    Utility overloading of parseJson(String) to cast the return as a JSArray
    
    Parameters:
    
    json - a json string containing an as the root element
    
    Returns:
    
    the result of parsing the json document cast to a JSArray
    
    Throws:
    
    java.lang.ClassCastException - if the result of parsing is not a JSArray
  - findAll
```
public JSArray findAll(java.lang.String pathExpression,
                       int qty)
```
    A heroically permissive finder supporting JSON Pointer, JSONPath and a simple 'dot and wildcard' type of system like so: 'propName.childPropName.*.skippedGenerationPropsName.4.fifthArrayNodeChildPropsName.**.recursivelyFoundPropsName'.
    All forms are internally converted into a 'master' form before processing. This master simply uses '.' to separate property names and array indexes and uses uses '*' to represent a single level wildcard and '**' to represent a recursive wildcard. For example:
    - 'myProp' finds 'myProp' in this node.
    - 'myProp.childProp' finds 'childProp' on 'myProp'
    - 'myArrayProp.2.*' finds all properties of the third element of the 'myArrayProp'
    - '*.myProp' finds 'myProp' in any of the children of this node.
    - '**.myProp' finds 'myProp' anywhere in my descendents.
    - '**.myProp.*.value' finds 'value' as a grandchild anywhere under me.
    - '**.*' returns every element of the document.
    - '**.5' gets the 6th element of every array.
    - '**.book[?(@.isbn)]' finds all books with an isbn
    - '**.[?(@.author = 'Herman Melville')]' finds all book with author 'Herman Melville'
    Arrays indexes are treated just like property names but with integer names. For example "myObject.4.nextProperty" finds "nextProperty" on the 5th element in the "myObject" array.
    JSON Pointer is the least expressive supported form and uses '/' characters to separate properties. To support JSON Pointer, we simply replace all '/' characters for "." characters before processing.
    JSON Path is more like XML XPath but uses '.' instead of '/' to separate properties. Technically JSON Path statements are supposed to start with '$.' but that is optional here. The best part about JSON Path is the query filters that let you conditionally select elements.
    Below is the implementation status of various JSON Path features:
    - SUPPORTED $.store.book[*].author //the authors of all books in the store
    - SUPPORTED $..author //all authors
    - SUPPORTED $.store..price //the prices of all books
    - SUPPORTED $..book[2] //the third book
    - SUPPORTED $..book[?(@.price@lt;10)] //all books priced @lt; 10
    - SUPPORTED $..[?(@.price@lt;10)] //find any node with a price property
    - SUPPORTED $..[?(@.*.price@lt;10)] //find the parent of any node with a price property
    - SUPPORTED $..book[?(@.author = 'Herman Melville')] //all books where 'Herman Melville' is the author
    - SUPPORTED $..* //all members of JSON structure.
    - SUPPORTED $..book[(@.length-1)] //the last book in order
    - SUPPORTED $..book[-1:] //the last book in order
    - SUPPORTED $..book[0,1] //the first two books
    - SUPPORTED $..book[:2] //the first two books
    - SUPPORTED $..book[?(@.isbn)] //find all books with an isbn property
    - SUPPORTED $..[?(@.isbn)] //find any node with an isbn property
    - SUPPORTED $..[?(@.*.isbn)] //find the parent of any node with an isbn property
    - SUPPORTED $..[?(@.*.*.isbn)] //find the grandparent of any node with an isbn property
    The JSON Path following boolean comparison operators are supported:
    - =
    - @gt;
    - @lt;
    - @gt;=
    - @lt;=
    - !=
    JsonPath bracket-notation such as "$['store']['book'][0]['title']" is currently not supported.
    Parameters:
    
    pathExpression - defines the properties to find
    
    qty - the maximum number of results
    
    Returns:
    
    an array of found values
    
    See Also:
    
    JSON Pointer, JSON Path, JSON Path
  - diff
```
public JSArray diff(JSNode source)
```
  - patch
```
public void patch(JSArray patches)
```
  - get
```
public java.lang.Object get(java.lang.Object name)
```
    Specified by:
    
    get in interface java.util.Map<java.lang.String,java.lang.Object>
  - getNode
```
public JSNode getNode(java.lang.String name)
               throws java.lang.ClassCastException
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name cast to a JSNode if exists else null
    
    Throws:
    
    java.lang.ClassCastException - if the object found is not a JSNode
    
    See Also:
    
    get(Object)
  - getArray
```
public JSArray getArray(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name cast to a JSArray if exists else null
    
    Throws:
    
    java.lang.ClassCastException - if the object found is not a JSArray
    
    See Also:
    
    get(Object)
  - getString
```
public java.lang.String getString(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the stringified value of property name if it exists else null
    
    See Also:
    
    get(Object)
  - getInt
```
public int getInt(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name stringified and parsed as an int if it exists else -1
    
    See Also:
    
    get(Object)
  - getLong
```
public long getLong(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name stringified and parsed as long if it exists else -1
    
    See Also:
    
    get(Object)
  - getDouble
```
public double getDouble(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name stringified and parsed as a double if it exists else -1
    
    See Also:
    
    get(Object)
  - getBoolean
```
public boolean getBoolean(java.lang.String name)
```
    Convenience overloading of get(Object)
    
    Parameters:
    
    name - the case insensitive property name to retrieve.
    
    Returns:
    
    the value of property name stringified and parsed as a boolean if it exists else false
    
    See Also:
    
    get(Object)
  - findNode
```
public JSNode findNode(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the nodes to find
    
    Returns:
    
    the first value found at pathExpression cast as a JSNode if exists else null
    
    Throws:
    
    java.lang.ClassCastException - if the object found is not a JSNode
    
    See Also:
    
    find(String)
  - findArray
```
public JSArray findArray(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression cast as a JSArray if exists else null
    
    Throws:
    
    java.lang.ClassCastException - if the object found is not a JSArray
    
    See Also:
    
    find(String)
  - findString
```
public java.lang.String findString(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression stringified if exists else null
    
    See Also:
    
    find(String)
  - findInt
```
public int findInt(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression stringified and parsed as an int if exists else -1
    
    See Also:
    
    find(String)
  - findLong
```
public long findLong(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression stringified and parsed as a long if exists else -1
    
    See Also:
    
    find(String)
  - findDouble
```
public double findDouble(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression stringified and parsed as a double if exists else -1
    
    See Also:
    
    find(String)
  - findBoolean
```
public boolean findBoolean(java.lang.String pathExpression)
```
    Convenience overloading of find(String)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first value found at pathExpression stringified and parsed as a boolean if exists else false
    
    See Also:
    
    find(String)
  - find
```
public java.lang.Object find(java.lang.String pathExpression)
```
    Convenience overloading of findAll(String, int) that returns the first item found
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    the first item found at pathExpression
    
    See Also:
    
    findAll(String, int)
  - findAll
```
public JSArray findAll(java.lang.String pathExpression)
```
    Convenience overloading of findAll(String, int)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    all items found for pathExpression
    
    See Also:
    
    findAll(String, int)
  - findAllNodes
```
public java.util.List<JSNode> findAllNodes(java.lang.String pathExpression)
```
    Convenience overloading of findAll(String, int)
    
    Parameters:
    
    pathExpression - specifies the properties to find
    
    Returns:
    
    all items found for pathExpression cast as a List
    
    See Also:
    
    findAll(String, int)
  - put
```
public java.lang.Object put(java.lang.String name,
                            java.lang.Object value)
```
    Specified by:
    
    put in interface java.util.Map<java.lang.String,java.lang.Object>
  - putAll
```
public void putAll(java.util.Map<? extends java.lang.String,? extends java.lang.Object> map)
```
    Specified by:
    
    putAll in interface java.util.Map<java.lang.String,java.lang.Object>
  - putFirst
```
public java.lang.Object putFirst(java.lang.String name,
                                 java.lang.Object value)
```
    Vanity method to make sure the attributes prints out first
    
    Parameters:
    
    name - the property name
    
    value - the property value
    
    Returns:
    
    the previous value of the property if it exists or null
  - with
```
public JSNode with(java.lang.Object... nvPairs)
```
  - containsKey
```
public boolean containsKey(java.lang.Object name)
```
    Specified by:
    
    containsKey in interface java.util.Map<java.lang.String,java.lang.Object>
  - remove
```
public java.lang.Object remove(java.lang.Object name)
```
    Specified by:
    
    remove in interface java.util.Map<java.lang.String,java.lang.Object>
  - removeAll
```
public java.lang.Object removeAll(java.lang.String... names)
```
    Removes all properties with names.
    
    Parameters:
    
    names - the keys to remove
    
    Returns:
    
    the first non null value for names
  - keySet
```
public java.util.Set<java.lang.String> keySet()
```
    Specified by:
    
    keySet in interface java.util.Map<java.lang.String,java.lang.Object>
  - hasProperty
```
public boolean hasProperty(java.lang.String name)
```
  - asMap
```
public java.util.Map<? extends java.lang.String,? extends java.lang.Object> asMap()
```
  - copy
```
public JSNode copy()
```
    Makes a deep copy of this JSNode by stringifying/parsing.
    
    Returns:
    
    a deep copy of this node.
  - sortKeys
```
public void sortKeys()
```
    Changes the property name iteration order from insertion order to alphabetic order.
  - isArray
```
public boolean isArray()
```
    Easy alternative to 'instanceof' to differentiate JSNode from JSArray (which subclasses JSNode).
    
    Returns:
    
    true if this class is a subclass of JSArray.
    
    See Also:
    
    JSArray.isArray()
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    json string, pretty printed with properties written out in their original case.
  - toString
```
public java.lang.String toString(boolean pretty)
```
    Prints the JSNode with properties written out in their original case.
    
    Parameters:
    
    pretty - should spaces and carriage returns be added to the doc for readability
    
    Returns:
    
    json string, with properties written out in their original case optional pretty printed.
  - toString
```
public java.lang.String toString(boolean pretty,
                                 boolean lowercasePropertyNames)
```
    Prints the JSNode
    
    Parameters:
    
    pretty - should spaces and carriage returns be added to the doc for readability
    
    lowercasePropertyNames - when true all property names are printed in lower case instead of their original case
    
    Returns:
    
    a json string
  - size
```
public int size()
```
    Specified by:
    
    size in interface java.util.Map<java.lang.String,java.lang.Object>
    
    Returns:
    
    the number of properties on this node.
  - isEmpty
```
public boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface java.util.Map<java.lang.String,java.lang.Object>
    
    Returns:
    
    true if size() == 0
  - containsValue
```
public boolean containsValue(java.lang.Object value)
```
    Checks all property values for equality to value
    
    Specified by:
    
    containsValue in interface java.util.Map<java.lang.String,java.lang.Object>
    
    Returns:
    
    true if any property values are equal to value
  - clear
```
public void clear()
```
    Removes all properties
    
    Specified by:
    
    clear in interface java.util.Map<java.lang.String,java.lang.Object>
  - values
```
public java.util.Collection values()
```
    Specified by:
    
    values in interface java.util.Map<java.lang.String,java.lang.Object>
    
    Returns:
    
    a collection of property values
  - entrySet
```
public java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>> entrySet()
```
    Specified by:
    
    entrySet in interface java.util.Map<java.lang.String,java.lang.Object>
    
    Returns:
    
    all property name / value pairs
  - asList
```
public java.util.List asList()
```
    Returns this object as the only element in a list.
    JSArray overrides this method to return all of its elements in a list.
    This method is designed to make it super easy to iterate over all property values or array elements without having to cast or consider differences between JSNode and JSArray.
    For example:
```
 JSNode node = response.getJson();//don't know if this is a JSNode or JSArray
 for(Object value : node.asList())
 {
    //do something;
 }
 
```
    Returns:
    
    A List with this node as the only value.
    
    See Also:
    
    JSArray.asList(), asNodeList()
  - asNodeList
```
public java.util.List<JSNode> asNodeList()
```
    Returns this object as the only element in a List
    JSArray overrides this method to return all of its elements in a list.
    This method is designed to make it super easy to iterate over all property values or array elements without having to cast or consider differences between JSNode and JSArray.
    For example:
```
 JSNode node = response.getJson();//don't know if this is a JSNode or JSArray
 for(JSNode child : node.asList())
 {
    System.out.println("found items with price: " + child.find("**.item.price"));
 }
 
```
    Returns:
    
    A List with this node as the only value.
    
    See Also:
    
    asList()
  - asArray
```
public JSArray asArray()
```
    Similar to #asList() but instead of returning a List, it returns a this JSNode as the only item in a JSArray.
    JSArray overrides this method to simply return 'this'.
    
    Returns:
    
    a JSArray with 'this' as the only element.
    
    See Also:
    
    asList(), asNodeList(), JSArray.asArray()
  - stream
```
public java.util.stream.Stream stream()
```
    Convenience method that calls asList().stream().
    
    Returns:
    
    asList().stream()
  - streamAll
```
public java.util.stream.Stream streamAll()
```
    Returns:
    
    a stream of findAll(**.*) plus "this"

Class JSNode

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Constructor Detail

JSNode

JSNode

JSNode

Method Detail

parseJson

parseJsonNode

parseJsonArray

findAll

diff

patch

get

getNode

getArray

getString

getInt

getLong

getDouble

getBoolean

findNode

findArray

findString

findInt

findLong

findDouble

findBoolean

find

findAll

findAllNodes

put

putAll

putFirst

with

containsKey

remove

removeAll

keySet

hasProperty

asMap

copy

sortKeys

isArray

toString

toString

toString

size

isEmpty

containsValue

clear

values

entrySet

asList

asNodeList

asArray

stream

streamAll