Package com.mycila.xmltool
Interface XMLTag
- All Known Implementing Classes:
XMLDoc
public interface XMLTag
Enables you to build, parse, navigate, modify XML documents through a simple and intuitive fluent interface.
XMLTag
is not thread-safe and cannot be considered so, even for non mutating methods.
This is due to the current location which needs to be kept, as we work in a fluent interface style.-
Method Summary
Modifier and TypeMethodDescriptionaddAttribute
(String name, String value) Create a new attribute for the current nodeaddAttribute
(Attr attr) Add given attribute to current elementAdd a data node under the current node, and jump to the parent node.addCDATA
(CDATASection data) Add a CDATA note to the current tagaddDocument
(XMLTag tag) Inserts anotherXMLTag
instance under the current tag.addDocument
(Document doc) Inserts anotherDocument
instance under the current tagaddNamespace
(String prefix, String namespaceURI) Add a namespace to the documentInserts anotherXMLTag
tag hierarchy under the current tag.Create a tag under the current location and use it as the current nodeInserts aElement
instance and its hierarchy under the current tagAdd a text node under the current node, and jump to the parent node.Add a text note to the current tagdelete()
Delete current tag and its childs.deleteAttribute
(String name) Delete an attribute of the current node.Delete an attribute of the current node, if it existsDelete all existing attributes of current nodeDelete all existing elements of this nodeRemove any prefix and namespaces contained in the tag name, childs and attributes, thus changing namespace and tag name.findAttribute
(String name) returns the attribute value of the current node or null if the attribute does not existfindAttribute
(String name, String relativeXpath, Object... arguments) Returns the attribute value of the node pointed by given XPath expression or null if the attribute does not existExecute an action for each selected tags from the current node.forEachChild
(CallBack callBack) Execute an action for each child in the current node.getAttribute
(String name) returns the attribute value of the current nodegetAttribute
(String name, String relativeXpath, Object... arguments) Returns the attribute value of the node pointed by given XPath expressionString[]
getCDATA()
Get the CDATA of a selected nodegetCDATAorText
(String relativeXpath, Object... arguments) Get the text of a sepcific nodeint
XMLTag tag = XMLDoc.newDocument(true) .addRoot("root").addTag("a") .gotoParent().addTag("b") .gotoParent().addTag("c") .gotoRoot(); assertEquals(tag.getCurrentTagName(), "root"); for (XMLTag xmlTag : tag.getChilds()) { if(xmlTag.getCurrentTagName().equals("b")) { break; } } assertEquals(tag.getCurrentTagName(), "b");
Create an iterable object over selected elements.Get the prefix of a namespaceString[]
getPefixes
(String namespaceURI) Get all bound prefixes of a namespacegetText()
Get the text of a sepcific nodegetTextOrCDATA
(String relativeXpath, Object... arguments) Get the text of a sepcific nodeGo to the only child element of the curent node.gotoChild
(int i) Go to the Nth child of the curent node.Go to the child found with given node nameGo to the first child element of the curent node.gotoFirstChild
(String name) Go to the first child occurance found having given nameGo to the lastest child element of the curent node.gotoLastChild
(String name) Go to the last child occurance found having given nameGo to parent tag.gotoRoot()
Go to document root tagGo to a specific nodeboolean
hasAttribute
(String name) Check wheter current tag contains an atributeboolean
hasAttribute
(String name, String relativeXpath, Object... arguments) Check if targeted tag has an attribute of given nameboolean
Check if a tag exist in the documentrawXpathBoolean
(String relativeXpath, Object... arguments) Execute an XPath expression directly using the Java XPath API, from the current node.rawXpathNode
(String relativeXpath, Object... arguments) Execute an XPath expression directly using the Java XPath API, from the current node.rawXpathNodeSet
(String relativeXpath, Object... arguments) Execute an XPath expression directly using the Java XPath API, from the current node.rawXpathNumber
(String relativeXpath, Object... arguments) Execute an XPath expression directly using the Java XPath API, from the current node.rawXpathString
(String relativeXpath, Object... arguments) Execute an XPath expression directly using the Java XPath API, from the current node.Replace current element name by another namesetAttribute
(String name, String value) Sets the new value on an existign attribute, and remains on the current tag.setAttribute
(String name, String value, String relativeXpath, Object... arguments) Sets the new value on a targetted node's attribute, and remains on the current tag.setAttributeIfExist
(String name, String value) Sets the new value on an attribute, and remains on the current tag.setAttributeIfExist
(String name, String value, String relativeXpath, Object... arguments) Sets the new value on a targetted node's attribute, and remains on the current tag.Set the cdata in the current node.Set the cdata in the targetted node.setCDATAIfExist
(String data, String relativeXpath, Object... arguments) Set the cdata in the targetted node.Set the text in the current node.Set the text in the targetted node.setTextIfExist
(String text, String relativeXpath, Object... arguments) Set the text in the targetted node.byte[]
toBytes()
byte[]
toOutputStream
(String encoding) toResult()
Converts this document to the result providedConverts this document to the result provided, overriding default encoding of xml documenttoSource()
toStream
(OutputStream out) Write this document to a streamtoStream
(OutputStream out, String encoding) Write this document to a streamWrite this document to a streamWrite this document to a streamtoString()
toWriter()
Validate this document against specifief schemasValidate this document against specifief schemas
-
Method Details
-
addNamespace
Add a namespace to the document- Parameters:
prefix
- The prefix of the namespacenamespaceURI
- The URI of the namespace- Returns:
- this
-
addTag
Create a tag under the current location and use it as the current node- Parameters:
name
- Name of the element to add- Returns:
- this
-
addAttribute
Create a new attribute for the current node- Parameters:
name
- Name of the attribute to addvalue
- value of the attribute to add- Returns:
- this
-
addText
Add a text node under the current node, and jump to the parent node. This enables the create or quick documents like this:addTag("name").addText("Bob")addTag("sex").addText("M")addTag("age").addText("30")
<name>Bob</name><sex>M</sex><age>30</age>
- Parameters:
text
- the text to add- Returns:
- this
-
addCDATA
Add a data node under the current node, and jump to the parent node. This enables the create or quick documents like this:addTag("name").addCDATA("Bob")addTag("sex").addCDATA("M")addTag("age").addCDATA("30")
<name><![CDATA[Bob]]></name><sex><![CDATA[M]]></sex><age><![CDATA[30]]></age>
- Parameters:
data
- the data to add- Returns:
- this
-
addDocument
Inserts anotherXMLTag
instance under the current tag. The whole document will be inserted.- Parameters:
tag
- TheXMLTag
instance to insert- Returns:
- this
-
addDocument
Inserts anotherDocument
instance under the current tag- Parameters:
doc
- TheDocument
instance to insert- Returns:
- this
-
addTag
Inserts anotherXMLTag
tag hierarchy under the current tag. Only the current tag of the given document will be inserted with its hierarchy, not the whole document.- Parameters:
tag
- TheXMLTag
current tag hierarchy to insert- Returns:
- this
-
addTag
Inserts aElement
instance and its hierarchy under the current tag- Parameters:
tag
- TheElement
instance to insert- Returns:
- this
-
addAttribute
Add given attribute to current element- Parameters:
attr
- The attribute to insert- Returns:
- this
-
addText
Add a text note to the current tag- Parameters:
text
- The node to insert- Returns:
- this
-
addCDATA
Add a CDATA note to the current tag- Parameters:
data
- The node to insert- Returns:
- this
-
gotoParent
XMLTag gotoParent()Go to parent tag. Do nothing if we are already at root- Returns:
- this
-
gotoRoot
XMLTag gotoRoot()Go to document root tag- Returns:
- this
-
gotoTag
Go to a specific node- Parameters:
relativeXpath
- XPath expresionarguments
- to be replaced in xpath expression before compiling. Uses String.format() to build XPath expression.- Returns:
- this
- Throws:
XMLDocumentException
- if the node does not exist or if the XPath expression is invalid
-
gotoChild
Go to the only child element of the curent node.- Returns:
- this
- Throws:
XMLDocumentException
- If the current node has several childs or no child at all
-
gotoChild
Go to the Nth child of the curent node.- Parameters:
i
- index of the child, from 1 to child element number- Returns:
- this
- Throws:
XMLDocumentException
- If the child node does not exist
-
gotoChild
Go to the child found with given node name- Parameters:
nodeName
- name of the child to find.- Returns:
- this
- Throws:
XMLDocumentException
- If the element with this name has not been found or if there are too many elements
-
gotoFirstChild
Go to the first child element of the curent node.- Returns:
- this
- Throws:
XMLDocumentException
- If the current node has no child at all
-
gotoFirstChild
Go to the first child occurance found having given name- Parameters:
name
- Name of the child to go at- Returns:
- this
- Throws:
XMLDocumentException
- If the current node has no child at all
-
gotoLastChild
Go to the lastest child element of the curent node.- Returns:
- this
- Throws:
XMLDocumentException
- If the current node has no child at all
-
gotoLastChild
Go to the last child occurance found having given name- Parameters:
name
- Name of the child to go at- Returns:
- this
- Throws:
XMLDocumentException
- If the current node has no child at all
-
hasTag
Check if a tag exist in the document- Parameters:
relativeXpath
- XPath expression where the tag should be locatedarguments
- XPath arguments. Uses String.format() to build XPath expression.- Returns:
- true if the tag is exist
-
hasAttribute
boolean hasAttribute(String name, String relativeXpath, Object... arguments) throws XMLDocumentException Check if targeted tag has an attribute of given name- Parameters:
name
- the name of the attributerelativeXpath
- XPath that target the tagarguments
- optional arguments of xpath expression. Uses String.format() to build XPath expression.- Returns:
- true if the tag exist with this attribute name
- Throws:
XMLDocumentException
- If the targetted node does not exist or if xpath expression is not valid
-
hasAttribute
Check wheter current tag contains an atribute- Parameters:
name
- Attribute name- Returns:
- true if the attribute is in current tag
-
forEachChild
Execute an action for each child in the current node.- Parameters:
callBack
- Callback method to run after the current tag of the document has changed to a child- Returns:
- this
-
forEach
Execute an action for each selected tags from the current node.- Parameters:
callBack
- Callback method to run after the current tag of the document has changed to a childrelativeXpath
- XXath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- this
-
forEach
-
rawXpathString
Execute an XPath expression directly using the Java XPath API, from the current node.- Parameters:
relativeXpath
- The XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The
XPathConstants.STRING
return type
-
rawXpathNumber
Execute an XPath expression directly using the Java XPath API, from the current node.- Parameters:
relativeXpath
- The XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The
XPathConstants.NUMBER
return type
-
rawXpathBoolean
Execute an XPath expression directly using the Java XPath API, from the current node.- Parameters:
relativeXpath
- The XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The
XPathConstants.BOOLEAN
return type
-
rawXpathNode
Execute an XPath expression directly using the Java XPath API, from the current node.- Parameters:
relativeXpath
- The XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The
XPathConstants.NODE
return type
-
rawXpathNodeSet
Execute an XPath expression directly using the Java XPath API, from the current node.- Parameters:
relativeXpath
- The XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The
XPathConstants.NODESET
return type
-
getCurrentTag
Element getCurrentTag()- Returns:
- the current tag
-
getChildCount
int getChildCount()- Returns:
- The number of child for the current tag
-
getChilds
XMLTag tag = XMLDoc.newDocument(true) .addRoot("root").addTag("a") .gotoParent().addTag("b") .gotoParent().addTag("c") .gotoRoot(); assertEquals(tag.getCurrentTagName(), "root"); for (XMLTag xmlTag : tag.getChilds()) { if(xmlTag.getCurrentTagName().equals("b")) { break; } } assertEquals(tag.getCurrentTagName(), "b");
XMLTag tag = XMLDoc.newDocument(true) .addRoot("root").addTag("a") .gotoParent().addTag("b") .gotoParent().addTag("c") .gotoRoot(); assertEquals(tag.getCurrentTagName(), "root"); for (XMLTag xmlTag : tag.getChilds()) { System.out.println(xmlTag.getCurrentTagName()); } assertEquals(tag.getCurrentTagName(), "root");
- Returns:
- An iterable object over childs
-
getChilds
Create an iterable object over selected elements. Act as the getChilds method: The current position of XMLTag is modified at each iteration. Thus, if you break in the iteration, the current position will not be the same as the position before.- Parameters:
relativeXpath
- XPath to select tagsarguments
- XPath arguments- Returns:
- The iterable object
-
getChildElement
- Returns:
- The child element's list
-
getCurrentTagName
String getCurrentTagName()- Returns:
- the current tag name
-
getCurrentTagLocation
String getCurrentTagLocation()- Returns:
- An XPath expression representing the current tag location in the document. If you are in the root node and run gotoTag() giving this XPath expression, you will return to the current node.
-
getContext
NamespaceContext getContext()- Returns:
- the namespace context
-
getPefix
Get the prefix of a namespace- Parameters:
namespaceURI
- The URI of the namespace- Returns:
- the prefix or "" if not found ("" is the default prefix - see
javadoc
)
-
getPefixes
Get all bound prefixes of a namespace- Parameters:
namespaceURI
- The URI of the namespace- Returns:
- a list of prefixes or an empty array.
-
getText
String getText()- Returns:
- The text content of the current node, "" if none
-
getText
Get the text of a sepcific node- Parameters:
relativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- the text of "" if none
- Throws:
XMLDocumentException
- If the XPath expression is not valid or if the node does not exist
-
getCDATA
String getCDATA()- Returns:
- The CDATA content of the current node, "" if none
-
getCDATA
Get the CDATA of a selected node- Parameters:
relativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- the text of "" if none
- Throws:
XMLDocumentException
- If the XPath expression is invalid or if the node does not exist
-
getTextOrCDATA
String getTextOrCDATA()- Returns:
- The text content of the current node, if none tries to get the CDATA content, if none returns ""
-
getTextOrCDATA
Get the text of a sepcific node- Parameters:
relativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The text content of the current node, if none tries to get the CDATA content, if none returns ""
- Throws:
XMLDocumentException
- If the XPath expression is not valid or if the node does not exist
-
getCDATAorText
String getCDATAorText()- Returns:
- The CDATA content of the current node, if none tries to get the text content, if none returns ""
-
getCDATAorText
Get the text of a sepcific node- Parameters:
relativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- The CDATA content of the current node, if none tries to get the text content, if none returns ""
- Throws:
XMLDocumentException
- If the XPath expression is not valid or if the node does not exist
-
getAttributeNames
String[] getAttributeNames()- Returns:
- all attribute names of current node
-
getAttribute
returns the attribute value of the current node- Parameters:
name
- attribute name- Returns:
- attribute value
- Throws:
XMLDocumentException
- If the attribute does not exist
-
getAttribute
String getAttribute(String name, String relativeXpath, Object... arguments) throws XMLDocumentException Returns the attribute value of the node pointed by given XPath expression- Parameters:
name
- attribute namerelativeXpath
- XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- attribute value
- Throws:
XMLDocumentException
- Attribute does not exist, targetted node or XPath expression is invalid
-
findAttribute
returns the attribute value of the current node or null if the attribute does not exist- Parameters:
name
- attribute name- Returns:
- attribute value or null if no attribute
-
findAttribute
String findAttribute(String name, String relativeXpath, Object... arguments) throws XMLDocumentException Returns the attribute value of the node pointed by given XPath expression or null if the attribute does not exist- Parameters:
name
- attribute namerelativeXpath
- XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- the attribute value or null if the attribute does not exist
- Throws:
XMLDocumentException
- targetted node does not exist or XPath expression is invalid
-
getInnerDocument
XMLTag getInnerDocument()- Returns:
- Another XMLTag instance in which the current tag becomes de root element of the new document, and it contains all inner elements as in the previous document.
-
getInnerText
String getInnerText()- Returns:
- The text representation of the inner nodes of the current node. The current node is outputed as the root element of inner tags.
-
duplicate
XMLTag duplicate()- Returns:
- A new com.mycila.xmltool.XMLTag instance having the same properties and documents of the current instance. The current tag will also remain the same (this.getCurrentTagName().equals(this.duplicate().getCurrentTagName()))
-
setText
Set the text in the current node. This method will replace all existing text and cdata by the given text. Also Jump after to the parent node. This enables the quicly replace test on several nodes like this:gotoChild("name").setText("Bob").gotoChild("sex").setText("M").gotoChild("age").setText("30")
<name>Bob</name><sex>M</sex><age>30</age>
- Parameters:
text
- text to put under this node- Returns:
- this
-
setText
Set the text in the targetted node. This method will replace all existing text and cdata by the given text, but remains on the current tag.- Parameters:
text
- text to put under this noderelativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- this
- Throws:
XMLDocumentException
- If the XPath expression is invalid or if the node does not exist
-
setTextIfExist
XMLTag setTextIfExist(String text, String relativeXpath, Object... arguments) throws XMLDocumentException Set the text in the targetted node. This method will replace all existing text and cdata by the given text, but remains on the current tag. If the targetted node does not exist, do nothing.- Parameters:
text
- text to put under this noderelativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- this
- Throws:
XMLDocumentException
- If the XPath expression is invalid
-
setCDATA
Set the cdata in the current node. This method will replace all existing text and cdata by the given cdata Also Jump after to the parent node. This enables the quicly replace test on several nodes like this:gotoChild("name").setText("Bob").gotoChild("sex").setText("M").gotoChild("age").setText("30")
<name>Bob</name><sex>M</sex><age>30</age>
- Parameters:
data
- text to put under this node in a cdata section- Returns:
- this
-
setCDATA
Set the cdata in the targetted node. This method will replace all existing text and cdata by the given cdata, but remains on the current tag.- Parameters:
data
- text to put under this node in a cdata sectionrelativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- this
- Throws:
XMLDocumentException
- If the XPath expression is invalid or if the node does not exist
-
setCDATAIfExist
XMLTag setCDATAIfExist(String data, String relativeXpath, Object... arguments) throws XMLDocumentException Set the cdata in the targetted node. This method will replace all existing text and cdata by the given cdata, but remains on the current tag. If the targetted node does not exist, do nothing.- Parameters:
data
- text to put under this node in a cdata sectionrelativeXpath
- XPath expression that select the nodearguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- this
- Throws:
XMLDocumentException
- If the XPath expression is invalid
-
setAttribute
Sets the new value on an existign attribute, and remains on the current tag.- Parameters:
name
- attribute namevalue
- new attribute'svalue- Returns:
- attribute value
- Throws:
XMLDocumentException
- If the attribute does not exist
-
setAttributeIfExist
Sets the new value on an attribute, and remains on the current tag. If it does not exist, do nothing.- Parameters:
name
- attribute namevalue
- new attribute value- Returns:
- attribute value
-
setAttribute
XMLTag setAttribute(String name, String value, String relativeXpath, Object... arguments) throws XMLDocumentException Sets the new value on a targetted node's attribute, and remains on the current tag.- Parameters:
name
- attribute namevalue
- new attribute's valuerelativeXpath
- XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- attribute value
- Throws:
XMLDocumentException
- Attribute does not exist, targetted node does not exit, or XPath expression is invalid
-
setAttributeIfExist
XMLTag setAttributeIfExist(String name, String value, String relativeXpath, Object... arguments) throws XMLDocumentException Sets the new value on a targetted node's attribute, and remains on the current tag. If the attribute does not exist, do nothing.- Parameters:
name
- attribute namevalue
- new attribute's valuerelativeXpath
- XPath expressionarguments
- facultative Xpath expression arguments. Uses String.format() to build XPath expression.- Returns:
- attribute value
- Throws:
XMLDocumentException
- XPath expression is invalid or targetted node does not exist
-
deleteChilds
XMLTag deleteChilds()Delete all existing elements of this node- Returns:
- this
-
delete
Delete current tag and its childs. If the current tag is the root tag of xml document, it cannot be delete. It can just be replaced. In this case, an exception is thrown- Returns:
- this
- Throws:
XMLDocumentException
- if the current node is the root node
-
deleteAttributes
XMLTag deleteAttributes()Delete all existing attributes of current node- Returns:
- this
-
deleteAttribute
Delete an attribute of the current node.- Parameters:
name
- attribute name- Returns:
- this
- Throws:
XMLDocumentException
- if the attribute does not exist
-
deleteAttributeIfExists
Delete an attribute of the current node, if it exists- Parameters:
name
- attribute name- Returns:
- this
-
renameTo
Replace current element name by another name- Parameters:
newTagName
- New name of the tag- Returns:
- this
-
deletePrefixes
XMLTag deletePrefixes()Remove any prefix and namespaces contained in the tag name, childs and attributes, thus changing namespace and tag name. This can be very useful if you are working in a document when you want to ignore namespaces, if you don't know the tag prefix- Returns:
- this
-
toDocument
Document toDocument()- Returns:
- the Document
-
toSource
Source toSource()- Returns:
- This document as
Source
-
toString
String toString() -
toString
- Parameters:
encoding
- destination encoding of XML document- Returns:
- a string representation of the document
-
toBytes
byte[] toBytes()- Returns:
- This document representation as String bytes, using default encoding of the document
-
toBytes
- Parameters:
encoding
- The encoding to use- Returns:
- This document representation as String bytes using sepcified ancoding
-
toResult
Converts this document to the result provided- Parameters:
out
- The output result- Returns:
- this
-
toResult
Converts this document to the result provided, overriding default encoding of xml document- Parameters:
out
- The output resultencoding
- The new encoding- Returns:
- this
-
toStream
Write this document to a stream- Parameters:
out
- The output result- Returns:
- this
-
toStream
Write this document to a stream- Parameters:
out
- The output resultencoding
- The new encoding- Returns:
- this
-
toStream
Write this document to a stream- Parameters:
out
- The output result- Returns:
- this
-
toStream
Write this document to a stream- Parameters:
out
- The output resultencoding
- The new encoding- Returns:
- this
-
toResult
Result toResult()- Returns:
- The
Result
representation of this document. Useful when using web services for example.
-
toResult
- Parameters:
encoding
- The new encoding- Returns:
- The
Result
representation of this document. Useful when using web services for example.
-
toOutputStream
OutputStream toOutputStream()- Returns:
- A stream where the document has already been written into
-
toOutputStream
- Parameters:
encoding
- The new encoding- Returns:
- A stream where the document has already been written into
-
toWriter
Writer toWriter()- Returns:
- A stream where the document has already been written into
-
toWriter
- Parameters:
encoding
- The new encoding- Returns:
- A stream where the document has already been written into
-
validate
Validate this document against specifief schemas- Parameters:
schemas
- A list of schemas- Returns:
- A validation result object containing exception list occured if any
-
validate
Validate this document against specifief schemas- Parameters:
schemaLocations
- A list of schemas- Returns:
- A validation result object containing exception list occured if any
-