Package groovy.text

# Class XmlTemplateEngine

java.lang.Object
groovy.text.TemplateEngine
groovy.text.XmlTemplateEngine

public class XmlTemplateEngine extends TemplateEngine
Template engine for use in templating scenarios where both the template source and the expected output are intended to be XML.

Templates may use the normal '${expression}' and '$variable' notations to insert an arbitrary expression into the template. In addition, support is also provided for special tags: <gsp:scriptlet> (for inserting code fragments) and <gsp:expression> (for code fragments which produce output).

Comments and processing instructions will be removed as part of processing and special XML characters such as <, >, " and ' in the text of the template will be escaped using the respective XML notation. The output will also be indented using standard XML pretty printing.

That escaping is applied to the template as it is read, and deliberately not to the `${expression}` and `$variable` insertions, which have to survive as Groovy for the value to be computed at all. Whatever such an insertion produces is written as it stands: a value carrying `<` or `&` reaches the output as markup rather than as text, and can leave it neither well-formed nor what the template intended. Escape a value that may contain either, with `XmlUtil.escapeXml(String)` or otherwise, before binding it — always for a value that came from somewhere you do not control.

The xmlns namespace definition for `gsp:` tags will be removed but other namespace definitions will be preserved (but may change to an equivalent position within the XML tree).

Normally, the template source will be in a file but here is a simple example providing the XML template as a string:

     def binding = [firstname:"Jochen", lastname:"Theodorou",
                    nickname:"blackdrag", salutation:"Dear"]
     def engine = new groovy.text.XmlTemplateEngine()
     def text = '''\
     <?xml version="1.0" encoding="UTF-8"?>
     <document xmlns:gsp='http://groovy.codehaus.org/2005/gsp' xmlns:foo='baz' type='letter'>
       <gsp:scriptlet>def greeting = "${salutation}est"</gsp:scriptlet>
       <gsp:expression>greeting</gsp:expression>
       <foo:to>$firstname "$nickname" $lastname</foo:to>
       How are you today?
     </document>
     '''
     def template = engine.createTemplate(text).make(binding)
     println template.toString()

This example will produce this output:

     <document type='letter'>
     Dearest
     <foo:to xmlns:foo='baz'>
       Jochen &quot;blackdrag&quot; Theodorou
     </foo:to>
     How are you today?
     </document>

The XML template engine can also be used as the engine for `groovy.servlet.TemplateServlet` by placing the following in your web.xml file (plus a corresponding servlet-mapping element):

     <servlet>
       <servlet-name>XmlTemplate</servlet-name>
       <servlet-class>groovy.servlet.TemplateServlet</servlet-class>
       <init-param>
         <param-name>template.engine</param-name>
         <param-value>groovy.text.XmlTemplateEngine</param-value>
       </init-param>
     </servlet>

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_INDENTATION`
  Default indentation sequence used for pretty-printed XML output.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XmlTemplateEngine()`
  Creates an XML template engine using the default indentation and with XML validation disabled.
  `XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell)`
  Creates an XML template engine backed by the supplied parser and shell.
  `XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader)`
  Creates an XML template engine backed by the supplied parser and a `GroovyShell` built from the parent loader.
  `XmlTemplateEngine(String indentation, boolean validating)`
  Creates an XML template engine with custom indentation and validation settings.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Template`
  `createTemplate(Reader reader)`
  Parses XML template source from the supplied reader and compiles it into a template.
  `String`
  `getIndentation()`
  Returns the indentation string used for pretty-printed XML output.
  `void`
  `setConfigurePrinter(Closure configurePrinter)`
  Closure that can be used to configure the printer.
  `void`
  `setIndentation(String indentation)`
  Sets the indentation string used for pretty-printed XML output.
  `String`
  `toString()`
  Returns a concise engine name for diagnostics.

  ### Methods inherited from class groovy.text.TemplateEngine

  `createTemplate, createTemplate, createTemplate, createTemplate, createTemplate`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_INDENTATION

    public static final String DEFAULT_INDENTATION
    Default indentation sequence used for pretty-printed XML output.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### XmlTemplateEngine

    public XmlTemplateEngine() throws SAXException, ParserConfigurationException
    Creates an XML template engine using the default indentation and with XML validation disabled.
    Throws:
      `SAXException` - if the underlying parser cannot be configured
      `ParserConfigurationException` - if the XML parser cannot be created

  - ### XmlTemplateEngine

    public XmlTemplateEngine(String indentation, boolean validating) throws SAXException, ParserConfigurationException
    Creates an XML template engine with custom indentation and validation settings.
    Parameters:
      `indentation` - indentation string used when rendering nested XML nodes
      `validating` - `true` to enable XML validation while parsing templates
    Throws:
      `SAXException` - if the underlying parser cannot be configured
      `ParserConfigurationException` - if the XML parser cannot be created

  - ### XmlTemplateEngine

    public XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader)
    Creates an XML template engine backed by the supplied parser and a `GroovyShell` built from the parent loader.
    Parameters:
      `xmlParser` - parser used to read template XML
      `parentLoader` - class loader used to compile generated template scripts

  - ### XmlTemplateEngine

    public XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell)
    Creates an XML template engine backed by the supplied parser and shell.
    Parameters:
      `xmlParser` - parser used to read template XML
      `groovyShell` - shell used to compile generated template scripts

- ## Method Details

  - ### setConfigurePrinter

    public void setConfigurePrinter(Closure configurePrinter)
    Closure that can be used to configure the printer. The printer is passed as a parameter to the closure.

         new XmlTemplateEngine(configurePrinter: { it.preserveWhitespace = true })

  - ### createTemplate

    public Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException
    Parses XML template source from the supplied reader and compiles it into a template.
    Specified by:
      `createTemplate` in class `TemplateEngine`
    Parameters:
      `reader` - XML template source
    Returns:
      a compiled XML template
    Throws:
      `CompilationFailedException` - if Groovy fails to compile the generated template script
      `ClassNotFoundException` - if the generated template class cannot be instantiated
      `IOException` - if reading the XML template fails

  - ### getIndentation

    public String getIndentation()
    Returns the indentation string used for pretty-printed XML output.
    Returns:
      the indentation sequence, never `null`

  - ### setIndentation

    public void setIndentation(String indentation)
    Sets the indentation string used for pretty-printed XML output.
    Parameters:
      `indentation` - indentation sequence to use; `null` restores `DEFAULT_INDENTATION`

  - ### toString

    public String toString()
    Returns a concise engine name for diagnostics.
    Overrides:
      `toString` in class `Object`
    Returns:
      the literal engine name