0
# Apache Groovy Templates
1

2
Apache Groovy Templates provides a comprehensive template framework that enables dynamic text generation through multiple template engines. It includes SimpleTemplateEngine for basic JSP-style templates, StreamingTemplateEngine for handling large templates, GStringTemplateEngine for closure-based templating, XmlTemplateEngine for XML template processing, and MarkupTemplateEngine as an optimized solution for markup generation.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy-templates
7
- **Package Type**: Maven
8
- **Language**: Java/Groovy
9
- **Installation**: `implementation 'org.apache.groovy:groovy-templates:5.0.0'` (Gradle) or `<dependency><groupId>org.apache.groovy</groupId><artifactId>groovy-templates</artifactId><version>5.0.0</version></dependency>` (Maven)
10

11
## Core Imports
12

13
```java
14
import groovy.text.*;
15
import groovy.text.markup.*;
16
```
17

18
Common imports for specific engines:
19

20
```java
21
import groovy.text.SimpleTemplateEngine;
22
import groovy.text.StreamingTemplateEngine;
23
import groovy.text.GStringTemplateEngine;
24
import groovy.text.XmlTemplateEngine;
25
import groovy.text.markup.MarkupTemplateEngine;
26
import groovy.text.markup.TemplateConfiguration;
27
import groovy.text.markup.BaseTemplate;
28
import groovy.text.markup.TemplateResolver;
29
import groovy.text.markup.DelegatingIndentWriter;
30
```
31

32
Exception handling imports:
33

34
```java
35
import groovy.text.TemplateExecutionException;
36
import groovy.text.TemplateParseException;
37
```
38

39
Groovy core imports commonly needed:
40

41
```java
42
import groovy.lang.Writable;
43
import groovy.lang.Closure;
44
import groovy.util.XmlParser;
45
import groovy.lang.GroovyShell;
46
import org.codehaus.groovy.control.CompilerConfiguration;
47
import org.codehaus.groovy.control.CompilationFailedException;
48
```
49

50
## Basic Usage
51

52
```java
53
import groovy.text.SimpleTemplateEngine;
54
import groovy.text.Template;
55
import groovy.lang.Writable;
56
import java.util.Map;
57
import java.util.HashMap;
58

59
// Create a simple template engine
60
SimpleTemplateEngine engine = new SimpleTemplateEngine();
61

62
// Template with JSP-style syntax
63
String templateText = """
64
Dear <%= firstname %> $lastname,
65

66
We <% if (accepted) print 'are pleased' else print 'regret' %> 
67
to inform you that your paper entitled
68
'$title' was ${ accepted ? 'accepted' : 'rejected' }.
69

70
The conference committee.
71
""";
72

73
// Create template from string
74
Template template = engine.createTemplate(templateText);
75

76
// Create binding data
77
Map<String, Object> binding = new HashMap<>();
78
binding.put("firstname", "Grace");
79
binding.put("lastname", "Hopper");
80
binding.put("accepted", true);
81
binding.put("title", "Groovy for COBOL programmers");
82

83
// Generate output
84
Writable result = template.make(binding);
85
System.out.println(result.toString());
86
```
87

88
## Architecture
89

90
Apache Groovy Templates is built around several key components:
91

92
- **TemplateEngine**: Abstract base class providing factory methods for creating templates from various sources
93
- **Template**: Interface representing compiled templates that can be bound to data
94
- **Template Engines**: Five specialized implementations optimized for different use cases
95
- **Exception Handling**: Comprehensive error reporting with line number information for debugging
96
- **Configuration System**: Advanced configuration options for the MarkupTemplateEngine
97

98
## Capabilities
99

100
### Simple Template Engine
101

102
Basic JSP-style template engine supporting `<% %>` scriptlets and `<%= %>` expressions, ideal for simple templating scenarios.
103

104
```java { .api }
105
public class SimpleTemplateEngine extends TemplateEngine {
106
    public SimpleTemplateEngine();
107
    public SimpleTemplateEngine(boolean verbose);
108
    public SimpleTemplateEngine(ClassLoader parentLoader);
109
    public SimpleTemplateEngine(GroovyShell groovyShell);
110
    
111
    public void setVerbose(boolean verbose);
112
    public boolean isVerbose();
113
    public void setEscapeBackslash(boolean escapeBackslash);
114
    public boolean isEscapeBackslash();
115
}
116
```
117

118
[Simple Templates](./simple-templates.md)
119

120
### Streaming Template Engine
121

122
Closure-based template engine optimized for large templates (>64k characters) with enhanced error reporting and scalable performance.
123

124
```java { .api }
125
public class StreamingTemplateEngine extends TemplateEngine {
126
    public StreamingTemplateEngine();
127
    public StreamingTemplateEngine(ClassLoader parentLoader);
128
}
129
```
130

131
[Streaming Templates](./streaming-templates.md)
132

133
### GString Template Engine
134

135
Template engine using GString closures for streaming scenarios, providing efficient template storage and execution.
136

137
```java { .api }
138
public class GStringTemplateEngine extends TemplateEngine {
139
    public GStringTemplateEngine();
140
    public GStringTemplateEngine(ClassLoader parentLoader);
141
}
142
```
143

144
[GString Templates](./gstring-templates.md)
145

146
### XML Template Engine
147

148
Specialized template engine for XML templates with `<gsp:scriptlet>` and `<gsp:expression>` support, including automatic XML escaping and indentation.
149

150
```java { .api }
151
public class XmlTemplateEngine extends TemplateEngine {
152
    public static final String DEFAULT_INDENTATION = "  ";
153
    
154
    public XmlTemplateEngine() throws SAXException, ParserConfigurationException;
155
    public XmlTemplateEngine(String indentation, boolean validating) throws SAXException, ParserConfigurationException;
156
    public XmlTemplateEngine(XmlParser xmlParser, ClassLoader parentLoader);
157
    public XmlTemplateEngine(XmlParser xmlParser, GroovyShell groovyShell);
158
    
159
    public String getIndentation();
160
    public void setIndentation(String indentation);
161
    public void setConfigurePrinter(Closure configurePrinter);
162
}
163
```
164

165
[XML Templates](./xml-templates.md)
166

167
### Markup Template Engine
168

169
Advanced template engine leveraging StreamingMarkupBuilder for optimized XML/XHTML generation with compile-time type checking and extensive configuration options.
170

171
```java { .api }
172
public class MarkupTemplateEngine extends TemplateEngine {
173
    public MarkupTemplateEngine();
174
    public MarkupTemplateEngine(TemplateConfiguration config);
175
    public MarkupTemplateEngine(ClassLoader parentLoader, TemplateConfiguration config);
176
    public MarkupTemplateEngine(ClassLoader parentLoader, TemplateConfiguration config, TemplateResolver resolver);
177
    public MarkupTemplateEngine(ClassLoader parentLoader, File templateDirectory, TemplateConfiguration tplConfig);
178
    
179
    public Template createTemplate(Reader reader, String sourceName) throws CompilationFailedException, ClassNotFoundException, IOException;
180
    public Template createTemplateByPath(String templatePath) throws CompilationFailedException, ClassNotFoundException, IOException;
181
    
182
    // Type-checked template methods
183
    public Template createTypeCheckedModelTemplate(String source, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
184
    public Template createTypeCheckedModelTemplate(String source, String sourceName, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
185
    public Template createTypeCheckedModelTemplate(Reader reader, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
186
    public Template createTypeCheckedModelTemplate(Reader reader, String sourceName, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
187
    public Template createTypeCheckedModelTemplateByPath(String templatePath, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
188
    public Template createTypeCheckedModelTemplate(URL resource, Map<String, String> modelTypes) throws CompilationFailedException, ClassNotFoundException, IOException;
189
    
190
    // Utility methods
191
    public GroovyClassLoader getTemplateLoader();
192
    public CompilerConfiguration getCompilerConfiguration();
193
    public TemplateConfiguration getTemplateConfiguration();
194
    public URL resolveTemplate(String templatePath) throws IOException;
195
}
196
```
197

198
[Markup Templates](./markup-templates.md)
199

200
## Core Interfaces
201

202
### Template Engine Base Class
203

204
Abstract base class providing template creation methods from various sources.
205

206
```java { .api }
207
public abstract class TemplateEngine {
208
    public abstract Template createTemplate(Reader reader) throws CompilationFailedException, ClassNotFoundException, IOException;
209
    public Template createTemplate(String templateText) throws CompilationFailedException, ClassNotFoundException, IOException;
210
    public Template createTemplate(File file) throws CompilationFailedException, ClassNotFoundException, IOException;
211
    public Template createTemplate(File file, Charset cs) throws CompilationFailedException, ClassNotFoundException, IOException;
212
    public Template createTemplate(URL url) throws CompilationFailedException, ClassNotFoundException, IOException;
213
    public Template createTemplate(URL url, Charset cs) throws CompilationFailedException, ClassNotFoundException, IOException;
214
}
215
```
216

217
### Template Interface
218

219
Interface for compiled templates that can be bound to data and rendered.
220

221
```java { .api }
222
public interface Template {
223
    Writable make();
224
    Writable make(Map binding);
225
}
226
```
227

228
## Exception Handling
229

230
### Template Execution Exception
231

232
Exception thrown during template execution with line number information.
233

234
```java { .api }
235
public class TemplateExecutionException extends Exception {
236
    public TemplateExecutionException(int lineNumber);
237
    public TemplateExecutionException(int lineNumber, String message);
238
    public TemplateExecutionException(int lineNumber, String message, Throwable cause);
239
    public TemplateExecutionException(int lineNumber, Throwable cause);
240
    
241
    public int getLineNumber();
242
}
243
```
244

245
### Template Parse Exception
246

247
Runtime exception thrown during template parsing with detailed location information.
248

249
```java { .api }
250
public class TemplateParseException extends RuntimeException {
251
    public TemplateParseException(int lineNumber, int column);
252
    public TemplateParseException(String message, int lineNumber, int column);
253
    public TemplateParseException(String message, Throwable cause, int lineNumber, int column);
254
    public TemplateParseException(Throwable t, int lineNumber, int column);
255
    
256
    public int getLineNumber();
257
    public int getColumn();
258
}
259
```