Template (FreeMarker 3.0.0-nightly-incubating API)

java.lang.Object
+
- org.apache.freemarker.core.Configurable
- +
  - org.apache.freemarker.core.Template
  +
+

+
+
+
```
public class Template
+extends Configurable
```
+
+ Stores an already parsed template, ready to be processed (rendered) for unlimited times, possibly from multiple + threads. + +
+ Typically, you will use Configuration.getTemplate(String) to create/get Template objects, so you + don't construct them directly. But you can also construct a template from a Reader or a String that + contains the template source code. But then it's important to know that while the resulting Template is + efficient for later processing, creating a new Template itself is relatively expensive. So try to re-use + Template objects if possible. Configuration.getTemplate(String) (and its overloads) does that + (caching Template-s) for you, but the constructor of course doesn't, so it's up to you to solve then. + +
+ Objects of this class meant to be handled as immutable and thus thread-safe. However, it has some setter methods for + changing FreeMarker settings. Those must not be used while the template is being processed, or if the template object + is already accessible from multiple threads. If some templates need different settings that those coming from the + shared Configuration, and you are using Configuration.getTemplate(String) (or its overloads), then + use Configuration.setTemplateConfigurations(org.apache.freemarker.core.templateresolver.TemplateConfigurationFactory) to achieve that.
+

+ +

Nested Class Summary

+ + + + + + + + + + +

Nested Classes
Modifier and Type	Class and Description
`static class`	`Template.WrongEncodingException` + Thrown by the `Template` constructors that specify a non-`null` encoding whoch doesn't match the + encoding specified in the `#ftl` header of the template. +

+ +

+ + +
Field Summary
+ + + + + + + + + + + + + + +
Fields
Modifier and Type Field and Description
static String DEFAULT_NAMESPACE_PREFIX
static String NO_NS_PREFIX
+
- + + +
  Fields inherited from class org.apache.freemarker.core.Configurable
  +API_BUILTIN_ENABLED_KEY, API_BUILTIN_ENABLED_KEY_CAMEL_CASE, API_BUILTIN_ENABLED_KEY_SNAKE_CASE, ARITHMETIC_ENGINE_KEY, ARITHMETIC_ENGINE_KEY_CAMEL_CASE, ARITHMETIC_ENGINE_KEY_SNAKE_CASE, AUTO_FLUSH_KEY, AUTO_FLUSH_KEY_CAMEL_CASE, AUTO_FLUSH_KEY_SNAKE_CASE, AUTO_IMPORT_KEY, AUTO_IMPORT_KEY_CAMEL_CASE, AUTO_IMPORT_KEY_SNAKE_CASE, AUTO_INCLUDE_KEY, AUTO_INCLUDE_KEY_CAMEL_CASE, AUTO_INCLUDE_KEY_SNAKE_CASE, BOOLEAN_FORMAT_KEY, BOOLEAN_FORMAT_KEY_CAMEL_CASE, BOOLEAN_FORMAT_KEY_SNAKE_CASE, CUSTOM_DATE_FORMATS_KEY, CUSTOM_DATE_FORMATS_KEY_CAMEL_CASE, CUSTOM_DATE_FORMATS_KEY_SNAKE_CASE, CUSTOM_NUMBER_FORMATS_KEY, CUSTOM_NUMBER_FORMATS_KEY_CAMEL_CASE, CUSTOM_NUMBER_FORMATS_KEY_SNAKE_CASE, DATE_FORMAT_KEY, DATE_FORMAT_KEY_CAMEL_CASE, DATE_FORMAT_KEY_SNAKE_CASE, DATETIME_FORMAT_KEY, DATETIME_FORMAT_KEY_CAMEL_CASE, DATETIME_FORMAT_KEY_SNAKE_CASE, LAZY_AUTO_IMPORTS_KEY, LAZY_AUTO_IMPORTS_KEY_CAMEL_CASE, LAZY_AUTO_IMPORTS_KEY_SNAKE_CASE, LAZY_IMPORTS_KEY, LAZY_IMPORTS_KEY_CAMEL_CASE, LAZY_IMPORTS_KEY_SNAKE_CASE, LOCALE_KEY, LOCALE_KEY_CAMEL_CASE, LOCALE_KEY_SNAKE_CASE, LOG_TEMPLA TE_EXCEPTIONS_KEY, LOG_TEMPLATE_EXCEPTIONS_KEY_CAMEL_CASE, LOG_TEMPLATE_EXCEPTIONS_KEY_SNAKE_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY, NEW_BUILTIN_CLASS_RESOLVER_KEY_CAMEL_CASE, NEW_BUILTIN_CLASS_RESOLVER_KEY_SNAKE_CASE, NUMBER_FORMAT_KEY, NUMBER_FORMAT_KEY_CAMEL_ CASE, NUMBER_FORMAT_KEY_SNAKE_CASE, OBJECT_WRAPPER_KEY, OBJECT_WRAPPER_KEY_CAMEL_CASE, OBJECT_WRAPPER_KEY_SNAKE_CASE, OUTPUT_ENCODING_KEY, OUTPUT_ENCODING_KEY_CAMEL_CASE, OUTPUT_ENCODING_KEY_SNAKE_CASE, SHOW_ERROR_TIPS_ KEY, SHOW_ERROR_TIPS_KEY_CAMEL_CASE, SHOW_ERROR_TIPS_KEY_SNAKE_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY, SQL_DATE_AND_TIME_TIME_ZONE_KEY_CAMEL_CASE, SQL_DATE_AND_TIME_TIME_ZONE_KEY_SNAKE_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY, TEMPLATE_EXCEPTION_HANDLE R_KEY_CAMEL_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY_SNAKE_CASE, TIME_FORMAT_KEY, TIME_FORMAT_KEY_CAMEL_CASE, TIME_FORMAT_KEY_SNAKE_CASE, TIME_ZONE_KEY, TIME_ZONE_KEY_CAMEL_CASE, TIME_ZONE_KEY_SNAKE_CASE, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE
+

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_NAMESPACE_PREFIX`
`static String`	`NO_NS_PREFIX`

+ +

+ + +

Constructor Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Constructors
Constructor and Description
`Template(String name, + Reader reader, + Configuration cfg)` + Same as `Template(String, String, Reader, Configuration)` with `null` `sourceName` parameter. +
`Template(String name, + Reader reader, + Configuration cfg, + String encoding)` + Convenience constructor for `Template(name, null, + reader, cfg, encoding)`. +
`Template(String name, + String sourceCode, + Configuration cfg)` + Convenience constructor for `Template(name, new StringReader(reader), cfg)`. +
`Template(String name, + String sourceName, + Reader reader, + Configuration cfg)` + Constructs a template from a character stream. +
`Template(String name, + String sourceName, + Reader reader, + Configuration cfg, + ParserConfiguration customParserConfiguration, + String encoding)` + Same as `Template(String, String, Reader, Configuration, String)`, but also specifies a + `TemplateConfiguration`. +
`Template(String name, + String sourceName, + Reader reader, + Configuration cfg, + ParserConfiguration customParserConfiguration, + String encoding, + InputStream streamToUnmarkWhenEncEstabd)` + Same as `Template(String, String, Reader, Configuration, ParserConfiguration, String)`, but allows + specifying the `streamToUnmarkWhenEncEstabd` `InputStream`. +
`Template(String name, + String sourceName, + Reader reader, + Configuration cfg, + String encoding)` + Same as `Template(String, String, Reader, Configuration)`, but also specifies the template's encoding (not + recommended). +

+ +

+ + +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Template`	`createPlainTextTemplate(String name, + String content, + Configuration config)` + Same as `createPlainTextTemplate(String, String, String, Configuration, String)` with `null` + `sourceName` argument. +
`static Template`	`createPlainTextTemplate(String name, + String sourceName, + String content, + Configuration config, + String encoding)` + Creates a `Template` that only contains a single block of static text, no dynamic content. +
`Environment`	`createProcessingEnvironment(Object dataModel, + Writer out)` + Same as `createProcessingEnvironment(dataModel, out, null)`. +
`Environment`	`createProcessingEnvironment(Object dataModel, + Writer out, + ObjectWrapper wrapper)` + Creates a `Environment` object, using this template, the data-model provided as + parameter. +
`void`	`dump(PrintStream ps)` + Dump the raw template in canonical form. +
`void`	`dump(Writer out)` + Dump the raw template in canonical form. +
`int`	`getActualNamingConvention()` + Returns the naming convention the parser has chosen for this template. +
`int`	`getActualTagSyntax()` + Returns the tag syntax the parser has chosen for this template. +
`boolean`	`getAutoEscaping()` + Returns if the template actually uses auto-escaping (see `Configuration.setAutoEscapingPolicy(int)`). +
`Configuration`	`getConfiguration()` + Returns the Configuration object associated with this template. +
`Object`	`getCustomLookupCondition()` + Gets the custom lookup condition with which this template was found. +
`String`	`getDefaultNS()`
`String`	`getEncoding()` + Returns the default character encoding used for reading included/imported files; if `null`, then + the encoding returned by `Configuration.getEncoding(java.util.Locale)` should be used instead. +
`String`	`getName()` + The usually path-like (or URL-like) identifier of the template, or possibly `null` for non-stored + templates. +
`String`	`getNamespaceForPrefix(String prefix)`
`OutputFormat`	`getOutputFormat()` + Returns the output format (see `Configuration.setOutputFormat(OutputFormat)`) used for this template. +
`ParserConfiguration`	`getParserConfiguration()` + Returns the `ParserConfiguration` that was used for parsing this template. +
`String`	`getPrefixedName(String localName, + String nsURI)`
`String`	`getPrefixForNamespace(String nsURI)`
`String`	`getSource(int beginColumn, + int beginLine, + int endColumn, + int endLine)` + Returns the template source at the location specified by the coordinates given, or `null` if unavailable. +
`String`	`getSourceName()` + The name that was actually used to load this template from the `TemplateLoader` (or from other custom + storage mechanism). +
`void`	`process(Object dataModel, + Writer out)` + Executes template, using the data-model provided, writing the generated output to the supplied `Writer`. +
`void`	`process(Object dataModel, + Writer out, + ObjectWrapper wrapper)` + Like `process(Object, Writer)`, but overrides the `Configurable.getObjectWrapper()`. +
`void`	`process(Object dataModel, + Writer out, + ObjectWrapper wrapper, + TemplateNodeModel rootNode)` + Like `process(Object, Writer)`, but also sets a (XML-)node to be recursively processed by the template. +
`void`	`setCustomLookupCondition(Object customLookupCondition)` + Mostly only used internally; setter pair of `getCustomLookupCondition()`. +
`String`	`toString()` + Returns a string representing the raw template + text in canonical form. +

+ + +
Methods inherited from class org.apache.freemarker.core.Configurable
+addAutoImport, addAutoInclude, doAutoImportsAndIncludes, getArithmeticEngine, getAutoFlush, getAutoImports, getAutoImportsWithoutFallback, getAutoIncludes, getAutoIncludesWithoutFallback, getBooleanFormat, getCorrectedNameForUnknownSetting, getCustomAttribute, getCustomAttributeNames, getCustomDateFormat, getCustomDateFormats, getCustomD ateFormatsWithoutFallback, getCustomNumberFormat, getCustomNumberFormats, getCustomNumberFormatsWithoutFallback, getDateFormat, getDateTimeFormat, getEnvironment, getLazyAutoImports, getLazyImports, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getRemovalVersionForUnknownSetting, getSettingN ames, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getURLEscapingCharset, hasCustomFormats, invalidSettingValueException, invalidSettingValueException, isAPIBuiltinEnabled, isAPIBuiltinEnabledSet, isArithmeticEngineSet, isAutoFlushSet, isAutoImportsSet, isAutoIncludesSet, isBooleanFormatSet, isCustomDateFormatsSet, isCustomNumberFormatsSet, isDateFormatSet, isDateTimeFormatSet, isLazyAutoImportsSet, isLazyImportsSet, isLocaleSet, isLogTemplateExceptionsSet, isNewBuiltinClassResolverSet, isNumberFormatSet, isObjectWrapperSet, isOutputEncodingSet, isShowErrorTipsSet, isSQLDateAndTimeTimeZoneSet, isTemplateExceptionHandlerSet, isTimeFormatSet, isTimeZoneSet, isURLEscapingCharsetSet, parseAsImportList, parseAsList, parseAsSegmentedList, removeAutoImport, removeAutoInclude, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAutoFlush, setAutoImports, setAutoIncludes, setBooleanFormat, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setDateFormat, setDateTimeFormat, setLazyAutoImports, setLazyImports, setLocale, setLogTemplateExceptions, setNewBuiltinClassResolver, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setURLEscapingCharset, unknownSettingException

+ + +
Methods inherited from class java.lang.Object
+clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

+ +
- + + +
  Field Detail
  + + + +
  - +
    DEFAULT_NAMESPACE_PREFIX
    +
```
public static final String DEFAULT_NAMESPACE_PREFIX
```
    +
    +
    See Also:
    +
    Constant Field Values
    +
    +
  + + + +
  - +
    NO_NS_PREFIX
    +
```
public static final String NO_NS_PREFIX
```
    +
    +
    See Also:
    +
    Constant Field Values
    +
    +
  +
+ +
- + + +
  Constructor Detail
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                Reader reader,
+                Configuration cfg)
+         throws IOException
```
    +
    Same as Template(String, String, Reader, Configuration) with null sourceName parameter.
    +
    +
    Throws:
    +
    IOException
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                String sourceCode,
+                Configuration cfg)
+         throws IOException
```
    +
    Convenience constructor for Template(name, new StringReader(reader), cfg).
    +
    +
    Throws:
    +
    IOException
    +
    Since:
    +
    2.3.20
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                Reader reader,
+                Configuration cfg,
+                String encoding)
+         throws IOException
```
    +
    Convenience constructor for Template(name, null, + reader, cfg, encoding).
    +
    +
    Throws:
    +
    IOException
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                String sourceName,
+                Reader reader,
+                Configuration cfg)
+         throws IOException
```
    +
    Constructs a template from a character stream. Note that this is a relatively expensive operation; where higher + performance matters, you should re-use (cache) Template instances instead of re-creating them from the + same source again and again. (and its overloads already do such reuse.)
    +
    +
    Parameters:
    +
    name - The path of the template file relatively to the (virtual) directory that you use to store the + templates (except if sourceName + differs from it). Shouldn't start with '/'. Should use '/', not '\'. Check + getName() to see how the name will be used. The name should be independent of the actual + storage mechanism and physical location as far as possible. Even when the templates are stored + straightforwardly in real files (they often aren't; see TemplateLoader), the name shouldn't be + an absolute file path. Like if the template is stored in "/www/templates/forum/main.ftl", and + you are using "/www/templates/" as the template root directory via + Configuration.setDirectoryForTemplateLoading(java.io.File), then the template name will be + "forum/main.ftl". The name can be null (should be used for template made on-the-fly + instead of being loaded from somewhere), in which case relative paths in it will be relative to + the template root directory (and here again, it's the TemplateLoader that knows what that + "physically" means).
    +
    sourceName - See getSourceName() for the meaning. Can be null, in which case + getSourceName() will return the same as getName().
    +
    reader - The character stream to read from. The Reader is not closed by this method (unlike + in FreeMarker 2.x.x), so be sure that it's closed somewhere. (Except of course, readers like + StringReader need not be closed.) The Reader need not be buffered, because this + method ensures that it will be read in few kilobyte chunks, not byte by byte.
    +
    cfg - The Configuration object that this Template is associated with. Can't be null.
    +
    Throws:
    +
    IOException
    +
    Since:
    +
    2.3.22
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                String sourceName,
+                Reader reader,
+                Configuration cfg,
+                String encoding)
+         throws IOException
```
    +
    Same as Template(String, String, Reader, Configuration), but also specifies the template's encoding (not + recommended).
    +
    +
    Parameters:
    +
    encoding - This is the encoding that we are supposed to be using. At the first glance it's unnecessary because we + already have a Reader (so decoding with the charset has already happened), however, if this is + non-null and there's an #ftl header with encoding parameter, they must match, + or else a Template.WrongEncodingException is thrown. Thus, it should be set if to decode the template, + we were using an encoding (a charset), otherwise it should be null. It's also kept as + meta-info (returned by getEncoding()). It also has an impact when #include-ing or + #import-ing another template from this template, as its default encoding will be this. But + this behavior of said directives is considered to be harmful, and will be probably phased out.
    +
    Throws:
    +
    IOException
    +
    Since:
    +
    2.3.22
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                String sourceName,
+                Reader reader,
+                Configuration cfg,
+                ParserConfiguration customParserConfiguration,
+                String encoding)
+         throws IOException
```
    +
    Same as Template(String, String, Reader, Configuration, String), but also specifies a + TemplateConfiguration. This is mostly meant to be used by FreeMarker internally, but advanced users might + still find this useful.
    +
    +
    Parameters:
    +
    customParserConfiguration - Overrides the parsing related configuration settings of the Configuration parameter; can be + null. This is useful as the Configuration is normally a singleton shared by all + templates, and so it's not good for specifying template-specific settings. (While Template + itself has methods to specify settings just for that template, those don't influence the parsing, and + you only have opportunity to call them after the parsing anyway.) This objects is often a + TemplateConfiguration whose parent is the Configuration parameter, and then it + practically just overrides some of the parser settings, as the others are inherited from the + Configuration. Note that if this is a TemplateConfiguration, you will also want to + call TemplateConfiguration.apply(Template) on the resulting Template so that + Configurable settings will be set too, because this constructor only uses it as a + ParserConfiguration.
    +
    encoding - Same as in Template(String, String, Reader, Configuration, String).
    +
    Throws:
    +
    IOException
    +
    Since:
    +
    2.3.24
    +
    +
  + + + +
  - +
    Template
    +
```
public Template(String name,
+                String sourceName,
+                Reader reader,
+                Configuration cfg,
+                ParserConfiguration customParserConfiguration,
+                String encoding,
+                InputStream streamToUnmarkWhenEncEstabd)
+         throws IOException
```
    +
    Same as Template(String, String, Reader, Configuration, ParserConfiguration, String), but allows + specifying the streamToUnmarkWhenEncEstabd InputStream.
    +
    +
    Parameters:
    +
    streamToUnmarkWhenEncEstabd - If not null, when during the parsing we reach a point where we know that no Template.WrongEncodingException will be thrown, mark(0) will be called on this. + This is meant to be used when the reader parameter is a InputStreamReader, and this parameter is + the underlying InputStream, and you have a mark at the beginning of the InputStream so + that you can retry if a Template.WrongEncodingException is thrown without extra I/O. As keeping that + mark consumes some resources, so you may want to release it as soon as possible.
    +
    Throws:

Class Template

Nested Class Summary

Field Summary

Fields inherited from class org.apache.freemarker.core.Configurable

Constructor Summary

Method Summary

Methods inherited from class org.apache.freemarker.core.Configurable

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_NAMESPACE_PREFIX

NO_NS_PREFIX

Constructor Detail

Template

Template

Template

Template

Template

Template

Template