Package global.sandbox.xmlutilities
Utilities and Tools that makes XML parsing and validation more easier.
See:
Description
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 in
XmlTools
and
- Instance of
XmlUtilities
class.
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 |
|
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
- Added support for output format properties
- Improved stream and string conversion functions
- Added stream and file writing functions
- Added resource-loading functions
|
Copyright © 2006–2017. All rights reserved.