Package global.sandbox.xmlutilities

Utilities and Tools that makes XML parsing and validation more easier.

See:
          Description

Interface Summary
OutputFormat.ConfigurationValue Convenient interface for getting rendered codes.
XmlUtilitiesException.PrintStreamOrWriter  
 

Class Summary
NamespaceContextImpl Simple implementation of the NamespaceContext.
NodeListCollection<E extends Node> ArrayList like implementation for NodeList which is unmodifiable, not serializable and exposes access to original NodeList.
OutputFormat Convenient harness for configuration of Transformers' output intent.
OutputFormat.Builder Builder for declarative construction of OutputFormat.
XmlTools Static version of the XML utilities class.
XmlUtilities This class provides simple XML utilities.
XmlUtilitiesException.WrappedPrintStream  
XmlUtilitiesException.WrappedPrintWriter  
 

Enum Summary
OutputFormat.Boolean Represents Boolean value with appropriate value expected by Transformer.
OutputFormat.OutputMethod Typed representation of output method with appropriate and expected values by Transformer.
 

Exception Summary
XmlUtilitiesException Common exception related to XML Utilities.
 

Package global.sandbox.xmlutilities Description

Utilities and Tools that makes XML parsing and validation more easier. There are two ways to use this package:

Static methods are good for simple usages. It shares one internal instance of XmlUtilities. Standalone XmlUtilities instance is good for multi-threading environment. All classes share on single exception which encapsulates all cases (checked exceptions) which might happen in the processing based on its purpose.

Functions, Methods and Tools

Functions, Methods and Tools
Category Method Availability
in XmlUtilities in XmlTools
XML Loading from File to Document X X
from Stream to Document X X
from String to Document X X
from String to Source X X
Conversions Document to Source X X
Document to String X X
Source to String X X
Validation XML validation against XMLSchema X X
XPath evaluation evaluate XPath that results to NodeList X X
evaluate XPath that results to single Node X X
Transformation from Sources to Document X X
from Templates and Source to Document X X
from Sources to String X X
from Templates and Source to String X X
Legend
Not available
X Available

XML Loading

The routines are defined in XmlTools and in XmlUtilities. The names of the methods starts with loadDocument or loadSource.
The following example loads XML content from specified resource. The static method returns Document and throws two Exceptions:
NoSuchResourceException
if the resource does not exist
XmlLoadingException
this exception covers all "technical" exceptions
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XmlTools;
import global.sandbox.xmlutilities.XmlUtilitiesException;
import java.io.IOException;
import java.io.InputStream;
import javax.xml.transform.Source;
import org.w3c.dom.Document;

public class XmlLoading {

    public static Document loadXmlFromResourceAsDocument(Class<?> clazz, String name) throws NoSuchResourceException, XmlLoadingException {
        InputStream is = clazz.getResourceAsStream(name);

        if (is == null) {
            throw new NoSuchResourceException(name);
        }

        try {
            return XmlTools.loadDocumentFromStream(is);
        } catch (XmlUtilitiesException ex) {
            throw new XmlLoadingException(ex);
        } finally {
            try {
                is.close();
            } catch (IOException ex) {
                throw new XmlLoadingException(ex);
            }
        }
    }

    public static class NoSuchResourceException extends Exception {

        private static final long serialVersionUID = 1L;

        public NoSuchResourceException(String resourceName) {
            super(resourceName);
        }

    }

    public static class XmlLoadingException extends Exception {

        private static final long serialVersionUID = 1L;

        public XmlLoadingException(Throwable cause) {
            super(cause);
        }

    }

}
 

Starting from XML Utilities version 1.2 there are resource-loading-related methods available:
...

    public static Document loadXmlFromResourceAsDocument12(Class<?> clazz, String name) throws XmlLoadingException {
        try {
            return XmlTools.loadDocumentFromResource(name, clazz);
        } catch (XmlUtilitiesException ex) {
            throw new XmlLoadingException(ex);
        }
    }

...
 

Conversions

XmlTools allows you to convert Document to Source or String.
The following method is part of the XmlLoading class from the example above:
    public static Source loadXmlFromResourceAsSource(Class<?> clazz, String name) throws NoSuchResourceException, XmlLoadingException {
        return XmlTools.documentToDomSource((loadXmlFromResourceAsDocument(clazz, name));
    }
 

Validation

Both, XmlUtilities and XmlTools allows you to validate specified XML file against specified Schema. The following class shows you, how to use the static variant:
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XmlTools;
import global.sandbox.xmlutilities.XmlUtilitiesException;
import javax.xml.transform.Source;
import org.w3c.dom.Document;

public class SchemaValidator {

    public static void validateXml(Source doc, Source schema) throws SchemaValidatorException, ValidationException {
        String result;

        try {
            result = XmlTools.validateXmlUsingSchema(doc, schema);
        } catch (XmlUtilitiesException ex) {
            throw new SchemaValidatorException(ex);
        }

        if (result != null) {
            throw new ValidationException(result);
        }
    }

    public static void validateXml(Document doc, Document schema) throws SchemaValidatorException, ValidationException {
        SchemaValidator.validateXml(XmlTools.documentToDomSource(doc), XmlTools.documentToDomSource(schema));
    }

    public static class SchemaValidatorException extends Exception {

        private static final long serialVersionUID = 1L;

        public SchemaValidatorException(Throwable cause) {
            super(cause);
        }

    }

    public static class ValidationException extends Exception {

        private static final long serialVersionUID = 1L;

        public ValidationException(String message) {
            super(message);
        }

    }

}
 

XPath Evaluation

The following code shows how to easily evaluate XPath query. The method loadAttribute evaluates specified query (the query should end with @xxx) and tries to convert obtained Node to Attr. We can also try to cast Node to Attr and catch the ClassCastException.
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.NamespaceContextImpl;
import global.sandbox.xmlutilities.XmlTools;
import global.sandbox.xmlutilities.XmlUtilitiesException;
import javax.xml.namespace.NamespaceContext;
import org.w3c.dom.Attr;
import org.w3c.dom.Element;
import org.w3c.dom.Node;

public class XPathEvaluation {

    final static NamespaceContext NAMESPACES;

    static {
        final NamespaceContextImpl nspaces = NamespaceContextImpl.namespaceContextWithDefaults();
        nspaces.addNamespace(
                "ns",
                "http://hadrabap.googlepages.com/projects/xmlutilities/demo");

        NAMESPACES = nspaces;
    }

    public static Attr loadAttribute(Element rootNode, String xPathQuery) throws XPathEvaluationException {
        Node node;
        try {
            node = XmlTools.getFirstNodeForXPath(
                    xPathQuery,
                    rootNode,
                    NAMESPACES);
        } catch (XmlUtilitiesException ex) {
            throw new XPathEvaluationException(ex);
        }

        if (node == null) {
            return null;
        }

        if (node.getNodeType() == Node.ATTRIBUTE_NODE) {
            return (Attr) node;
        } else {
            throw new XPathEvaluationException(String.format("Resulting node is not Attr, got %d.", node.getNodeType()));
        }
    }

    public static class XPathEvaluationException extends Exception {

        private static final long serialVersionUID = 1L;

        public XPathEvaluationException(String message) {
            super(message);
        }

        public XPathEvaluationException(Throwable cause) {
            super(cause);
        }

    }

}
 

As of version 1.2, generics are supported. The above code might be simplified as follows:
...

    public static Attr loadAttribute12(Element rootNode, String xPathQuery) throws XmlUtilitiesException {
        return XmlTools.getFirstNodeForXPath(
                xPathQuery,
                rootNode,
                NAMESPACES,
                Attr.class);
    }

...
 

Transformations

XmlUtilities and XmlTools also simplify transformations. They support Source-based and precompiled templates.
The following code demonstrates how to use the transformation support in XmlTools:
package global.sandbox.xmlutilities.demo;

import global.sandbox.xmlutilities.XmlTools;
import global.sandbox.xmlutilities.XmlUtilitiesException;
import org.w3c.dom.Document;

public class Transformations {

    public static Document transform(Document doc, Document xsl) throws TransformationsException {
        try {
            return XmlTools.transformToDocument(
                    XmlTools.documentToDomSource(xsl),
                    XmlTools.documentToDomSource(doc));
        } catch (XmlUtilitiesException ex) {
            throw new TransformationsException(ex);
        }
    }

    public static class TransformationsException extends Exception {

        private static final long serialVersionUID = 1L;

        public TransformationsException(Throwable cause) {
            super(cause);
        }

    }

}
 

For more details please check the test cases.

ChangeLog

ChangeLog
Version Changes
1.0
  • Initial release
1.1
  • Added support for name spaces
  • First public-domain release
1.2
  • Binary incompatible version
  • Removed dependency on Xerces and Xalan-J; moved to JDK6
  • Consolidated exception into single checked one
  • Generics support for XPath evaluation
  • Added support for output format properties
  • Improved stream and string conversion functions
  • Added stream and file writing functions
  • Store functionality (streams, files)
  • Added resource-loading functions



Copyright © 2006–2018. All rights reserved.