Package org.shredzone.commons.xml

Class XQuery

java.lang.Object

org.shredzone.commons.xml.XQuery

@ParametersAreNonnullByDefault
@Immutable
@ThreadSafe
public class XQuery
extends Object

Helps to easily read content from XML sources.

A main goal of XQuery is to keep XML reading as simple as possible. For this reason, sophisticated XML features like validation or namespaces are not supported.

Performance was not a goal as well. If you need to parse large documents, you better use the old-fashioned Java ways.

Author:

Richard "Shred" Körber

Method Summary

Modifier and Type	Method	Description
String	allText()	Returns the text content of the entire tree that is spawned by this node.
Stream<String>	allValue(String xpath)	Selects values based on the XPath expression that is applied to the tree represented by this XQuery.
Map<String,String>	attr()	Returns a map of attributes.
boolean	exists(String xpath)	Checks if there is at least one element matching the XPath expression.
XQuery	get(String xpath)	Gets a single element based on the XPath expression that is applied to the tree represented by this XQuery.
boolean	isRoot()	Checks if this is a root node.
String	name()	Returns the tag name of this node.
Optional<XQuery>	nextSibling()	Returns the next sibling of this element.
Optional<XQuery>	parent()	Returns the parent node of this node, as XQuery object.
static XQuery	parse(InputStream in)	Parses an XML source and returns an XQuery object representing the root of the document.
static XQuery	parse(Reader r)	Parses an XML source and returns an XQuery object representing the root of the document.
static XQuery	parse(String xml)	Parses an XML source and returns an XQuery object representing the root of the document.
static XQuery	parse(InputSource in)	Parses an XML source and returns an XQuery object representing the root of the document.
Optional<XQuery>	previousSibling()	Returns the previous sibling of this element.
XQuery	root()	Returns the root node of this node, as XQuery object.
Stream<XQuery>	select(String xpath)	Selects elements based on the XPath expression that is applied to the tree represented by this XQuery.
Stream<XQuery>	stream()	Streams all children of this element.
String	text()	Returns the text content of this node.
String	text(String xpath)	Returns the text selected by the XPath expression.
Stream<String>	value(String xpath)	Selects values based on the XPath expression that is applied to the tree represented by this XQuery.

Methods inherited from class java.lang.Object

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

Method Detail

parse

@Nonnull
public static XQuery parse(@WillClose
                           InputSource in)
                    throws IOException

Parses an XML source and returns an XQuery object representing the root of the document.

Parameters:

in - InputSource of the XML document

Returns:

XQuery representing the root of the parsed document

Throws:

IOException - if the XML source could not be read or parsed for any reason

parse

@Nonnull
public static XQuery parse(@WillClose
                           InputStream in)
                    throws IOException

Parses an XML source and returns an XQuery object representing the root of the document.

Parameters:

in - InputStream of the XML document

Returns:

XQuery representing the root of the parsed document

Throws:

IOException - if the XML source could not be read or parsed for any reason

parse

@Nonnull
public static XQuery parse(@WillClose
                           Reader r)
                    throws IOException

Parses an XML source and returns an XQuery object representing the root of the document.

Parameters:

r - Reader providing the XML document

Returns:

XQuery representing the root of the parsed document

Throws:

IOException - if the XML source could not be read or parsed for any reason

parse

@Nonnull
public static XQuery parse(String xml)
                    throws IOException

Parses an XML source and returns an XQuery object representing the root of the document.

Parameters:

xml - String containing the XML document

Returns:

XQuery representing the root of the parsed document

Throws:

IOException - if the XML source could not be read or parsed for any reason

stream

@Nonnull
public Stream<XQuery> stream()

Streams all children of this element. Children elements are represented by XQuery objects as well.

Returns:

Stream of children

nextSibling

@Nonnull
public Optional<XQuery> nextSibling()

Returns the next sibling of this element.

Returns:

Next sibling element

Since:

1.1

previousSibling

@Nonnull
public Optional<XQuery> previousSibling()

Returns the previous sibling of this element.

Returns:

Previous sibling element

Since:

1.1

select

@Nonnull
public Stream<XQuery> select(String xpath)

Selects elements based on the XPath expression that is applied to the tree represented by this XQuery.

Parameters:

xpath - XPath expression

Returns:

Stream of selected nodes as XQuery object

get

@Nonnull
public XQuery get(String xpath)

Gets a single element based on the XPath expression that is applied to the tree represented by this XQuery. Exactly one element is expected to match the XPath expression, otherwise an exception is thrown.

Parameters:

xpath - XPath expression

Returns:

Selected node

Since:

1.1

exists

public boolean exists(String xpath)

Checks if there is at least one element matching the XPath expression.

Parameters:

xpath - XPath expression

Returns:

true if there is at least one element, false if there is none.

Since:

1.1

value

@Nonnull
public Stream<String> value(String xpath)

Selects values based on the XPath expression that is applied to the tree represented by this XQuery.

Parameters:

xpath - XPath expression

Returns:

Stream of strings containing the node values

allValue

@Nonnull
public Stream<String> allValue(String xpath)

Selects values based on the XPath expression that is applied to the tree represented by this XQuery. In contrast to value(String), this method reads the element texts recursively, using allText().

Parameters:

xpath - XPath expression

Returns:

Stream of strings containing the node values

text

@Nonnull
public String text(String xpath)

Returns the text selected by the XPath expression.

Parameters:

xpath - XPath expression

Returns:

Text selected by the expression

name

@Nonnull
public String name()

Returns the tag name of this node.

Returns:

this XQuery node's tag name.

text

@Nonnull
public String text()

Returns the text content of this node.

Returns:

this XQuery node's text content, non recursively.

allText

@Nonnull
public String allText()

Returns the text content of the entire tree that is spawned by this node.

Returns:

this XQuery node's text content, recursively.

attr

@Nonnull
public Map<String,String> attr()

Returns a map of attributes.

Returns:

a map of this node's attributes.

parent

@Nonnull
public Optional<XQuery> parent()

Returns the parent node of this node, as XQuery object. A root node returns an empty optional instead.

Returns:

parent node

isRoot

public boolean isRoot()

Checks if this is a root node.

Returns:

true if this is a root node, false if there's a parent.

Since:

1.1

root

@Nonnull
public XQuery root()

Returns the root node of this node, as XQuery object. A root node returns itself.

Returns:

root node

Since:

1.1