Java : Transformer (XML) with Examples

Transformer (Java SE 17 & JDK 17) API Examples.
You will find code examples on most Transformer methods.


Summary

An instance of this abstract class can transform a source tree into a result tree.

Class diagram

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var text = document.createTextNode("abcd");
root.appendChild(text);

final var factory = TransformerFactory.newInstance();
final var transformer = factory.newTransformer();

final var source = new DOMSource(document);
final var result = new StreamResult(new StringWriter());
transformer.transform(source, result);

//<?xml version="1.0" encoding="UTF-8" standalone="no"?><root>abcd</root>
System.out.println(result.getWriter());

Constructors

Transformer ()

Default constructor is protected on purpose.

I think it's rare to create a subclass of Transformer. Therefore, the code example is omitted.

Methods

abstract void clearParameters ()

Clear all parameters set with setParameter.

final var xml = """
        <root/>
        """;

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var xsl = """
        <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
          <xsl:output omit-xml-declaration="yes" />
          <xsl:param name="param">aaaa</xsl:param>

          <xsl:template match="root">
            <xsl:copy-of select="$param" />
          </xsl:template>

        </xsl:stylesheet>
        """;

final var factory = TransformerFactory.newInstance();
final var transformer = factory.newTransformer(
        new StreamSource(new ByteArrayInputStream(xsl.getBytes())));

System.out.println(transformer.getParameter("param")); // null
transformer.setParameter("param", "bbbb");

{
    System.out.println(transformer.getParameter("param")); // bbbb

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //bbbb
    System.out.println(result.getWriter());
}

transformer.clearParameters();

{
    System.out.println(transformer.getParameter("param")); // null

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //aaaa
    System.out.println(result.getWriter());
}

abstract ErrorListener getErrorListener ()

Get the error event handler in effect for the transformation.

// An XML for errors.
final var xml = """
        <root>
            <<<child>aaa</child>
        </root>
        """;

final var factory = TransformerFactory.newInstance();
final var transformer = factory.newTransformer();

final var listener = new ErrorListener() {
    @Override
    public void warning(TransformerException exception) {
        System.out.println("-- ErrorListener warning --");
        System.out.println(exception);
    }

    @Override
    public void error(TransformerException exception) {
        System.out.println("-- ErrorListener error --");
        System.out.println(exception);
    }

    @Override
    public void fatalError(TransformerException exception) {
        System.out.println("-- ErrorListener fatalError --");
        System.out.println(exception);
    }
};

transformer.setErrorListener(listener);
System.out.println(listener == transformer.getErrorListener()); // true

final var source = new StreamSource(new ByteArrayInputStream(xml.getBytes()));
final var result = new StreamResult(new StringWriter());

try {
    transformer.transform(source, result);
} catch (TransformerException e) {
    System.out.println("-- TransformerException --");
    System.out.println(e);
}

// Result
// ↓
//-- ErrorListener error --
//javax.xml.transform.TransformerException:
// The content of elements must consist of well-formed character data or markup.
//-- TransformerException --
//javax.xml.transform.TransformerException:
// org.xml.sax.SAXParseException; lineNumber: 2; columnNumber: 6;
// The content of elements must consist of well-formed character data or markup.

abstract Properties getOutputProperties ()

Get a copy of the output properties for the transformation.

final var xml = """
        <root><child>aaa</child></root>
        """;

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var transformer = TransformerFactory.newInstance().newTransformer();

{
    final var ret = transformer.getOutputProperties();
    System.out.println(ret.size()); // 0

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<?xml version="1.0" encoding="UTF-8" standalone="no"?><root><child>aaa</child></root>
    System.out.println(result.getWriter());
}

final var properties = new Properties();
properties.setProperty(OutputKeys.INDENT, "yes");
properties.setProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

transformer.setOutputProperties(properties);

{
    final var ret = transformer.getOutputProperties();
    System.out.println(ret); // {indent=yes, omit-xml-declaration=yes}

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<root>
    //    <child>aaa</child>
    //</root>
    System.out.println(result.getWriter());
}

abstract String getOutputProperty (String name)

Get an output property that is in effect for the transformer.

final var xml = """
        <root><child>aaa</child></root>
        """;

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.parse(new ByteArrayInputStream(xml.getBytes()));

final var transformer = TransformerFactory.newInstance().newTransformer();

{
    System.out.println(transformer.getOutputProperty(OutputKeys.INDENT)); // "no"
    System.out.println(transformer.getOutputProperty(OutputKeys.OMIT_XML_DECLARATION)); // "no"

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<?xml version="1.0" encoding="UTF-8" standalone="no"?><root><child>aaa</child></root>
    System.out.println(result.getWriter());
}

transformer.setOutputProperty(OutputKeys.INDENT, "yes");
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

{
    System.out.println(transformer.getOutputProperty(OutputKeys.INDENT)); // "yes"
    System.out.println(transformer.getOutputProperty(OutputKeys.OMIT_XML_DECLARATION)); // "yes"

    final var source = new DOMSource(document);
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<root>
    //    <child>aaa</child>
    //</root>
    System.out.println(result.getWriter());
}

abstract Object getParameter (String name)

Get a parameter that was explicitly set with setParameter.

Please see clearParameters().

abstract URIResolver getURIResolver ()

Get an object that will be used to resolve URIs used in document().

final var sampleA = Path.of("R:", "java-work", "sample-a.xml");
System.out.println(sampleA); // R:\java-work\sample-a.xml

Files.writeString(sampleA, """
        <root>aaa</root>
        """);

final var sampleB = Path.of("R:", "java-work", "sample-b.xml");
System.out.println(sampleB); // R:\java-work\sample-b.xml

Files.writeString(sampleB, """
        <root>bbb</root>
        """);

final var xml = """
        <root/>
        """;

final var xsl = """
        <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
          <xsl:output omit-xml-declaration="yes" />
          <xsl:variable name="doc" select="document('file:///R:/java-work/sample-a.xml')" />

          <xsl:template match="/">
            <xsl:copy-of select="$doc" />
          </xsl:template>

        </xsl:stylesheet>
        """;

final var factory = TransformerFactory.newInstance();
final var transformer = factory.newTransformer(
        new StreamSource(new ByteArrayInputStream(xsl.getBytes())));

{
    System.out.println(transformer.getURIResolver()); // null

    final var source = new StreamSource(new ByteArrayInputStream(xml.getBytes()));
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<root>aaa</root>
    System.out.println(result.getWriter());
}

final var urlResolver = new URIResolver() {
    @Override
    public Source resolve(String href, String base) {
        if ("file:///R:/java-work/sample-a.xml".equals(href)) {
            return new StreamSource("file:///R:/java-work/sample-b.xml");
        }

        return null;
    }
};

transformer.setURIResolver(urlResolver);

{
    System.out.println(transformer.getURIResolver() == urlResolver); // true

    final var source = new StreamSource(new ByteArrayInputStream(xml.getBytes()));
    final var result = new StreamResult(new StringWriter());
    transformer.transform(source, result);

    //<root>bbb</root>
    System.out.println(result.getWriter());
}

void reset ()

Reset this Transformer to its original configuration.

final var transformer = TransformerFactory.newInstance().newTransformer();

transformer.setParameter("param", "bbbb");
transformer.setOutputProperty(OutputKeys.INDENT, "yes");
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

System.out.println(transformer.getParameter("param")); // "bbbb"
System.out.println(transformer.getOutputProperty(OutputKeys.INDENT)); // "yes"
System.out.println(transformer.getOutputProperty(OutputKeys.OMIT_XML_DECLARATION)); // "yes"

transformer.reset();

System.out.println(transformer.getParameter("param")); // null
System.out.println(transformer.getOutputProperty(OutputKeys.INDENT)); // "no"
System.out.println(transformer.getOutputProperty(OutputKeys.OMIT_XML_DECLARATION)); // "no"

abstract void setErrorListener (ErrorListener listener)

Set the error event listener in effect for the transformation.

Please see getErrorListener().

abstract void setOutputProperties (Properties oformat)

Set the output properties for the transformation.

Please see getOutputProperties().

abstract void setOutputProperty (String name, String value)

Set an output property that will be in effect for the transformation.

Please see getOutputProperty(String name).

abstract void setParameter (String name, Object value)

Add a parameter for the transformation.

Please see clearParameters().

abstract void setURIResolver (URIResolver resolver)

Set an object that will be used to resolve URIs used in document().

Please see getURIResolver().

abstract void transform (Source xmlSource, Result outputTarget)

Transform the XML Source to a Result.

// DOM → XML String

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var text = document.createTextNode("abcd");
root.appendChild(text);

final var transformer = TransformerFactory.newInstance().newTransformer();
transformer.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "yes");

final var source = new DOMSource(document);
final var result = new StreamResult(new StringWriter());
transformer.transform(source, result);

//<root>abcd</root>
System.out.println(result.getWriter());
// XML String → XSL

final var xml = """
        <root>abcd</root>
        """;

final var xsl = """
        <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
          <xsl:output omit-xml-declaration="yes" />

          <xsl:template match="/">012<xsl:value-of select="." />XYZ</xsl:template>

        </xsl:stylesheet>
        """;

final var transformer = TransformerFactory.newInstance().newTransformer(
        new StreamSource(new ByteArrayInputStream(xsl.getBytes())));

final var source = new StreamSource(new ByteArrayInputStream(xml.getBytes()));
final var result = new StreamResult(new StringWriter());
transformer.transform(source, result);

//012abcdXYZ
System.out.println(result.getWriter());
// DOM → SAX

final var builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
final var document = builder.newDocument();

final var root = document.createElement("root");
document.appendChild(root);

final var text = document.createTextNode("abcd");
root.appendChild(text);

final var transformer = TransformerFactory.newInstance().newTransformer();

final var handler = new DefaultHandler() {

    @Override
    public void startElement(String uri, String localName, String qName, Attributes attributes) {
        System.out.println("startElement : " + qName);
    }

    @Override
    public void endElement(String uri, String localName, String qName) {
        System.out.println("endElement : " + qName);
    }

    @Override
    public void characters(char[] ch, int start, int length) {
        System.out.println("text : " + new String(ch, start, length));
    }
};

final var source = new DOMSource(document);
final var result = new SAXResult(handler);

//startElement : root
//text : abcd
//endElement : root
transformer.transform(source, result);

Related posts

To top of page