public class Path
extends java.lang.Object
Provides an object path navigation class to return the value for the given
expression. This class will automatically select the appropriate path navigation
library for the given source object which may be JSON text, XML text, XML
document or Java POJO (Plain Old Java Object). Path Sources The supported
Path
sources can be constructed by JSON text, XML text, XML
document or Java POJO.
Expressions
Here is a complete overview and a side by side comparison of the JSONPath syntax
elements with its XPath counterparts.
XPath |
JSONPath |
Description |
/ |
$ |
the root object/element |
. |
@ |
the current object/element |
/ |
. or [] |
child operator |
.. |
n/a |
parent operator |
// |
.. |
recursive descent. JSONPath borrows this syntax from E4X. |
* |
* |
wildcard. All objects/elements regardless their names. |
@ |
n/a |
attribute access. JSON structures don't have attributes. |
[] |
[] |
subscript operator. XPath uses it to iterate over element collections
and for predicates. In Javascript and JSON it is the native array
operator.
|
| |
[,] |
Union operator in XPath results in a combination of node sets. JSONPath
allows alternate names or array indices as a set.
|
n/a |
[start:end:step] |
array slice operator borrowed from ES4. |
[] |
?() |
applies a filter (script) expression. |
n/a |
() |
script expression, using the underlying script engine. |
() |
n/a |
grouping in Xpath |
JSON Sources
With JSON sources the expression language used is JSONPath. When using the
val(exp)
method this class will return the text content value for
the first selected node, or null if no node was found. The expression operators
include $(root node of the structure), @ (current node that is being processed,
e.g. "user[?(@.firstName==John)]") and * (wildcard indicating all elements in
scope, e.g. user[*]). See JayWay JSONPath Library Guide for more documentation.
Object Sources
With Object sources the expression language used is "property names", e.g.
"user.firstName". When using the val(exp)
method this class will
return the text content value for the first selected node, or null if no node
was found.
XML Sources
Note that the implementation is namespace aware but ignores default namespace's
override. Examples
JSON Examples
This Groovy example creates Path from JSON string, and then reads out a value
from path.
import com.avoka.tm.util.Path
String json =
'''{
"address": {
"line1": "1 Street",
"postCode": 2000
}
}'''
Path path = new Path(json)
def line1 = path.val('address.line1')
def postCode = path.val('$.[\'address\'].[\'postCode\']')
Note you have the full power of JSON Path so you can perform like:
def addressNodeFiltered = path.val("address[?(@.postCode == 2000)]")
def allAddressChildrenValuesList = path.val("address[*]")
Java Object Examples
This Groovy example creates Path from Object, and then reads out a value from
path.
import com.avoka.tm.util.Path
User user = new User()
user.setFirstName("George")
ContactDetails cd = new ContactDetails()
cd.setEmail("george@email.com")
user.setContactDetails(cd)
Address address = new Address()
address.setCity("Sydney")
address.setPostCode(2153)
user.getAddressList().add(address)
Path path = new Path(user)
def userFirstName = path.val("firstName")
def userEmail = path.val("contactDetails.email")
def postCode = path.val("addressList[0].postCode")
XML Examples
This Groovy example creates Path from XML string, and then reads out a value
from path.
import com.avoka.tm.util.Path
// source - XML text
String formXml =
'''<AvokaSmartForm>
<YourDetails>
<FirstName> ... </FirstName>
<LastName> ... </LastName>
<Email> ... </Email>
</YourDetails>
</AvokaSmartForm>'''
Path path = new Path(formXml)
def userFirstName = path.val("//FirstName")
def userEmail = path.val("/AvokaSmartForm/YourDetails/Email")
// schemaSeed - XML Document source
Path path2 = new Path(schemaSeed)
def userEmail = path2.val("//Email")
Note you have the full power of XQuery so you can perform XQuerys like:
def countryList = path.val("//root/country[@value='USA']")
The Path class also provides a nodes()
method which will return a
typed List of XML Nodes which can be iterated over. In contrast the Path
val()
method will return the text content of the first selected XML
Node.
import com.avoka.tm.util.Path
import org.w3c.dom.Node
def xml =
'''<bar>
<drink type="Beer"> 4 Pines </drink>
<drink type="Beer"> Coopers </drink>
<drink type="Wine"> Cab Sav </drink>
</bar>'''
// Select first value
Path path = new Path(xml)
def firstDrink = path.val('//drink')
println 'firstDrink value: ' + firstDrink + ', type: ' + firstDrink.class.simpleName
// Select node list
List<Node> drinks = path.nodes('//drink')
for (drink in drinks) {
println 'textContent: ' + drink.textContent + ', type: ' + drink.class.simpleName + ', toString: ' + drink
}
Script output results:
firstDrink value: 4 Pines, type: String
textContent: 4 Pines, type: DeferredElementImpl, toString: <?xml version="1.0" encoding="UTF-8"?> <drink type="Beer">4 Pines</drink>
textContent: Coopers, type: DeferredElementImpl, toString: <?xml version="1.0" encoding="UTF-8"?> <drink type="Beer">Coopers</drink>
textContent: Cab Sav, type: DeferredElementImpl, toString: <?xml version="1.0" encoding="UTF-8"?> <drink type="Wine">Cab Sav</drink>
- Since:
- 5.0.0
Constructor Summary
Constructors
Constructor |
Description |
Path(java.lang.Object source) |
Create a path evaluation object with the given source.
|
Method Summary
All Methods Instance Methods Concrete Methods
Modifier and Type |
Method |
Description |
Path |
firstPath(java.lang.String path) |
Return the first path object for the given expression, or null if not
resolved.
|
java.util.List<org.w3c.dom.Node> |
nodes(java.lang.String path) |
Return the list of XML Node values for the given expression.
|
java.util.List<Path> |
paths(java.lang.String path) |
Return the list of paths for the given expression.
|
java.lang.Object |
val(java.lang.String path) |
Return the value for the given expression.
|
java.util.List<java.lang.Object> |
vals(java.lang.String path) |
Return the list of values for the given expression.
|
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString,
wait, wait, wait
Constructor Detail
Path
public Path(java.lang.Object source)
Create a path evaluation object with the given source.
- Parameters:
source
- the source
Method Detail
val
public java.lang.Object val(java.lang.String path)
Return the value for the given expression. With XML sources the expression
language used is XPath. When using the val(exp)
method this class
will return the text content value for the first selected node, or null if no
node was found.
- Parameters:
path
- the path expression to evaluate (required)
- Returns:
-
value for the path expression, otherwise
null
if path is
invalid or can not be found.
vals
public java.util.List<java.lang.Object> vals(java.lang.String path)
Return the list of values for the given expression. With an XML source the
expression language used is XPath. When using the vals(exp)
method
this class will return the text content value for the list of selected nodes, or
an empty list if not found.
- Parameters:
path
- the path expression to evaluate (required)
- Returns:
-
the list of values for the given expression, otherwise empty
List
if can not be found.
nodes
public java.util.List<org.w3c.dom.Node> nodes(java.lang.String path)
Return the list of XML Node values for the given expression. This method will
throw an UnsupportedOperationException if the Path source is not an XML source.
- Parameters:
path
- the path expression to evaluate (required)
- Returns:
- the list of DOM Node values for the given the path expression
paths
public java.util.List<Path> paths(java.lang.String path)
Return the list of paths for the given expression.
- Parameters:
path
- the path expression to evaluate (required)
- Returns:
- the list of values for the given expression.
firstPath
public Path firstPath(java.lang.String path)
Return the first path object for the given expression, or null if not resolved.
- Parameters:
path
- the path expression to evaluate (required)
- Returns:
-
the first path object for the given expression, or null if not resolved.
- Since:
- 18.11.0