XmlExtensions

java.lang.Object
- org.vishia.xml.XmlExtensions

```
public class XmlExtensions
extends java.lang.Object
```
The class XmlExtensions contains several methods to deal with XML data. It uses JDOM as basic access to XML. The JDOM library downloadable from www.jdom.org is necessary.
They are three groups of tasks of this class:
- Access to inner parts of an element tree: This feature is implemented in the methods getChildren(Element, String), getTextFromPath(Element, String, boolean) and setTextToPath(Element, String, String ). With this methods a textual controlled access to any content inside Elements is possible, without calling a XSL-translator, but directly. The textual given pathes are comparably to XPATH, but not equivalent.
- Read and write whole XML trees from files and to files. The beautification and handling of white spaces are topics of the appropriate methods read...() and write...().
- Wrapper to call the XSL translator xslTransformString(Element, File) and xslTransformXml(Element, File). The cause of this wrappers are catch of exceptions and supply detached xml elements (not bind to a document) as result of XSL translation.
The beautification and white space processing followes the necessities of document text processing. It is a own problem of XML, that spaces and new lines are determined by output formats (beautification) and content, both is not distinguishably. From there, in some XML formats no beautification is made. But such XML files are arduously readable by human. But in document texts, no linefeed should be present because linefeeds are not parts of the information itself, they are parts of the appearance of the information at printing. This is adequate to the spaces: Only one space in series may be a part of the information itself. White spaces are not.
From there any input with white spaces may be reduced to one space after reading from file. The routing replaceWhiteSpaceWith1Space(Element, boolean) implements this feature. The reduced input xml tree may be processed by any XSL translation or other XML processing in Java. The output may be beautificated for better readability by human. But the spaces of text content may be beware. The beautification is only made respecitvely to the superior organisation elements. The methods beautificationBewareTextContent(Element) and the writeXmlBeautificatedTextFile(Element, File) do so.

Most of the methods are static, because no internal data are necessary. The output methods uses settings of some properties: encoding, indent mode, so they are based on a instance of XmlExtensions. A instance of XmlExtensions will be created by the static methods create(Charset), the constructors are private. This is a design attempt ajar to factory patterns. The using of new XmlExtension(...) instead create(...) will be adequate, but here create() is the decision.
```
date       who        change
2007-01-02 JcHartmut  create() with Charset, some methods will be non static.
2006-03-07 JcHartmut  beautification, replaceWhiteSpaceWith1Space.
2005-06-00 JcHartmut  initial revision
```

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class XmlExtensions.XmlMode
Class hold some properties of transformation.

Nested Classes
Modifier and Type	Class and Description
`static class`	`XmlExtensions.XmlMode` Class hold some properties of transformation.

Constructor Summary

Constructors
Constructor and Description

XmlExtensions()

Constructors
Constructor and Description
`XmlExtensions()`

Method Summary

Methods
Modifier and Type	Method and Description
`static Element`	`beautificationBewareTextContent(Element xml)` Beautificates the content of the Element with respecting of textual content preserving.
`static java.util.List<org.jdom.Parent>`	`getChildren(Element xml, java.lang.String sXmlPath)` Gets a list of children, not only from the given xml Element, but also from a deeper level.
`static java.lang.String`	`getTextFromPath(Element xml, java.lang.String sXmlPath, boolean bInvalidIsOk)` Gets the text content from the adressed node relativ to the given Element.
`static Element`	`readXmlFile(java.io.File file)` Reads a xml file and convert it to a internal xml tree.
`static Element`	`readXmlFileTrimWhiteSpace(java.io.File file)` Reads a xml file and convert it to a internal xml tree.
`static void`	`replaceWhiteSpaceWith1Space(Element xml, boolean bContendText)` Replaces white spaces of all text()-content with one space, by keeping the inner leading and trailing spaces.
`static void`	`reportContentElement(Element xml, Report report)` Write the content of the xml-node in the report
`static boolean`	`setTextToPath(Element xml, java.lang.String sXmlPath, java.lang.String sContent)` Sets the specified element with the given value.
`static void`	`writeXmlBeautificatedTextFile(Element xmlRoot, java.io.File fileOut, java.nio.charset.Charset encoding)` Output a xml tree to a file with beautification of the output, but beware all spaces inside textual content.
`static void`	`writeXmlDirect(Element xml, java.io.File fileOut, java.lang.String sEncoding)` Output a xml tree to a file.
`static void`	`writeXmlDirect(Element xml, java.io.Writer out, java.lang.String sEncoding)` Output a xml tree to a file.
`void`	`writeXmlFile(Element xmlRoot, java.io.File fileOut)` Output a xml tree to a file.
`static void`	`writeXmlFile(Element xmlRoot, java.io.File fileOut, XmlExtensions.XmlMode mode)` Output a xml tree to a file.
`static java.lang.String`	`xslTransformString(Element xmlInput, java.io.File xslFile)` Transform a xml tree to a string.
`static Element`	`xslTransformXml(Element xmlInput, java.io.File xslFile)` XSL-Transformation of a xml tree to a new tree.

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

Constructor Detail
- XmlExtensions
```
public XmlExtensions()
```

Method Detail

beautificationBewareTextContent
```
public static Element beautificationBewareTextContent(Element xml)
```
Beautificates the content of the Element with respecting of textual content preserving. Copies the Element content inclusive childs into a new Element and returns the new Element. If an element (child element) contents text(), than the content is copied without changes, like xml:space="preserve".
If no text() is containing, all empty (only whitespace)-text()- elements are ignored, and between elements, linefeed and indent is added. So the output written with org.jdom.output.Format.getRawFormat() is beautificated. This method is called recursively if child Elements are present.
Example: if the input xml tree contains:
```
<sampleTag><innerTag>This is text with bold and inner bold text</innerTag></sampleTag>
 
```
The output will be:
```
 <sampleTag>
 <innerTag>
 This is text with bold and inner bold text
 </innerTag>
 </sampleTag>
 
```
Another way to get beautificated output may be using the formatting possibilities of JDOM, but they take no consideration of inner textual elements. If beautification is choiced, all elements are beautificated and the original space structure may be corrupted. The above example will written in form
```
 <sampleTag>
 <innerTag>
 This is text
 with bold
 
 and i
 nn
 
 er bold text
 
 </innerTag>
 </sampleTag>
 
```
In this sample always a whitespace is produced between elements in output, even if the user will not have a space.
Note: The identation is limited to approximately a half page width (length of sIndent).
Note: other content as Element and Text are not supported yet (:TODO:).
Parameters:
xml - The Input element tree.

Returns:
A new XML tree with beautificated content.

getChildren
```
public static java.util.List<org.jdom.Parent> getChildren(Element xml,
 java.lang.String sXmlPath)
```
Gets a list of children, not only from the given xml Element, but also from a deeper level. This method is useable conveniently if the path is given in textual form outside the directly programming in java, but at example with control files (may be in XML) or from a conversion of XML data to a java routine (code generation). The Path, param sXmlPath, may be given in the followed form,
examples:
- "element1/name": children of element1 with tag name "name"
- "element1/*": all children of element1
- "../name": all siblings with name
- "../*": all siblings inclusive self
- "..": Only the parent of self
- "../..": Only the parent of parent
- ".": Only self (it is the param xml itself)
If the path ends with ".." or ".", the list contains only the addressed element, it is not a list getted with org.jdom.Element.getChildren(), it is a simple LinkedList with this one element.
But if the path ends with an named element or "*", the returned list is a list getted with org.jdom.Element.getChildren(). It means, that all operations may be applied to the list, including add of further siblings using thelist.listIterator().add(sibling);
Parameters:
xml - The parent element.
sXmlPath - Path relativ from parent to the element from which the children are listed. If the path is "." or empty,

Returns:
List of children or null if any error in path.

getTextFromPath

public static java.lang.String getTextFromPath(Element xml,
                               java.lang.String sXmlPath,
                               boolean bInvalidIsOk)

Gets the text content from the adressed node relativ to the given Element. This method is useable conveniently if the path is given in textual form outside the directly programming in java, but at example with control files (may be in XML) or from a conversion of XML data to a java routine (code generation).
The Path, param sXmlPath, may be given in the followed form,
example: "../element/@attribute" or "@name+$+{Parameter|@name|$}"

sample	meaning
`name`	Normalized text content of the element
`@name`	content of the attribute
`name/child`	Normalized text content of the child element
`name/@attr`	content of the attribute within the element
`name/name/@attr`	The path can be in any deepness
`../../name`	parent from parent
`"text"`	the constant text between "". It may be a part of the path concating with other parts with +, but it is also possible to return a text directly, without using the input xml element. This choice is conveniently, because the behaviour may be determined outside of a java programming, and no special case will be produced if only a simple text is expected.
`path+"text"+path`	concation between the texts from pathes
`path+c+path`	1 char between + is a added separator, it is the same as `+"c"+`
`path+c`	1 char on end after +, same as here `+"."`
`{apath\|vpath\|c}`	concation of all textes from `vpath` from all elements found with `apath`, with `c` as separator between the concatenated result strings. With using this expression as part of sXmlPath it is possible to concatenate the content of more as one elements without using of a extra programmed loop.

Parameters:: xml - The Element the path starts from.; sXmlPath - The path expression see above.; bInvalidIsOk - If true, than return "" on invalid path, if false than return null on invalid path.
Returns:: The requested text content, "" or null if the path is not valid.

readXmlFile
```
public static Element readXmlFile(java.io.File file)
                           throws XmlException
```
Reads a xml file and convert it to a internal xml tree. This is a simple frame arround SAXBuilder. On any problem an exception is thrown. This may be a file-not-found or a parsing problem with the content of the xml-file.

Returns:
The root element

Throws:

XmlException

readXmlFileTrimWhiteSpace
```
public static Element readXmlFileTrimWhiteSpace(java.io.File file)
                                         throws XmlException
```
Reads a xml file and convert it to a internal xml tree. This is a more complex frame arround SAXBuilder. The special solution is the followed:
* By reading from file every newline is converted to a space char, except the first line. It means, the file have only 2 lines, the head line and a very long second line with the whole content.
* After reading all whitespaces are converted to one space using replaceWhiteSpaceWith1Space(Element, boolean).

The effect is the followed: The textual content from the inputted XML file doesn 't contain any whitespaces, or line feed. Every white space is converted to one spaces. More as one space in serial doesn't exist. No line structure is given. If a prior beautificated input is there, it is now non-beatificated, simple. This is a format appropriately useable for document processing with document formatting structures.

Parameters:
file - The file from which xml is readed.

Returns:
The root element without whitespaces.

Throws:

XmlException

replaceWhiteSpaceWith1Space
```
public static void replaceWhiteSpaceWith1Space(Element xml,
 boolean bContendText)
```
Replaces white spaces of all text()-content with one space, by keeping the inner leading and trailing spaces. The original behaviour of XML outputter is the possibility of replacement of all whitespace with one space, but only in combination with trimming all leading and trailing spaces with no replacement with one spaces. This property sometimes is not useable, at example in a combination of "text This is bold The last space is a bold space." The trimming ignores the space and the text would be corrupted.

Parameters:
xml - The element to be white-spaces-trimmed.
bContendText - Normally let it false by calling outside! If false, than test of containing text(), if it contains text() than delete the first leading and the last trailing whitespace and call recursively for inner elements with true.
If true than normalize, but keep one space instead of possible leading or trainling white spaces. This is the correct choice for inner (recursively) calling.

reportContentElement

public static void reportContentElement(Element xml,
                        Report report)

Write the content of the xml-node in the report

setTextToPath

public static boolean setTextToPath(Element xml,
                    java.lang.String sXmlPath,
                    java.lang.String sContent)

Sets the specified element with the given value. The Path may be given in the followed form (example): "../element/@attribute"

Parameters:

xml - Element within the content is setted

sXmlPath - Path selects the child within xml, into the sContent is setted. The path should be given in form "../../name/name/dst". The specification ".." means the parent, like XPATH. All childs are created, if they don't exist.
The last element of the path may be a special specification:

form	Description
name	the child with the name
.	The element itself (sXmlPath="." is the input element itself)
@name	example: "tag/@name". Sets the content into the attribute name of the tag
=	example: "tag/tag2/=". Sets the content into the element tag2, otherwise the content is appended to name2
!	example: "tag/tag2/!". Changes the name of the selected xml-Element tag2 to the sContent

sContent - content set to the element, attribute or defines the name of the element.

Returns:

true if succesfull, false if the element is not found or other error (if no effect).

writeXmlBeautificatedTextFile
```
public static void writeXmlBeautificatedTextFile(Element xmlRoot,
                                 java.io.File fileOut,
                                 java.nio.charset.Charset encoding)
                                          throws XmlException,
                                                 java.io.FileNotFoundException
```
Output a xml tree to a file with beautification of the output, but beware all spaces inside textual content. It calls internally beautificationNoTextContent(Element)

Parameters:
xmlRoot - The root element
fileOut - The file to write out. The file will be created or replaced.

Throws:

java.io.FileNotFoundException - If the fileOut doesn't match.

XmlException

writeXmlDirect
```
public static void writeXmlDirect(Element xml,
                  java.io.File fileOut,
                  java.lang.String sEncoding)
                           throws XmlException,
                                  java.io.FileNotFoundException
```
Output a xml tree to a file.

Parameters:
xmlRoot - The root Element of the created output XML-File.
fileOut - This file will be created or replaced.
sEncoding - The encoding, typicall "ISO-8859-1"

Throws:

java.io.FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

java.io.IOException - if any error on writing at file system

java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

XmlException

writeXmlDirect
```
public static void writeXmlDirect(Element xml,
                  java.io.Writer out,
                  java.lang.String sEncoding)
                           throws XmlException,
                                  java.io.IOException
```
Output a xml tree to a file.

Parameters:
xmlRoot - The root Element of the created output XML-File.
fileOut - This file will be created or replaced.
sEncoding - The encoding, typicall "ISO-8859-1"

Throws:

java.io.FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

java.io.IOException - if any error on writing at file system

java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

XmlException

writeXmlFile
```
public void writeXmlFile(Element xmlRoot,
                java.io.File fileOut)
                  throws XmlException,
                         java.io.FileNotFoundException
```
Output a xml tree to a file. if setIndent() is called with null-Argument, than write without wrapping. Otherwise, wrap with the given indent. If the output is written with indent, it is revitalize readable. Some times, the text should be written with exactly spaces, not with white spaces, from there setIndent(null) should be called before. The output will be written with the charset defined by create(Charset) or setEncoding(int).

Parameters:
xmlRoot - The root Element of the created output XML-File.
fileOut - This file will be created or replaced.

Throws:

java.io.FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

java.io.IOException - if any error on writing at file system

java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

XmlException

writeXmlFile
```
public static void writeXmlFile(Element xmlRoot,
                java.io.File fileOut,
                XmlExtensions.XmlMode mode)
                         throws XmlException,
                                java.io.FileNotFoundException
```
Output a xml tree to a file.

Parameters:
xmlRoot - The root Element of the created output XML-File.
fileOut - This file will be created or replaced.
sEncoding - The encoding, typicall "ISO-8859-1"

Throws:

java.io.FileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason

java.io.IOException - if any error on writing at file system

java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

XmlException

xslTransformString

public static java.lang.String xslTransformString(Element xmlInput,
                                  java.io.File xslFile)
                                           throws XmlException

Transform a xml tree to a string. The input tree is started from an detached xml Element.

Returns:: the string.
Throws:: XmlException

xslTransformXml
```
public static Element xslTransformXml(Element xmlInput,
                      java.io.File xslFile)
                               throws XmlException
```
XSL-Transformation of a xml tree to a new tree. The input tree is started from an detached xml Element. Internally javax.xml is used.

Returns:
The new xml tree. The returned root element has not a parent, it is detached. So it can be added to any other tree.

Throws:

XmlException

Class XmlExtensions

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XmlExtensions

Method Detail

beautificationBewareTextContent

getChildren

getTextFromPath

readXmlFile

readXmlFileTrimWhiteSpace

replaceWhiteSpaceWith1Space

reportContentElement

setTextToPath

writeXmlBeautificatedTextFile

writeXmlDirect

writeXmlDirect

writeXmlFile

writeXmlFile

xslTransformString

xslTransformXml