0
# Apache FreeMarker
1

2
Apache FreeMarker is a template engine: a Java library to generate text output (HTML web pages, e-mails, configuration files, source code, etc.) based on templates and changing data. FreeMarker provides a powerful templating language with features like variable substitution, conditional logic, loops, macros, and built-in functions for processing collections, strings, numbers, and dates.
3

4
## Package Information
5

6
- **Package Name**: org.freemarker:freemarker
7
- **Package Type**: Maven (Java)
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.freemarker</groupId>
13
    <artifactId>freemarker</artifactId>
14
    <version>2.3.34</version>
15
  </dependency>
16
  ```
17
  
18
  Gradle:
19
  ```gradle
20
  implementation 'org.freemarker:freemarker:2.3.34'
21
  ```
22

23
## Core Imports
24

25
```java
26
import freemarker.template.Configuration;
27
import freemarker.template.Template;
28
import freemarker.template.TemplateException;
29
import freemarker.template.Version;
30
```
31

32
## Basic Usage
33

34
```java
35
import freemarker.template.*;
36
import java.io.*;
37
import java.util.*;
38

39
// Create and configure FreeMarker
40
Configuration cfg = new Configuration(Configuration.VERSION_2_3_34);
41
cfg.setDirectoryForTemplateLoading(new File("templates"));
42
cfg.setDefaultEncoding("UTF-8");
43

44
// Create data model
45
Map<String, Object> dataModel = new HashMap<>();
46
dataModel.put("user", "John Doe");
47
dataModel.put("items", Arrays.asList("Apple", "Banana", "Cherry"));
48

49
// Get template and process
50
Template template = cfg.getTemplate("hello.ftl");
51
Writer out = new StringWriter();
52
template.process(dataModel, out);
53

54
System.out.println(out.toString());
55
```
56

57
## Architecture
58

59
FreeMarker follows a clean separation between:
60
- **Configuration**: Global settings and template loading setup
61
- **Template**: Parsed template ready for processing  
62
- **Data Model**: Java objects exposed to templates via ObjectWrapper
63
- **Environment**: Processing context with template execution state
64

65
## Capabilities
66

67
### Core Template Processing
68

69
Essential classes and methods for template loading, configuration, and processing.
70

71
```java { .api }
72
// Main configuration class
73
class Configuration {
74
  Configuration(Version incompatibleImprovements);
75
  Template getTemplate(String name) throws IOException;
76
  Template getTemplate(String name, Locale locale) throws IOException;
77
  Template getTemplate(String name, Locale locale, String encoding) throws IOException;
78
  void setDirectoryForTemplateLoading(File dir) throws IOException;
79
  void setClassForTemplateLoading(Class resourceLoaderClass, String basePackagePath);
80
  void setTemplateLoader(TemplateLoader templateLoader);
81
  void setObjectWrapper(ObjectWrapper objectWrapper);
82
  void setDefaultEncoding(String encoding);
83
  void setLocale(Locale locale);
84
  void setTimeZone(TimeZone timeZone);
85
  void setOutputFormat(OutputFormat outputFormat);
86
  void setSetting(String name, String value) throws TemplateException;
87
  Version getVersion();
88
}
89

90
// Template representation
91
class Template {
92
  Template(String name, Reader reader, Configuration cfg) throws IOException;
93
  void process(Object dataModel, Writer out) throws TemplateException, IOException;
94
  void process(Object dataModel, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException;
95
  Environment createProcessingEnvironment(Object dataModel, Writer out) throws TemplateException, IOException;
96
  String getName();
97
  String getEncoding();
98
  Configuration getConfiguration();
99
}
100

101
// Processing environment
102
class Environment {
103
  void process() throws TemplateException, IOException;
104
  void include(Template template) throws TemplateException, IOException;
105
  TemplateHashModel getCurrentNamespace() throws TemplateException;
106
  TemplateHashModel getMainNamespace();
107
  void setGlobalVariable(String name, TemplateModel model) throws TemplateException;
108
  TemplateModel getGlobalVariable(String name) throws TemplateException;
109
  Object getDataModel();
110
  Writer getOut();
111
}
112
```
113

114
[Core Template Processing](./core-processing.md)
115

116
### Template Model System
117

118
Interfaces for representing different data types in templates, enabling seamless integration between Java objects and FreeMarker templates.
119

120
```java { .api }
121
// Base interface for all template values
122
interface TemplateModel {
123
  TemplateModel NOTHING = GeneralPurposeNothing.INSTANCE;
124
}
125

126
// String values
127
interface TemplateScalarModel extends TemplateModel {
128
  String getAsString() throws TemplateModelException;
129
}
130

131
// Numeric values  
132
interface TemplateNumberModel extends TemplateModel {
133
  Number getAsNumber() throws TemplateModelException;
134
}
135

136
// Boolean values
137
interface TemplateBooleanModel extends TemplateModel {
138
  boolean getAsBoolean() throws TemplateModelException;
139
  TemplateBooleanModel TRUE = TrueBooleanModel.INSTANCE;
140
  TemplateBooleanModel FALSE = FalseBooleanModel.INSTANCE;
141
}
142

143
// Date/time values
144
interface TemplateDateModel extends TemplateModel {
145
  Date getAsDate() throws TemplateModelException;
146
  int getDateType();
147
  int DATE = 1;
148
  int TIME = 2; 
149
  int DATETIME = 3;
150
  int UNKNOWN = 0;
151
}
152

153
// Sequence/list access
154
interface TemplateSequenceModel extends TemplateModel {
155
  TemplateModel get(int index) throws TemplateModelException;
156
  int size() throws TemplateModelException;
157
}
158

159
// Hash/map access
160
interface TemplateHashModel extends TemplateModel {
161
  TemplateModel get(String key) throws TemplateModelException;
162
  boolean isEmpty() throws TemplateModelException;
163
}
164
```
165

166
[Template Model System](./template-models.md)
167

168
### Object Wrapping
169

170
Convert Java objects to TemplateModel objects for use in templates.
171

172
```java { .api }
173
// Core object wrapper interface
174
interface ObjectWrapper {
175
  TemplateModel wrap(Object obj) throws TemplateModelException;
176
}
177

178
// Default object wrapper with comprehensive Java object support
179
class DefaultObjectWrapper extends BeansWrapper {
180
  DefaultObjectWrapper(Version incompatibleImprovements);
181
  static DefaultObjectWrapper getDefaultInstance();
182
}
183

184
// Builder for creating configured DefaultObjectWrapper instances
185
class DefaultObjectWrapperBuilder {
186
  DefaultObjectWrapperBuilder(Version incompatibleImprovements);
187
  DefaultObjectWrapper build();
188
  DefaultObjectWrapperBuilder setExposeFields(boolean exposeFields);
189
  DefaultObjectWrapperBuilder setForceLegacyNonListCollections(boolean force);
190
}
191

192
// Bean wrapper for Java beans with property and method access
193
class BeansWrapper implements RichObjectWrapper {
194
  BeansWrapper(Version incompatibleImprovements);
195
  TemplateHashModel getStaticModels();
196
  TemplateHashModel getEnumModels();
197
  void setExposeFields(boolean exposeFields);
198
  void setMethodAppearanceFineTuner(MethodAppearanceFineTuner tuner);
199
  TemplateModel unwrap(TemplateModel model) throws TemplateModelException;
200
}
201
```
202

203
[Object Wrapping](./object-wrapping.md)
204

205
### Template Caching and Loading
206

207
Control how templates are loaded, cached, and resolved from various sources.
208

209
```java { .api }
210
// Core template loading interface
211
interface TemplateLoader {
212
  Object findTemplateSource(String name) throws IOException;
213
  long getLastModified(Object templateSource);
214
  Reader getReader(Object templateSource, String encoding) throws IOException;
215
  void closeTemplateSource(Object templateSource) throws IOException;
216
}
217

218
// File system template loading
219
class FileTemplateLoader implements TemplateLoader {
220
  FileTemplateLoader(File baseDir) throws IOException;
221
  FileTemplateLoader(File baseDir, boolean disableCanonicalization) throws IOException;
222
}
223

224
// Classpath template loading
225
class ClassTemplateLoader extends URLTemplateLoader {
226
  ClassTemplateLoader(Class resourceLoaderClass, String basePackagePath);
227
}
228

229
// In-memory string template loading
230
class StringTemplateLoader implements TemplateLoader {
231
  StringTemplateLoader();
232
  void putTemplate(String name, String templateSource);
233
  void removeTemplate(String name);
234
}
235

236
// Cache storage interface
237
interface CacheStorage {
238
  Object get(Object key);
239
  void put(Object key, Object value);
240
  void remove(Object key);
241
  void clear();
242
}
243
```
244

245
[Template Caching and Loading](./caching-loading.md)
246

247
### Extensions and Integration
248

249
Extend FreeMarker with custom functionality and integrate with external systems.
250

251
```java { .api }
252
// Custom directive interface
253
interface TemplateDirectiveModel extends TemplateModel {
254
  void execute(Environment env, Map params, TemplateModel[] loopVars, 
255
               TemplateDirectiveBody body) throws TemplateException, IOException;
256
}
257

258
// Custom method interface
259
interface TemplateMethodModelEx extends TemplateMethodModel {
260
  Object exec(List arguments) throws TemplateModelException;
261
}
262

263
// Text transformation interface
264
interface TemplateTransformModel extends TemplateModel {
265
  Writer getWriter(Writer out, Map args) throws TemplateModelException, IOException;
266
}
267

268
// XML/DOM node model
269
class NodeModel implements TemplateNodeModel, TemplateHashModel, TemplateSequenceModel {
270
  static NodeModel wrap(Node node);
271
  static NodeModel parse(InputSource is) throws SAXException, IOException, ParserConfigurationException;
272
  Node getNode();
273
  String getNodeName() throws TemplateModelException;
274
  String getNodeType() throws TemplateModelException;
275
}
276
```
277

278
[Extensions and Integration](./extensions.md)
279

280
### Output Formats and Escaping
281

282
Control output formatting and automatic escaping for different content types.
283

284
```java { .api }
285
// Base output format
286
abstract class OutputFormat {
287
  abstract String getName();
288
  abstract String getMimeType();
289
  abstract boolean isOutputFormatMixingAllowed(OutputFormat otherOutputFormat);
290
}
291

292
// HTML output format with automatic escaping
293
class HTMLOutputFormat extends CommonMarkupOutputFormat {
294
  static final HTMLOutputFormat INSTANCE;
295
}
296

297
// XML output format
298
class XMLOutputFormat extends CommonMarkupOutputFormat {
299
  static final XMLOutputFormat INSTANCE;
300
}
301

302
// Plain text (no escaping)
303
class PlainTextOutputFormat extends OutputFormat {
304
  static final PlainTextOutputFormat INSTANCE;
305
}
306
```
307

308
[Output Formats and Escaping](./output-formats.md)
309

310
### Exception Handling
311

312
Handle template processing errors and exceptions.
313

314
```java { .api }
315
// Base template exception
316
class TemplateException extends Exception {
317
  TemplateException(String description, Environment env);
318
  TemplateException(String description, Environment env, Throwable cause);
319
  String getFTLInstructionStack();
320
  int getLineNumber();
321
  int getColumnNumber();
322
  String getTemplateName();
323
}
324

325
// Template model exceptions
326
class TemplateModelException extends TemplateException {
327
  TemplateModelException(String description);
328
  TemplateModelException(String description, Throwable cause);
329
}
330

331
// Exception handler interface
332
interface TemplateExceptionHandler {
333
  void handleTemplateException(TemplateException te, Environment env, Writer out) 
334
    throws TemplateException;
335
  
336
  TemplateExceptionHandler IGNORE_HANDLER = IgnoreTemplateExceptionHandler.INSTANCE;
337
  TemplateExceptionHandler DEBUG_HANDLER = DebugTemplateExceptionHandler.INSTANCE;
338
  TemplateExceptionHandler HTML_DEBUG_HANDLER = HtmlDebugTemplateExceptionHandler.INSTANCE;
339
  TemplateExceptionHandler RETHROW_HANDLER = RethrowTemplateExceptionHandler.INSTANCE;
340
}
341
```
342

343
[Exception Handling](./exception-handling.md)
344

345
## Types
346

347
```java { .api }
348
// Version information
349
class Version implements Serializable {
350
  Version(String version) throws NumberFormatException;
351
  Version(int major, int minor, int micro);
352
  int getMajor();
353
  int getMinor();
354
  int getMicro();
355
  String toString();
356
  static final Version VERSION_2_3_0 = new Version(2, 3, 0);
357
  static final Version VERSION_2_3_19 = new Version(2, 3, 19);
358
  static final Version VERSION_2_3_20 = new Version(2, 3, 20);
359
  static final Version VERSION_2_3_21 = new Version(2, 3, 21);
360
  static final Version VERSION_2_3_22 = new Version(2, 3, 22);
361
  static final Version VERSION_2_3_23 = new Version(2, 3, 23);
362
  static final Version VERSION_2_3_24 = new Version(2, 3, 24);
363
  static final Version VERSION_2_3_25 = new Version(2, 3, 25);
364
  static final Version VERSION_2_3_26 = new Version(2, 3, 26);
365
  static final Version VERSION_2_3_27 = new Version(2, 3, 27);
366
  static final Version VERSION_2_3_28 = new Version(2, 3, 28);
367
  static final Version VERSION_2_3_29 = new Version(2, 3, 29);
368
  static final Version VERSION_2_3_30 = new Version(2, 3, 30);
369
  static final Version VERSION_2_3_31 = new Version(2, 3, 31);
370
  static final Version VERSION_2_3_32 = new Version(2, 3, 32);
371
  static final Version VERSION_2_3_33 = new Version(2, 3, 33);
372
  static final Version VERSION_2_3_34 = new Version(2, 3, 34);
373
  static final Version DEFAULT_INCOMPATIBLE_IMPROVEMENTS = Configuration.VERSION_2_3_0;
374
}
375

376
// Template directive body for custom directives
377
interface TemplateDirectiveBody {
378
  void render(Writer out) throws TemplateException, IOException;
379
}
380

381
// Iterator for template models
382
interface TemplateModelIterator {
383
  TemplateModel next() throws TemplateModelException;
384
  boolean hasNext() throws TemplateModelException;
385
}
386

387
// Key-value pair for hash iteration
388
interface KeyValuePair {
389
  TemplateModel getKey() throws TemplateModelException;
390
  TemplateModel getValue() throws TemplateModelException;
391
}
392

393
// Configuration interface for configurable objects
394
abstract class Configurable {
395
  void setSetting(String name, String value) throws TemplateException;
396
  String getSetting(String key);
397
  void setLocale(Locale locale);
398
  Locale getLocale();
399
  void setTimeZone(TimeZone timeZone);
400
  TimeZone getTimeZone();
401
  void setOutputFormat(OutputFormat outputFormat);
402
  OutputFormat getOutputFormat();
403
}
404
```