Package org.daisy.dotify.common.xml

Class XMLTools

java.lang.Object

org.daisy.dotify.common.xml.XMLTools

public class XMLTools
extends Object

Provides some xml tools.

Method Summary

Modifier and Type	Method	Description
static Optional<Charset>	detectBomEncoding(byte[] data)	Tries to detect a Unicode encoding from the supplied data based on the presence of a BOM.
static String	detectXmlEncoding(byte[] data)	Detects XML encoding based on this algorithm: https://www.w3.org/TR/xml/#sec-guessing.
static Optional<String>	getDeclaredEncoding(String text)	Gets the declared encoding from the given string.
static boolean	isWellformedXML(File f)	Returns true if the specified file is well formed XML.
static boolean	isWellformedXML(URI uri)	Returns true if the contents at the specified URI is well formed XML.
static boolean	isWellformedXML(InputSource source)	Returns true if the specified source is well formed XML.
static XMLInfo	parseXML(File f)	Asserts that the specified file is well formed and returns some root node information.
static XMLInfo	parseXML(File f, boolean peek)	Returns some root node information and optionally asserts that the specified file is well formed.
static XMLInfo	parseXML(URI uri)	Asserts that the contents at the specified URI is well formed and returns some root node information.
static XMLInfo	parseXML(URI uri, boolean peek)	Returns some root node information and optionally asserts that the contents at the specified URI is well formed.
static XMLInfo	parseXML(InputSource source)	Asserts that the source is well formed and returns some root node information.
static XMLInfo	parseXML(InputSource source, boolean peek)	Returns some root node information and optionally asserts that the contents at the specified source is well formed.
static void	transform(Object source, Object result, Object xslt, Map<String,Object> params)	Transforms the xml with the specified parameters.
static void	transform(Object source, Object result, Object xslt, Map<String,Object> params, TransformerFactory factory)	Transforms the xml with the specified parameters.
static <T extends Exception> void	transform(Object source, Object result, Object xslt, TransformerEnvironment<T> env)	Transforms the xml with the specified parameters.
static void	transform(Source source, Result result, Source xslt, Map<String,Object> params)	Transforms the xml with the specified parameters.
static void	transform(Source source, Result result, Source xslt, Map<String,Object> params, TransformerFactory factory)	Transforms the xml with the specified parameters.
static <T extends Exception> void	transform(Source source, Result result, Source xslt, TransformerEnvironment<T> env)	Transforms the xml with the specified parameters.

Methods inherited from class java.lang.Object

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

Method Detail

getDeclaredEncoding

public static Optional<String> getDeclaredEncoding(String text)

Gets the declared encoding from the given string. If the string doesn't start with an XML declaration, an empty optional is returned.

Parameters:

text - the xml

Returns:

returns a string with the declared encoding

detectXmlEncoding

public static String detectXmlEncoding(byte[] data)
                                throws XmlEncodingDetectionException

Detects XML encoding based on this algorithm: https://www.w3.org/TR/xml/#sec-guessing. In accordance with this specification, it is assumed that the XML declaration is not preceded by whitespace (if present). Note that some encodings mentioned in the specification are not supported because they are not supported by the JVM.

Parameters:

data - the input bytes

Returns:

returns the name of the detected charset

Throws:

IllegalArgumentException - if the length of the data is less than 4 bytes

XmlEncodingMismatchException - if the declared encoding doesn't match the detected encoding and the detected encoding is an exact match

XmlEncodingDetectionException - if detection fails

detectBomEncoding

public static Optional<Charset> detectBomEncoding(byte[] data)

Tries to detect a Unicode encoding from the supplied data based on the presence of a BOM. If the file doesn't start with a BOM, an empty optional is returned.

Parameters:

data - the data to detect encoding on

Returns:

returns the encoding detected from the BOM

Throws:

UnsupportedCharsetException - if the charset could be detected but not created

transform

public static void transform(Object source,
                             Object result,
                             Object xslt,
                             Map<String,Object> params)
                      throws XMLToolsException

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

This method will attempt to create Source and Result objects from the supplied source, result and xslt objects. This process supports several types of objects from which Sources and Results are typically created, such as files, strings and URLs.

This method will create its own instance of a transformer factory.

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

params - xslt parameters

Throws:

XMLToolsException - if the transformation is unsuccessful

transform

public static void transform(Object source,
                             Object result,
                             Object xslt,
                             Map<String,Object> params,
                             TransformerFactory factory)
                      throws XMLToolsException

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

This method will attempt to create Source and Result objects from the supplied source, result and xslt objects. This process supports several types of objects from which Sources and Results are typically created, such as files, strings and URLs.

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

params - xslt parameters

factory - the transformer factory

Throws:

XMLToolsException - if the transformation is unsuccessful

transform

public static void transform(Source source,
                             Result result,
                             Source xslt,
                             Map<String,Object> params)
                      throws XMLToolsException

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

This method will create its own instance of a transformer factory.

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

params - xslt parameters

Throws:

XMLToolsException - if the transformation is unsuccessful

transform

public static void transform(Source source,
                             Result result,
                             Source xslt,
                             Map<String,Object> params,
                             TransformerFactory factory)
                      throws XMLToolsException

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

params - xslt parameters

factory - the transformer factory

Throws:

XMLToolsException - if the transformation is unsuccessful

transform

public static <T extends Exception> void transform(Object source,
                                                   Object result,
                                                   Object xslt,
                                                   TransformerEnvironment<T> env)
                                            throws T extends Exception

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

Type Parameters:

T - the type of exception thrown

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

env - the transformer environment

Throws:

T - if the transformation is unsuccessful

T extends Exception

transform

public static <T extends Exception> void transform(Source source,
                                                   Result result,
                                                   Source xslt,
                                                   TransformerEnvironment<T> env)
                                            throws T extends Exception

Transforms the xml with the specified parameters. By default, this method will set up a caching entity resolver, which will reduce the amount of fetching of dtd's from the Internet.

Type Parameters:

T - the type of exception thrown

Parameters:

source - the source xml

result - the result xml

xslt - the xslt

env - the transformer environment

Throws:

T - if the transformation is unsuccessful

T extends Exception

isWellformedXML

public static final boolean isWellformedXML(File f)
                                     throws XMLToolsException

Returns true if the specified file is well formed XML.

Parameters:

f - the file

Returns:

returns true if the file is well formed XML, false otherwise

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

isWellformedXML

public static final boolean isWellformedXML(URI uri)
                                     throws XMLToolsException

Returns true if the contents at the specified URI is well formed XML.

Parameters:

uri - the URI

Returns:

returns true if the contents at the specified URI is well formed XML, false otherwise

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

isWellformedXML

public static final boolean isWellformedXML(InputSource source)
                                     throws XMLToolsException

Returns true if the specified source is well formed XML.

Parameters:

source - the source

Returns:

returns true if the source is well formed XML, false otherwise

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(File f)
                              throws XMLToolsException

Asserts that the specified file is well formed and returns some root node information.

Parameters:

f - the file

Returns:

returns the root node, or null if file is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(URI uri)
                              throws XMLToolsException

Asserts that the contents at the specified URI is well formed and returns some root node information.

Parameters:

uri - the URI

Returns:

returns the root node, or null if the contents at the specified URI is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(InputSource source)
                              throws XMLToolsException

Asserts that the source is well formed and returns some root node information.

Parameters:

source - the source

Returns:

returns the root node, or null if the source is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(File f,
                                     boolean peek)
                              throws XMLToolsException

Returns some root node information and optionally asserts that the specified file is well formed.

Parameters:

f - the file

peek - true if the parsing should stop after reading the root element. If true, the file may or may not be well formed beyond the first start tag.

Returns:

returns the root node, or null if file is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(URI uri,
                                     boolean peek)
                              throws XMLToolsException

Returns some root node information and optionally asserts that the contents at the specified URI is well formed.

Parameters:

uri - the URI

peek - true if the parsing should stop after reading the root element. If true, the contents at the specified URI may or may not be well formed beyond the first start tag.

Returns:

returns the root node, or null if file is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails

parseXML

public static final XMLInfo parseXML(InputSource source,
                                     boolean peek)
                              throws XMLToolsException

Returns some root node information and optionally asserts that the contents at the specified source is well formed.

Parameters:

source - the source

peek - true if the parsing should stop after reading the root element. If true, the source may or may not be well formed beyond the first start tag.

Returns:

returns the root node, or null if file is not well formed

Throws:

XMLToolsException - if a parser cannot be configured or if parsing fails