Package com.storedobject.common

Class XML

java.lang.Object

com.storedobject.common.XML

public class XML
extends Object

Simple XML utility for XPath element extraction.

Author:

Syam

Constructor Summary

Constructors

Constructor	Description
XML()	XML represents an XML document and provides various methods for manipulating and extracting information from the XML structure.
XML(InputStream stream)	Creates a new XML object by setting the contents of the XML from the given input stream.
XML(Reader reader)	Constructs an XML object using the provided Reader.
XML(String xml)	Represents an XML document.
XML(URL url)	XML class represents an XML document.
XML(Document document)	XML constructor with a Document object that represents the XML structure.

Method Summary

Modifier and Type	Method	Description
boolean	check(String xpath)	Extract the boolean value of a path.
boolean	check(Node node, String xpath)	Extract the boolean value of a path.
XML	copy()	Creates a new XML object with the same content as the current object.
protected void	customizeBuilder(DocumentBuilder documentBuilder)	Customizes the DocumentBuilder by providing additional configuration options.
protected void	customizeBuilderFactory(DocumentBuilderFactory documentBuilderFactory)	Customize the DocumentBuilderFactory before creating a new DocumentBuilder instance.
protected void	customizePathFactory(XPathFactory pathFactory)	Customize the XPathFactory used by the XML class.
String	get(String xpath)	Deprecated. Use getText(String) instead.
String	get(Node node, String xpath)	Deprecated. Use getText(Node, String) instead.
Document	getDocument()	Retrieves the document.
String	getNamespacePrefix(String uri)	Returns the namespace prefix associated with the given URI.
String	getNamespaceURI(String prefix)	Retrieves the namespace URI associated with the given prefix.
Node	getNode(String xpath)	Retrieves the Node object corresponding to the given XPath expression.
Node	getNode(Node node, String xpath)	Retrieves the specific node based on the given XPath expression.
Number	getNumber(String xpath)	Extract the numeric value of a path.
Number	getNumber(Node node, String xpath)	Extract the numeric value of a path under a given node.
String	getText(String xpath)	Extract the text value of a path.
String	getText(Node node, String xpath)	Extract the text value of a path under a given node.
void	ignoreDTDs()	Sets the entity resolver of the document builder to ignore DTDs.
ArrayList<String>	list(String xpath)	Returns a list of strings matching the given XPath expression.
ArrayList<String>	list(Node node, String xpath)	Returns a list of string values from the given XML node using the specified XPath.
ArrayList<Node>	listNodes(String xpath)	Retrieves a list of nodes from the XML document that match a given XPath expression.
ArrayList<Node>	listNodes(Node node, String xpath)	Returns a list of nodes matching the given XPath expression within the given node.
void	set(InputStream stream)	Sets the input stream.
void	set(Reader reader)	Sets the XML document using the provided Reader object.
void	set(String xml)	Sets the value of the object using the provided XML representation.
void	set(URL url)	Sets the input stream using the given URL.
void	set(Document document)	Sets the Document object representing the XML structure.
void	setNamespacePrefix(String prefix)	Sets the namespace prefix for the XML document.
void	setPack(boolean pack)	Whether to pack the XML structure by removing all the unwanted text nodes or not.
boolean	setText(String xpathToNode, String value)	Set a text value to the given node if it is a "text node".
boolean	setText(Node node, String value)	Set a text value to the given node if it is a "text node".
String	toPrettyString()	Converts the document to a formatted string representation.
String	toPrettyString(Node node)	Converts the given XML Node to a pretty formatted XML string.
String	toString()	Returns a string representation of the current object.
String	toString(Node node)	Converts a Node object to its string representation.
void	write(OutputStream stream)	Writes the content of the document to the specified output stream.
void	write(Writer writer)	Write the document to the given writer.
void	write(Node node, OutputStream stream)	Writes the given XML node to the specified output stream.
void	write(Node node, Writer writer)	Write the XML content of a given Node to a Writer.

Methods inherited from class java.lang.Object

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

Constructor Details

XML

public XML()

XML represents an XML document and provides various methods for manipulating and extracting information from the XML structure.

XML

public XML(String xml)
    throws Exception

Represents an XML document.

Parameters:

xml - The XML as a string.

Throws:

Exception - If an error occurs.

XML

public XML(InputStream stream)
    throws Exception

Creates a new XML object by setting the contents of the XML from the given input stream.

Parameters:

stream - The input stream containing the XML content.

Throws:

Exception - If any exception occurs.

XML

public XML(Reader reader)
    throws Exception

Constructs an XML object using the provided Reader.

Parameters:

reader - The Reader object to read XML from.

Throws:

Exception - If any error occurs during the XML parsing.

XML

public XML(URL url)
    throws Exception

XML class represents an XML document.

Throws:

Exception

XML

public XML(Document document)
    throws Exception

XML constructor with a Document object that represents the XML structure.

Parameters:

document - The Document object representing the XML structure.

Throws:

Exception - If any error occurs.

Method Details

customizeBuilderFactory

protected void customizeBuilderFactory(DocumentBuilderFactory documentBuilderFactory)

Customize the DocumentBuilderFactory before creating a new DocumentBuilder instance.

Parameters:

documentBuilderFactory - The DocumentBuilderFactory to customize.

customizeBuilder

protected void customizeBuilder(DocumentBuilder documentBuilder)

Customizes the DocumentBuilder by providing additional configuration options.

Parameters:

documentBuilder - The DocumentBuilder to customize.

customizePathFactory

protected void customizePathFactory(XPathFactory pathFactory)

Customize the XPathFactory used by the XML class.

Parameters:

pathFactory - The XPathFactory to customize.

setPack

public void setPack(boolean pack)

Whether to pack the XML structure by removing all the unwanted text nodes or not. The default value is true. Packing reduces human readability.

Parameters:

pack - True/false.

ignoreDTDs

public void ignoreDTDs()

Sets the entity resolver of the document builder to ignore DTDs. This is useful when working with XML documents that reference DTDs, but you want to ignore them during parsing.

copy

public XML copy()
         throws Exception

Creates a new XML object with the same content as the current object.

Returns:

The new XML object.

Throws:

Exception - If an error occurs.

set

public void set(Document document)
         throws Exception

Sets the Document object representing the XML structure.

Parameters:

document - The Document object representing the XML structure.

Throws:

Exception - If any error occurs.

set

public void set(String xml)
         throws Exception

Sets the value of the object using the provided XML representation.

Parameters:

xml - the XML representation of the object

Throws:

Exception - if an error occurs during the XML parsing or object setting process

set

public void set(InputStream stream)
         throws Exception

Sets the input stream.

Parameters:

stream - The input stream to set.

Throws:

Exception - If an error occurs.

set

public void set(Reader reader)
         throws Exception

Sets the XML document using the provided Reader object.

Parameters:

reader - The Reader object to read XML from.

Throws:

Exception - If any error occurs during the XML parsing.

setNamespacePrefix

public void setNamespacePrefix(String prefix)

Sets the namespace prefix for the XML document.

Parameters:

prefix - The desired namespace prefix. If null, the default namespace prefix will be used.

getNamespacePrefix

public String getNamespacePrefix(String uri)

Returns the namespace prefix associated with the given URI.

Parameters:

uri - The URI to get the prefix for.

Returns:

The namespace prefix for the given URI, or null if not found.

getNamespaceURI

public String getNamespaceURI(String prefix)

Retrieves the namespace URI associated with the given prefix.

Parameters:

prefix - The prefix to retrieve the namespace URI for.

Returns:

The namespace URI for the given prefix.

set

public void set(URL url)
         throws Exception

Sets the input stream using the given URL.

Parameters:

url - the URL to set the input stream from

Throws:

Exception - if an error occurs while setting the input stream

list

public ArrayList<String> list(String xpath)
                       throws Exception

Returns a list of strings matching the given XPath expression.

Parameters:

xpath - the XPath expression to evaluate

Returns:

an ArrayList of strings that match the given XPath expression

Throws:

Exception - if an error occurs while evaluating the XPath expression

listNodes

public ArrayList<Node> listNodes(String xpath)
                          throws Exception

Retrieves a list of nodes from the XML document that match a given XPath expression.

Parameters:

xpath - The XPath expression to match nodes in the XML document.

Returns:

An ArrayList of nodes that match the given XPath expression.

Throws:

Exception - If an error occurs while retrieving the nodes.

getNode

public Node getNode(String xpath)
             throws Exception

Retrieves the Node object corresponding to the given XPath expression.

Parameters:

xpath - the XPath expression to search for the Node object

Returns:

the Node object matching the XPath expression

Throws:

Exception - if there is an error while retrieving the Node object

check

public boolean check(String xpath)
              throws Exception

Extract the boolean value of a path.

Parameters:

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

get

@Deprecated
public String get(String xpath)
           throws Exception

Deprecated.

Use getText(String) instead.

Extract the text value of a path.

Parameters:

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

getText

public String getText(String xpath)
               throws Exception

Extract the text value of a path.

Parameters:

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

getNumber

public Number getNumber(String xpath)
                 throws Exception

Extract the numeric value of a path.

Parameters:

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

check

public boolean check(Node node,
 String xpath)
              throws Exception

Extract the boolean value of a path.

Parameters:

node - Node.

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

setText

public boolean setText(String xpathToNode,
 String value)

Set a text value to the given node if it is a "text node". If the node is not a "text node", the value will be set to its first child if that is a "text node". Else, it will recursively go down until a "text node" is found. Please note that the recursive traversal happens only through the first children.

Parameters:

xpathToNode - XPath's expression to reach the node.

value - Value to set.

Returns:

True if the value was successfully set. Otherwise, false.

setText

public boolean setText(Node node,
 String value)

Set a text value to the given node if it is a "text node". If the node is not a "text node", the value will be set to its first child if that is a "text node". Else, it will recursively go down until a "text node" is found. Please note that the recursive traversal happens only through the first children.

Parameters:

node - Node for which value to be set.

value - Value to set.

Returns:

True if the value was successfully set. Otherwise, false.

get

@Deprecated
public String get(Node node,
 String xpath)
           throws Exception

Deprecated.

Use getText(Node, String) instead.

Extract the text value of a path under a given node.

Parameters:

node - Node.

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

getText

public String getText(Node node,
 String xpath)
               throws Exception

Extract the text value of a path under a given node.

Parameters:

node - Node.

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

getNumber

public Number getNumber(Node node,
 String xpath)
                 throws Exception

Extract the numeric value of a path under a given node.

Parameters:

node - Node.

xpath - XPath.

Returns:

Value.

Throws:

Exception - If any error occurs.

list

public ArrayList<String> list(Node node,
 String xpath)
                       throws Exception

Returns a list of string values from the given XML node using the specified XPath.

Parameters:

node - The XML node to extract values from.

xpath - The XPath expression to be evaluated.

Returns:

An ArrayList of string values that match the given XPath expression.

Throws:

Exception - If an error occurs during the XML parsing or XPath evaluation.

listNodes

public ArrayList<Node> listNodes(Node node,
 String xpath)
                          throws Exception

Returns a list of nodes matching the given XPath expression within the given node.

Parameters:

node - The node to search within.

xpath - The XPath expression to match nodes.

Returns:

A list of nodes matching the XPath expression.

Throws:

Exception - if an error occurs during the evaluation of the XPath expression.

getNode

public Node getNode(Node node,
 String xpath)
             throws Exception

Retrieves the specific node based on the given XPath expression.

Parameters:

node - The starting node from which to search for the target node.

xpath - The XPath expression used to locate the target node.

Returns:

The target node if found, otherwise null.

Throws:

Exception - if an error occurs during the evaluation of the XPath expression.

toPrettyString

public String toPrettyString()

Converts the document to a formatted string representation.

Returns:

A string representing the document in a pretty format.

toPrettyString

public String toPrettyString(Node node)

Converts the given XML Node to a pretty formatted XML string.

Parameters:

node - the XML Node to be converted

Returns:

a pretty formatted XML string representation of the given Node

toString

public String toString()

Returns a string representation of the current object.

Overrides:

toString in class Object

Returns:

the string representation of the current object.

toString

public String toString(Node node)

Converts a Node object to its string representation.

Parameters:

node - the Node object to convert

Returns:

the string representation of the Node object, or "ERROR" in case of an exception

write

public void write(OutputStream stream)
           throws Exception

Writes the content of the document to the specified output stream.

Parameters:

stream - the output stream to write the content to

Throws:

Exception - if an error occurs while writing the content

write

public void write(Writer writer)
           throws Exception

Write the document to the given writer.

Parameters:

writer - the writer to write the document to

Throws:

Exception - if an error occurs while writing the document

write

public void write(Node node,
 OutputStream stream)
           throws Exception

Writes the given XML node to the specified output stream.

Parameters:

node - the XML node to be written

stream - the output stream to write the XML to

Throws:

Exception - if an error occurs during the writing process

write

public void write(Node node,
 Writer writer)
           throws Exception

Write the XML content of a given Node to a Writer.

Parameters:

node - the Node containing the XML content

writer - the Writer to write the XML content to

Throws:

Exception - if an error occurs while writing the XML content

getDocument

public Document getDocument()

Retrieves the document.

Returns:

The document object.