com.bristle.javalib.xml
Class XSLUtil

java.lang.Object
  com.bristle.javalib.xml.XSLUtil

public class XSLUtil
extends Object

This class contains utility routines for working with XSL.

Usage:
   - Some typical scenarios for using this class are:

     - To apply an XSL transformation to an XML tree:
           xmlXML2 = XSLUtil.transform(xmlXML1, xmlXSL);

     - To copy an XML tree:   
           xml2 = XSLUtil.copy(xml1);

     - To strip the comments from an XML tree:   
           xml2 = XSLUtil.stripComments(xml1);

     - To copy an XML tree into a subtree of another XML tree:   
           XSLUtil.copy(xml1, xmlChildOfXML2);

     - To sort the child Elements (in this case, the B Elements) within an 
       XML Element (the A Element), ordering them by the value of a specified 
       XML Element (the C Element) nested within each child Element.

           Document dom = XMLUtil.loadDocumentFromString
                   ("<A>" +
                      "<B>" +
                        "<C>3</C>" +
                      "</B>" +
                      "<B>" +
                        "<C>2</C>" +
                      "</B>" +
                      "<B>" +
                        "<C>10</C>" +
                      "</B>" +
                    "</A>");
           XSLUtil.sortElements(dom, "A", "C",
                         XSLUtil.SortDataType.TEXT,
                         XSLUtil.SortOrder.ASCENDING,
                         XSLUtil.SortCaseOrder.UPPER_CASE_FIRST);

       Resulting DOM: 
                     <A>
                       <B>
                         <C>10</C>
                       </B>
                       <B>
                         <C>2</C>
                       </B>
                       <B>   
                         <C>3</C>
                       </B>
                     </A>


     - You can also sort numerically, instead of alphabetically.
       To sort the child Elements (in this case, the B Elements) within an 
       XML Element (the A Element), ordering them by the numeric value of a 
       specified XML Element (the C Element) nested within each child Element.

           Document dom = XMLUtil.loadDocumentFromString
                   ("<A>" +
                      "<B>" +
                        "<C>3</C>" +
                      "</B>" +
                      "<B>" +
                        "<C>2</C>" +
                      "</B>" +
                      "<B>" +
                        "<C>10</C>" +
                      "</B>" +
                    "</A>");
           XSLUtil.sortElements(dom, "A", "C",
                         XSLUtil.SortDataType.NUMBER,
                         XSLUtil.SortOrder.ASCENDING,
                         XSLUtil.SortCaseOrder.UPPER_CASE_FIRST);

       Resulting DOM: 
                     <A>
                       <B>
                         <C>2</C>
                       </B>
                       <B>   
                         <C>3</C>
                       </B>
                       <B>
                         <C>10</C>
                       </B>
                     </A>

 
     - You can sort by attribute value, instead of by nested Element value.
       To sort the child Elements (in this case, the B Elements) within an 
       XML Element (the A Element), ordering them by the value of a 
       specified XML Attribute (the attr1 Attribute) of each child Element.

           Document dom = XMLUtil.loadDocumentFromString
                   ("<A>" +
                      "<B attr1='3'>" +
                        "<C>some text</C>" +
                      "</B>" +
                      "<B attr1='2'>" +
                        "<C>some more text</C>" +
                      "</B>" +
                      "<B attr1='10'>" +
                        "<C>yet more text</C>" +
                      "</B>" +
                    "</A>");
           XSLUtil.sortElements(dom, "A", "@attr1",
                         XSLUtil.SortDataType.TEXT,
                         XSLUtil.SortOrder.ASCENDING,
                         XSLUtil.SortCaseOrder.UPPER_CASE_FIRST);

       Resulting DOM: 
                     <A>
                       <B attr1='10'>
                         <C>yet more text</C>
                       </B>
                       <B attr1='2'>   
                         <C>some more text</C>
                       </B>
                       <B attr1='3'>
                         <C>some text</C>
                       </B>
                     </A>


     - The sorted child Elements need not all be the same type of Element.  
       To sort the child Elements (in this case, the B and Z Elements) 
       within an XML Element (the A Element), ordering them by the value of 
       a specified XML Element (the C Element) nested within each child 
       Element.

           Document dom = XMLUtil.loadDocumentFromString
                   ("<A>" +
                      "<B>" +
                        "<C>3</C>" +
                      "</B>" +
                      "<Z>" +
                        "<C>2</C>" +
                      "</Z>" +
                      "<B>" +
                        "<C>10</C>" +
                      "</B>" +
                    "</A>");
           XSLUtil.sortElements(dom, "A", "C",
                         XSLUtil.SortDataType.TEXT,
                         XSLUtil.SortOrder.ASCENDING,
                         XSLUtil.SortCaseOrder.UPPER_CASE_FIRST);

       Resulting DOM: 
                     <A>
                       <B>
                         <C>10</C>
                       </B>
                       <Z>
                         <C>2</C>
                       </Z>
                       <B>   
                         <C>3</C>
                       </B>
                     </A>


     - You can also sort the children of multiple parents at the same time.
       In the above examples, if there had been multiple A Elements in the 
       XML tree (even at different nesting levels), each would have had its
       child Elements sorted within it.  In such a case, you can specify a 
       more specific parent XPath, like "A[2]" to limit the sort to a 
       single parent.

     - You can use any valid XPath to specify the parents, not just the 
       simplistic "A" and "A[2]" examples above.    

     - You can use any valid XPath to specify the sort key, not just the 
       simplistic "C" and "@attr1" examples above.    

   - See the source code of the inner Tester class for more examples.
  
Assumptions:
Effects:
       - None.
Anticipated Changes:
Notes:
       - Pay particular attention to the distinction between the different
         XML DOM node types.  The names and comments in this class use these
         different terms very precisely: 
           Document    An entire XML DOM document
           DocumentFragment    
                       A fragment of an XML document.
           Element     An XML element or tag (an item in angle brackets)
           Text        A sequence of text stored in an Element
           Node        Could be any of the above, or an XML attribute, CDATA,
                       comment, document type, entity, etc.
         See the org.w3c.dom.Node documentation for details.            
Implementation Notes:
Portability Issues:
Revision History:
   $Log$

Nested Class Summary

static class	XSLUtil.SortCaseOrder This class represents an enumerated type that identifies sort case orders (upper case first, lower case first, case insensitive).
static class	XSLUtil.SortDataType This class represents an enumerated type that identifies data types to sort by.
static class	XSLUtil.SortOrder This class represents an enumerated type that identifies sort orders (ascending and descending).
static class	XSLUtil.Tester Each class contains a Tester inner class with a main() for easier unit testing.

Constructor Summary

XSLUtil()

Method Summary

static Document	copy(Node xml) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to a new Document.
static Node	copy(Node xmlXML, DOMResult xmlResult) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node.
static Node	copy(Node xmlXML, Node xmlResult) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified Node (which should be an XML Document, DocumentFragment or Element), and returning the generated XML as a Node.
static Document	getIdentityTransformationStylesheetDocument() Returns the identity transformation stylesheet as an XML Document.
static String	getIdentityTransformationStylesheetString() Returns the identity transformation stylesheet as a string of XSL.
static String	getIdentityTransformationTemplateString() Returns the identity transformation template as a string of XSL.
static Document	getSortElementsTransformationStylesheetDocument(String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder) Returns a sort transformation stylesheet as an XML Document.
static String	getSortElementsTransformationStylesheetString(String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder) Returns a sort transformation stylesheet as a string of XSL.
static String	getSortElementsTransformationTemplateString(String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder) Returns a sortElements transformation template as a string of XSL.
static Document	getStripCommentsTransformationStylesheetDocument() Returns a "strip comments" transformation stylesheet as an XML Document.
static String	getStripCommentsTransformationStylesheetString() Returns a "strip comments" transformation stylesheet as a string of XSL.
static String	getStripCommentsTransformationTemplateString() Returns a "strip comments" transformation template as a string of XSL.
static Node	sortElements(Node xml, String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder) Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to a new Document, and returning the sorted XML as a Node.
static Node	sortElements(Node xmlXML, String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder, DOMResult xmlResult) Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the sorted XML as a Node.
static Node	sortElements(Node xmlXML, String strParentElementXPath, String strSortKeyXPath, XSLUtil.SortDataType dataType, XSLUtil.SortOrder order, XSLUtil.SortCaseOrder caseOrder, Node xmlResult) Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to the specified Node (which should be an XML Document, DocumentFragment or Element), and returning the sorted XML as a Node.
static Document	stripComments(Node xml) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to a new Document, but stripping the comments out of the generated copy.
static Node	stripComments(Node xmlXML, DOMResult xmlResult) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), but stripping the comments out of the generated copy, and returning the generated XML as a Node.
static Node	stripComments(Node xmlXML, Node xmlResult) Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified Node (which should be an XML Document, DocumentFragment or Element), but stripping the comments out of the generated copy, and returning the generated XML as a Node.
static Document	transform(Node xmlXML, Node xmlXSL) Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, and returning a new Document.
static Node	transform(Node xmlXML, Node xmlXSL, DOMResult xmlResult) Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, storing the generated XML in the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node.
static Node	transform(Node xmlXML, Node xmlXSL, Node xmlResult) Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, storing the generated XML in the specified result Node (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node.
static String	wrapInXSLStylesheet(String strXSL) Returns an XSL stylesheet as a String, wrapping the syntax for the required xsl:stylesheet node around the specified XML string which may be one or more xsl:templates, or any other valid XSL syntax.

Methods inherited from class java.lang.Object

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

Constructor Detail

XSLUtil

public XSLUtil()

Method Detail

wrapInXSLStylesheet

public static String wrapInXSLStylesheet(String strXSL)

Returns an XSL stylesheet as a String, wrapping the syntax for the required xsl:stylesheet node around the specified XML string which may be one or more xsl:templates, or any other valid XSL syntax.

Returns:

The XSL stylesheet string

getIdentityTransformationTemplateString

public static String getIdentityTransformationTemplateString()

Returns the identity transformation template as a string of XSL. Unlike getIdentityTransformationStylesheetString(), this is not a complete XSL stylesheet. It is only an XSL template subtree. That is, its root node is xsl:template, not xsl:stylesheet. Therefore, it cannot be used as a standalone XSL stylesheet. However, it can be combined with other strings of XSL to produce a standalone XSL stylesheet. When that stylesheet is applied to an XML tree, this template will cause XML nodes that are not matched by more specific templates of the stylesheet to be copied unchanged.

Returns:

The XSL transformation template string

See Also:

wrapInXSLStylesheet(java.lang.String)

getIdentityTransformationStylesheetString

public static String getIdentityTransformationStylesheetString()

Returns the identity transformation stylesheet as a string of XSL. This stylesheet can be applied to an XML tree, causing all XML nodes to be copied unchanged.

Returns:

The XSL transformation stylesheet string

getIdentityTransformationStylesheetDocument

public static Document getIdentityTransformationStylesheetDocument()
                                                            throws SAXException,
                                                                   IOException

Returns the identity transformation stylesheet as an XML Document. This stylesheet can be applied to an XML tree, causing all XML nodes to be copied unchanged.

Returns:

The XSL transformation stylesheet Document.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

getStripCommentsTransformationTemplateString

public static String getStripCommentsTransformationTemplateString()

Returns a "strip comments" transformation template as a string of XSL. Unlike getStripCommentsTransformationStylesheetString(), this is not a complete XSL stylesheet. It is only an XSL template subtree. That is, its root node is xsl:template, not xsl:stylesheet. Therefore, it cannot be used as a standalone XSL stylesheet. However, it can be combined with other strings of XSL to produce a standalone XSL stylesheet. When that stylesheet is applied to an XML tree, this template will cause all XML non-comment nodes that are not matched by more specific templates of the stylesheet to be copied unchanged, but comments will be omitted.

Returns:

The XSL transformation template string

See Also:

wrapInXSLStylesheet(java.lang.String)

getStripCommentsTransformationStylesheetString

public static String getStripCommentsTransformationStylesheetString()

Returns a "strip comments" transformation stylesheet as a string of XSL. This stylesheet can be applied to an XML tree, causing all non-comment XML nodes to be copied unchanged, but omitting comments.

Returns:

The XSL transformation stylesheet string

getStripCommentsTransformationStylesheetDocument

public static Document getStripCommentsTransformationStylesheetDocument()
                                                                 throws SAXException,
                                                                        IOException

Returns a "strip comments" transformation stylesheet as an XML Document. This stylesheet can be applied to an XML tree, causing all non-comment XML nodes to be copied unchanged, but omitting comments.

Returns:

The XSL transformation stylesheet Document.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

getSortElementsTransformationTemplateString

public static String getSortElementsTransformationTemplateString(String strParentElementXPath,
                                                                 String strSortKeyXPath,
                                                                 XSLUtil.SortDataType dataType,
                                                                 XSLUtil.SortOrder order,
                                                                 XSLUtil.SortCaseOrder caseOrder)

Returns a sortElements transformation template as a string of XSL. Unlike getSortElementsTransformationStylesheetString(), this is not a complete XSL stylesheet. It is only an XSL template subtree. That is, its root node is xsl:template, not xsl:stylesheet. Therefore, it cannot be used as a standalone XSL stylesheet. However, it can be combined with other strings of XSL to produce a standalone XSL stylesheet. When that stylesheet is applied to an XML tree, this template will sort the child XML Elements within each specified parent XML Element.

Parameters:

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each child Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

Returns:

The XSL transformation template string

See Also:

wrapInXSLStylesheet(java.lang.String)

getSortElementsTransformationStylesheetString

public static String getSortElementsTransformationStylesheetString(String strParentElementXPath,
                                                                   String strSortKeyXPath,
                                                                   XSLUtil.SortDataType dataType,
                                                                   XSLUtil.SortOrder order,
                                                                   XSLUtil.SortCaseOrder caseOrder)

Returns a sort transformation stylesheet as a string of XSL. This stylesheet can be applied to an XML tree, sorting the child XML Elements within each specified parent XML Element.

Parameters:

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

Returns:

The XSL transformation stylesheet string

getSortElementsTransformationStylesheetDocument

public static Document getSortElementsTransformationStylesheetDocument(String strParentElementXPath,
                                                                       String strSortKeyXPath,
                                                                       XSLUtil.SortDataType dataType,
                                                                       XSLUtil.SortOrder order,
                                                                       XSLUtil.SortCaseOrder caseOrder)
                                                                throws SAXException,
                                                                       IOException

Returns a sort transformation stylesheet as an XML Document. This stylesheet can be applied to an XML tree, sorting the child XML Elements within each specified parent XML Element.

Parameters:

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

Returns:

The XSL transformation stylesheet Document.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

transform

public static Node transform(Node xmlXML,
                             Node xmlXSL,
                             DOMResult xmlResult)
                      throws TransformerConfigurationException,
                             TransformerException

Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, storing the generated XML in the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node. Can safely be called to update a Document in place as: xmlXML1 = transform(xmlXML1, xmlXSL, new DOMResult()); Can also safely be called to insert new nodes into the source XML by passing a child of the source XML as the target. For example: transform(xmlXML1, xmlXSL, new DOMResult(xmlChildNodeOfXML1));

Parameters:

xmlXML - XML to be transformed

xmlXSL - XSL transformation

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

The transformed XML

Throws:

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

transform

public static Node transform(Node xmlXML,
                             Node xmlXSL,
                             Node xmlResult)
                      throws TransformerConfigurationException,
                             TransformerException

Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, storing the generated XML in the specified result Node (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node. Can safely be called to update a Document in place as: xmlXML1 = transform(xmlXML1, xmlXSL, null); Can also safely be called to insert new nodes into the source XML by passing a child of the source XML as the target. For example: transform(xmlXML1, xmlXSL, xmlChildNodeOfXML1);

Parameters:

xmlXML - XML to be transformed

xmlXSL - XSL transformation

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

The transformed XML

Throws:

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

transform

public static Document transform(Node xmlXML,
                                 Node xmlXSL)
                          throws TransformerConfigurationException,
                                 TransformerException

Applies the specified XSL transformation to the specified XML Document, DocumentFragment or Element, leaving the original XML untouched, and returning a new Document. Can also safely be called to update a Document in place as: xmlXML = transform(xmlXML, xmlXSL);

Parameters:

xmlXML - XML to be transformed

xmlXSL - XSL transformation

Returns:

The transformed XML

Throws:

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

copy

public static Node copy(Node xmlXML,
                        DOMResult xmlResult)
                 throws SAXException,
                        IOException,
                        TransformerConfigurationException,
                        TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the generated XML as a Node. Can safely be called to copy a Document onto itself as: xmlXML1 = copy(xmlXML1, new DOMResult()); Can also safely be called to insert a copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: copy(xmlXML1, new DOMResult(xmlChildNodeOfXML1));

Parameters:

xmlXML - XML to be transformed

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

copy

public static Node copy(Node xmlXML,
                        Node xmlResult)
                 throws SAXException,
                        IOException,
                        TransformerConfigurationException,
                        TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified Node (which should be an XML Document, DocumentFragment or Element), and returning the generated XML as a Node. Can safely be called to copy a Document onto itself as: xmlXML1 = copy(xmlXML1, null); Can also safely be called to insert a copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: copy(xmlXML1, xmlChildNodeOfXML1);

Parameters:

xmlXML - XML to be transformed

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

copy

public static Document copy(Node xml)
                     throws SAXException,
                            IOException,
                            TransformerConfigurationException,
                            TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to a new Document. Can also safely be called to update a Document in place as: xmlXML = copy(xmlXML);

Parameters:

xml - XML to be transformed

Returns:

A copy of the XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

stripComments

public static Node stripComments(Node xmlXML,
                                 DOMResult xmlResult)
                          throws SAXException,
                                 IOException,
                                 TransformerConfigurationException,
                                 TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), but stripping the comments out of the generated copy, and returning the generated XML as a Node. Can safely be called to copy a Document onto itself as: xmlXML1 = stripComments(xmlXML1, new DOMResult()); Can also safely be called to insert a comment-stripped copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: stripComments(xmlXML1, new DOMResult(xmlChildNodeOfXML1));

Parameters:

xmlXML - XML to be transformed

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the XML, with comments stripped.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

stripComments

public static Node stripComments(Node xmlXML,
                                 Node xmlResult)
                          throws SAXException,
                                 IOException,
                                 TransformerConfigurationException,
                                 TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to the specified Node (which should be an XML Document, DocumentFragment or Element), but stripping the comments out of the generated copy, and returning the generated XML as a Node. Can safely be called to copy a Document onto itself as: xmlXML1 = stripComments(xmlXML1, null); Can also safely be called to insert a comment-stripped copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: stripComments(xmlXML1, xmlChildNodeOfXML1);

Parameters:

xmlXML - XML to be transformed

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the XML, with comments stripped.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

stripComments

public static Document stripComments(Node xml)
                              throws SAXException,
                                     IOException,
                                     TransformerConfigurationException,
                                     TransformerException

Uses an XSL transformation to copy the specified XML Document, DocumentFragment or Element to a new Document, but stripping the comments out of the generated copy. Can also safely be called to update a Document in place as: xmlXML = stripComments(xmlXML);

Parameters:

xml - XML to be transformed

Returns:

A copy of the XML, with comments stripped.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

sortElements

public static Node sortElements(Node xmlXML,
                                String strParentElementXPath,
                                String strSortKeyXPath,
                                XSLUtil.SortDataType dataType,
                                XSLUtil.SortOrder order,
                                XSLUtil.SortCaseOrder caseOrder,
                                DOMResult xmlResult)
                         throws SAXException,
                                IOException,
                                TransformerConfigurationException,
                                TransformerException

Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to the specified DOMResult (which should refer to an XML Document, DocumentFragment or Element), and returning the sorted XML as a Node. Can safely be called to sort a Document onto itself as: xmlXML1 = sortElements (xmlXML1, strElementName, strKey, XSLUtil.SortDataType.TEXT, XSLUtil.SortOrder.ASCENDING, XSLUtil.SortCaseOrder.UPPER_CASE_FIRST, new DOMResult()); Can also safely be called to insert a sorted copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: sortElements (xmlXML1, strElementName, strKey, XSLUtil.SortDataType.TEXT, XSLUtil.SortOrder.ASCENDING, XSLUtil.SortCaseOrder.UPPER_CASE_FIRST, new DOMResult(xmlChildNodeOfXML1));

Parameters:

xmlXML - XML to be sorted

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each child Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the sorted XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

sortElements

public static Node sortElements(Node xmlXML,
                                String strParentElementXPath,
                                String strSortKeyXPath,
                                XSLUtil.SortDataType dataType,
                                XSLUtil.SortOrder order,
                                XSLUtil.SortCaseOrder caseOrder,
                                Node xmlResult)
                         throws SAXException,
                                IOException,
                                TransformerConfigurationException,
                                TransformerException

Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to the specified Node (which should be an XML Document, DocumentFragment or Element), and returning the sorted XML as a Node. Can safely be called to sort a Document onto itself as: xmlXML1 = sortElements (xmlXML1, strElementName, strKey, XSLUtil.SortDataType.TEXT, XSLUtil.SortOrder.ASCENDING, XSLUtil.SortCaseOrder.UPPER_CASE_FIRST, null); Can also safely be called to insert a sorted copy of the XML tree into a branch of the XML tree by passing a child of the source XML as the target. For example: sortElements (xmlXML1, strElementName, strKey, XSLUtil.SortDataType.TEXT, XSLUtil.SortOrder.ASCENDING, XSLUtil.SortCaseOrder.UPPER_CASE_FIRST, xmlChildNodeOfXML1);

Parameters:

xmlXML - XML to be sorted

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each child Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

xmlResult - The XML Document, DocumentFragment, or Element in which to store the generated XML.

Returns:

A copy of the sorted XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.

sortElements

public static Node sortElements(Node xml,
                                String strParentElementXPath,
                                String strSortKeyXPath,
                                XSLUtil.SortDataType dataType,
                                XSLUtil.SortOrder order,
                                XSLUtil.SortCaseOrder caseOrder)
                         throws SAXException,
                                IOException,
                                TransformerConfigurationException,
                                TransformerException

Sorts the child Elements of the specified Elements of the specified XML Document, DocumentFragment or Element, ordering them by the value of the specified XML Element nested within each child Element, leaving the original XML unmodified, copying the sorted XML to a new Document, and returning the sorted XML as a Node. Can safely be called to sort a Document onto itself as: xmlXML1 = sortElements (xmlXML1, strElementName, strKey, XSLUtil.SortDataType.TEXT, XSLUtil.SortOrder.ASCENDING, XSLUtil.SortCaseOrder.UPPER_CASE_FIRST);

Parameters:

xml - XML to be sorted

strParentElementXPath - XPath of parent Elements whose child Elements are to be sorted

strSortKeyXPath - XPath of XML Node to be used as the sort key within each child Element to be sorted.

dataType - Data type of the sort key

order - Order of the sort

caseOrder - Effect of case on the sort order

Returns:

A copy of the sorted XML.

Throws:

SAXException - Should never happen, unless there is an error in this class.

IOException - Should never happen, unless there is an error in this class.

TransformerConfigurationException - When the Transformer cannot be constructed.

TransformerException - When the transformation fails.