Template (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.template, class: Template

Package freemarker.template

# Class Template

java.lang.Object
freemarker.core.Configurable
freemarker.template.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(freemarker.cache.TemplateConfigurationFactory)` to achieve that.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  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.

  ## Nested classes/interfaces inherited from class freemarker.core.Configurable

  `Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException`

- ## Field Summary

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

  ### Fields inherited from class 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, ATTEMPT_EXCEPTION_REPORTER_KEY, ATTEMPT_EXCEPTION_REPORTER_KEY_CAMEL_CASE, ATTEMPT_EXCEPTION_REPORTER_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, C_FORMAT_KEY, C_FORMAT_KEY_CAMEL_CASE, C_FORMAT_KEY_SNAKE_CASE, CLASSIC_COMPATIBLE_KEY, CLASSIC_COMPATIBLE_KEY_CAMEL_CASE, CLASSIC_COMPATIBLE_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_TEMPLATE_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, STRICT_BEAN_MODELS, STRICT_BEAN_MODELS_KEY, STRICT_BEAN_MODELS_KEY_CAMEL_CASE, STRICT_BEAN_MODELS_KEY_SNAKE_CASE, TEMPLATE_EXCEPTION_HANDLER_KEY, TEMPLATE_EXCEPTION_HANDLER_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, TRUNCATE_BUILTIN_ALGORITHM_KEY, TRUNCATE_BUILTIN_ALGORITHM_KEY_CAMEL_CASE, TRUNCATE_BUILTIN_ALGORITHM_KEY_SNAKE_CASE, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY, WRAP_UNCHECKED_EXCEPTIONS_KEY_CAMEL_CASE, WRAP_UNCHECKED_EXCEPTIONS_KEY_SNAKE_CASE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Template​(String name, Reader reader)`
  Deprecated.
  This constructor uses the "default" `Configuration` instance, which can easily lead to erroneous, unpredictable behavior.
  `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, String encoding)`
  Same as `Template(String, String, Reader, Configuration)`, but also specifies the template's encoding (not recommended).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addImport​(freemarker.core.LibraryLoad ll)`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `void`
  `addMacro​(freemarker.core.Macro macro)`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `void`
  `addPrefixNSMapping​(String prefix, String nsURI)`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `List`
  `containingElements​(int column, int line)`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `Environment`
  `createProcessingEnvironment​(Object dataModel, Writer out)`
  Same as `createProcessingEnvironment(dataModel, out, null)`.
  `Environment`
  `createProcessingEnvironment​(Object dataModel, Writer out, ObjectWrapper wrapper)`
  Creates a `Environment` object, with this template as the main (top-level template), and 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()`
  The encoding that was (allegedly) used to read this template; also the the default character encoding used for reading files included from this template.
  `List`
  `getImports()`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `int`
  `getInterpolationSyntax()`
  Returns the interpolation syntax the parser has used for this template.
  `Map`
  `getMacros()`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `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.
  `static Template`
  `getPlainTextTemplate​(String name, String content, Configuration config)`
  Same as `getPlainTextTemplate(String, String, String, Configuration)` with `null` `sourceName` argument.
  `static Template`
  `getPlainTextTemplate​(String name, String sourceName, String content, Configuration config)`
  Creates (not "get"-s) a `Template` that only contains a single block of static text, no dynamic content.
  `String`
  `getPrefixedName​(String localName, String nsURI)`
  `String`
  `getPrefixForNamespace​(String nsURI)`
  `freemarker.core.TemplateElement`
  `getRootTreeNode()`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `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()`.
  `void`
  `setEncoding​(String encoding)`
  Deprecated.
  Should only be used internally, and might will be removed later.
  `String`
  `toString()`
  Returns a string representing the raw template text in canonical form.

  ### Methods inherited from class freemarker.core.Configurable

  `addAutoImport, addAutoInclude, clone, doAutoImportsAndIncludes, getArithmeticEngine, getAttemptExceptionReporter, getAutoFlush, getAutoImports, getAutoImportsWithoutFallback, getAutoIncludes, getAutoIncludesWithoutFallback, getBooleanFormat, getCFormat, getClassicCompatibleAsInt, getCorrectedNameForUnknownSetting, getCustomAttribute, getCustomAttributeNames, getCustomDateFormat, getCustomDateFormats, getCustomDateFormatsWithoutFallback, getCustomNumberFormat, getCustomNumberFormats, getCustomNumberFormatsWithoutFallback, getDateFormat, getDateTimeFormat, getEnvironment, getLazyAutoImports, getLazyImports, getLocale, getLogTemplateExceptions, getNewBuiltinClassResolver, getNumberFormat, getObjectWrapper, getOutputEncoding, getParent, getSetting, getSettingNames, getSettings, getShowErrorTips, getSQLDateAndTimeTimeZone, getTemplateExceptionHandler, getTimeFormat, getTimeZone, getTruncateBuiltinAlgorithm, getURLEscapingCharset, getWrapUncheckedExceptions, hasCustomFormats, invalidSettingValueException, isAPIBuiltinEnabled, isAPIBuiltinEnabledSet, isArithmeticEngineSet, isAttemptExceptionReporterSet, isAutoFlushSet, isAutoImportsSet, isAutoIncludesSet, isBooleanFormatSet, isCFormatSet, isClassicCompatible, isClassicCompatibleSet, isCustomDateFormatsSet, isCustomNumberFormatsSet, isDateFormatSet, isDateTimeFormatSet, isLazyAutoImportsSet, isLazyImportsSet, isLocaleSet, isLogTemplateExceptionsSet, isNewBuiltinClassResolverSet, isNumberFormatSet, isObjectWrapperSet, isOutputEncodingSet, isShowErrorTipsSet, isSQLDateAndTimeTimeZoneSet, isTemplateExceptionHandlerSet, isTimeFormatSet, isTimeZoneSet, isTruncateBuiltinAlgorithmSet, isURLEscapingCharsetSet, isWrapUncheckedExceptionsSet, parseAsImportList, parseAsList, parseAsSegmentedList, removeAutoImport, removeAutoInclude, removeCustomAttribute, setAPIBuiltinEnabled, setArithmeticEngine, setAttemptExceptionReporter, setAutoFlush, setAutoImports, setAutoIncludes, setBooleanFormat, setCFormat, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setDateFormat, setDateTimeFormat, setLazyAutoImports, setLazyImports, setLocale, setLogTemplateExceptions, setNewBuiltinClassResolver, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setStrictBeanModels, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setTruncateBuiltinAlgorithm, setURLEscapingCharset, setWrapUncheckedExceptions, unknownSettingException`

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

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

- ## Field Details

  - ### 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 Details

  - ### 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. It will always be closed (`Reader.close()`) by this method (this is for backward compatibility; later major versions may discontinue this behavior). 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. If this is `null`, the "default" `Configuration` object is used, which is highly discouraged, because it can easily lead to erroneous, unpredictable behavior. (See more `here...`)
    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)`. When it's non-`null`, it overrides the value coming from the `TemplateConfiguration.getEncoding()` method of the `templateConfiguration` parameter.
    Throws:
      `IOException`
    Since:
      2.3.24

  - ### Template

    @Deprecated public Template​(String name, Reader reader) throws IOException
    Deprecated.
    This constructor uses the "default" `Configuration` instance, which can easily lead to erroneous, unpredictable behavior. See more `here...`.
    Equivalent to `Template(name, reader, null)`.
    Throws:
      `IOException`

- ## Method Details

  - ### getPlainTextTemplate

    public static Template getPlainTextTemplate​(String name, String content, Configuration config)
    Same as `getPlainTextTemplate(String, String, String, Configuration)` with `null` `sourceName` argument.

  - ### getPlainTextTemplate

    public static Template getPlainTextTemplate​(String name, String sourceName, String content, Configuration config)
    Creates (not "get"-s) a `Template` that only contains a single block of static text, no dynamic content.
    Parameters:
      `name` - See `getName()` for more details.
      `sourceName` - See `getSourceName()` for more details. If `null`, it will be the same as the `name`.
      `content` - the block of text that this template represents
      `config` - the configuration to which this template belongs
    Since:
      2.3.22

  - ### process

    public void process​(Object dataModel, Writer out) throws TemplateException, IOException
    Executes template, using the data-model provided, writing the generated output to the supplied `Writer`.

    For finer control over the runtime environment setup, such as per-HTTP-request configuring of FreeMarker settings, you may need to use `createProcessingEnvironment(Object, Writer)` instead.

    Parameters:
      `dataModel` - the holder of the variables visible from the template (name-value pairs); usually a `Map<String, Object>` or a JavaBean (where the JavaBean properties will be the variables). Can be any object that the `ObjectWrapper` in use turns into a `TemplateHashModel`. You can also use an object that already implements `TemplateHashModel`; in that case it won't be wrapped. If it's `null`, an empty data model is used.
      `out` - The `Writer` where the output of the template will go. Note that unless you have used `Configurable.setAutoFlush(boolean)` to disable this, `Writer.flush()` will be called at the when the template processing was finished. `Writer.close()` is not called. Can't be `null`.
    Throws:
      `TemplateException` - if an exception occurs during template processing
      `IOException` - if an I/O exception occurs during writing to the writer.

  - ### process

    public void process​(Object dataModel, Writer out, ObjectWrapper wrapper, TemplateNodeModel rootNode) throws TemplateException, IOException
    Like `process(Object, Writer)`, but also sets a (XML-)node to be recursively processed by the template. That node is accessed in the template with `.node`, `#recurse`, etc. See the Declarative XML Processing as a typical example of recursive node processing.
    Parameters:
      `rootNode` - The root node for recursive processing or `null`.
    Throws:
      `TemplateException` - if an exception occurs during template processing
      `IOException` - if an I/O exception occurs during writing to the writer.

  - ### process

    public void process​(Object dataModel, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException
    Like `process(Object, Writer)`, but overrides the `Configurable.getObjectWrapper()`.
    Parameters:
      `wrapper` - The `ObjectWrapper` to be used instead of what `Configurable.getObjectWrapper()` provides, or `null` if you don't want to override that.
    Throws:
      `TemplateException`
      `IOException`

  - ### createProcessingEnvironment

    public Environment createProcessingEnvironment​(Object dataModel, Writer out, ObjectWrapper wrapper) throws TemplateException, IOException
    Creates a `Environment` object, with this template as the main (top-level template), and the data-model provided as parameter. You have to call `Environment.process()` on the return value to start actual template processing (that is, to run the template, to generate output).

    Use this method if you want to do some special initialization on the `Environment` before template processing, or if you want to read the `Environment` after template processing. Otherwise, using `process(Object, Writer)` is simpler.

    Example:

         Environment env = myTemplate.createProcessingEnvironment(root, out, null);
         env.process();

    The above is equivalent with this:

         myTemplate.process(root, out);

    But with `createProcessingEnvironment`, you can manipulate the environment before and after the processing:

         Environment env = myTemplate.createProcessingEnvironment(root, out);

         env.setLocale(myUsersPreferredLocale);
         env.setTimeZone(myUsersPreferredTimezone);

         env.process();  // output is rendered here

         TemplateModel x = env.getVariable("x");  // read back a variable set by the template

    Parameters:
      `dataModel` - the holder of the variables visible from all templates; see `process(Object, Writer)` for more details. If `null`, the data model will be empty.
      `wrapper` - The `ObjectWrapper` to use to wrap objects into `TemplateModel` instances. Normally you left it `null`, in which case `Configurable.getObjectWrapper()` will be used.
      `out` - The `Writer` where the output of the template will go; see `process(Object, Writer)` for more details. Can't be `null`.
    Returns:
      the `Environment` object created for processing. Call `Environment.process()` to process the template.
    Throws:
      `TemplateException` - if an exception occurs while setting up the Environment object.
      `IOException` - if an exception occurs doing any auto-imports

  - ### createProcessingEnvironment

    public Environment createProcessingEnvironment​(Object dataModel, Writer out) throws TemplateException, IOException
    Same as `createProcessingEnvironment(dataModel, out, null)`.
    Throws:
      `TemplateException`
      `IOException`

  - ### toString

    public String toString()
    Returns a string representing the raw template text in canonical form.
    Overrides:
      `toString` in class `Object`

  - ### getName

    public String getName()
    The usually path-like (or URL-like) identifier of the template, or possibly `null` for non-stored templates. It usually looks like a relative UN*X path; it should use `/`, not `\`, and shouldn't start with `/` (but there are no hard guarantees). It's not a real path in a file-system, it's just a name that a `TemplateLoader` used to load the backing resource (in simple cases; actually that name is `getSourceName()`, but see it there). Or, it can also be a name that was never used to load the template (directly created with `Template(String, Reader, Configuration)`). Even if the templates are stored straightforwardly in files, this is relative to the base directory of the `TemplateLoader`. So it really could be anything, except that it has importance in these situations:

    Relative paths to other templates in this template will be resolved relatively to the directory part of this. Like if the template name is `"foo/this.ftl"`, then `<#include "other.ftl">` gets the template with name `"foo/other.ftl"`.

    You should not use this name to indicate error locations, or to find the actual templates in general, because localized lookup, acquisition and other lookup strategies can transform names before they get to the `TemplateLoader` (the template storage) mechanism. Use `getSourceName()` for these purposes.

    Some frameworks use URL-like template names like `"someSchema://foo/bar.ftl"`. FreeMarker understands this notation, so an absolute path like `"/baaz.ftl"` in that template will be resolved too `"someSchema://baaz.ftl"`.

  - ### getSourceName

    public String getSourceName()
    The name that was actually used to load this template from the `TemplateLoader` (or from other custom storage mechanism). This is what should be shown in error messages as the error location. This is usually the same as `getName()`, except when localized lookup, template acquisition (`*` step in the name), or other `TemplateLookupStrategy` transforms the requested name (`getName()`) to a different final `TemplateLoader`-level name. For example, when you get a template with name `"foo.ftl"` then because of localized lookup, it's possible that something like `"foo_en.ftl"` will be loaded behind the scenes. While the template name will be still the same as the requested template name (`"foo.ftl"`), errors should point to `"foo_de.ftl"`. Note that relative paths are always resolved relatively to the `name`, not to the `sourceName`.
    Since:
      2.3.22

  - ### getConfiguration

    public Configuration getConfiguration()
    Returns the Configuration object associated with this template.

  - ### getParserConfiguration

    public ParserConfiguration getParserConfiguration()
    Returns the `ParserConfiguration` that was used for parsing this template. This is most often the same object as `getConfiguration()`, but sometimes it's a `TemplateConfiguration`, or something else. It's never `null`.
    Since:
      2.3.24

  - ### setEncoding

    @Deprecated public void setEncoding​(String encoding)
    Deprecated.
    Should only be used internally, and might will be removed later.
    Parameters:
      `encoding` - The encoding that was used to read this template. When this template `#include`-s or `#import`-s another template, by default it will use this encoding for those. For backward compatibility, this can be `null`, which will unset this setting.

  - ### getEncoding

    public String getEncoding()
    The encoding that was (allegedly) used to read this template; also the the default character encoding used for reading files included from this template. Possibly `null`, in which case you are supposed to use `Configuration.getEncoding(Locale)`.

  - ### getCustomLookupCondition

    public Object getCustomLookupCondition()
    Gets the custom lookup condition with which this template was found. See the `customLookupCondition` parameter of `Configuration.getTemplate(String, java.util.Locale, Object, String, boolean, boolean)` for more explanation.
    Since:
      2.3.22

  - ### setCustomLookupCondition

    public void setCustomLookupCondition​(Object customLookupCondition)
    Mostly only used internally; setter pair of `getCustomLookupCondition()`. This meant to be called directly after instantiating the template with its constructor, after a successfull lookup that used this condition. So this should only be called from code that deals with creating new `Template` objects, like from `TemplateCache`.
    Since:
      2.3.22

  - ### getActualTagSyntax

    public int getActualTagSyntax()
    Returns the tag syntax the parser has chosen for this template. If the syntax could be determined, it's `Configuration.SQUARE_BRACKET_TAG_SYNTAX` or `Configuration.ANGLE_BRACKET_TAG_SYNTAX`. If the syntax couldn't be determined (like because there was no tags in the template, or it was a plain text template), this returns whatever the default is in the current configuration, so it's maybe `Configuration.AUTO_DETECT_TAG_SYNTAX`.
    Since:
      2.3.20
    See Also:
      `Configuration.setTagSyntax(int)`

  - ### getInterpolationSyntax

    public int getInterpolationSyntax()
    Returns the interpolation syntax the parser has used for this template. Because the interpolation syntax is never auto-detected, it's not called "getActualInterpolationSyntax" (unlike `getActualTagSyntax()`).
    Returns:
      A constant like `Configuration.LEGACY_INTERPOLATION_SYNTAX`, `Configuration.DOLLAR_INTERPOLATION_SYNTAX`, or `Configuration.SQUARE_BRACKET_INTERPOLATION_SYNTAX`.
    Since:
      2.3.28
    See Also:
      `Configuration.setInterpolationSyntax(int)`

  - ### getActualNamingConvention

    public int getActualNamingConvention()
    Returns the naming convention the parser has chosen for this template. If it could be determined, it's `Configuration.LEGACY_NAMING_CONVENTION` or `Configuration.CAMEL_CASE_NAMING_CONVENTION`. If it couldn't be determined (like because there no identifier that's part of the template language was used where the naming convention matters), this returns whatever the default is in the current configuration, so it's maybe `Configuration.AUTO_DETECT_TAG_SYNTAX`.
    Since:
      2.3.23
    See Also:
      `Configuration.setNamingConvention(int)`

  - ### getOutputFormat

    public OutputFormat getOutputFormat()
    Returns the output format (see `Configuration.setOutputFormat(OutputFormat)`) used for this template. The output format of a template can come from various places, in order of increasing priority: `Configuration.getOutputFormat()`, `ParserConfiguration.getOutputFormat()` (which is usually provided by `Configuration.getTemplateConfigurations()`) and the `#ftl` header's `output_format` option in the template.
    Since:
      2.3.24

  - ### getAutoEscaping

    public boolean getAutoEscaping()
    Returns if the template actually uses auto-escaping (see `Configuration.setAutoEscapingPolicy(int)`). This value is decided by the parser based on the actual `OutputFormat`, and the auto-escaping enums, in order of increasing priority: `Configuration.getAutoEscapingPolicy()`, `ParserConfiguration.getAutoEscapingPolicy()` (which is usually provided by `Configuration.getTemplateConfigurations()`), and finally on the `#ftl` header's `auto_esc` option in the template.
    Since:
      2.3.24

  - ### dump

    public void dump​(PrintStream ps)
    Dump the raw template in canonical form.

  - ### dump

    public void dump​(Writer out) throws IOException
    Dump the raw template in canonical form.
    Throws:
      `IOException`

  - ### addMacro

    @Deprecated public void addMacro​(freemarker.core.Macro macro)
    Deprecated.
    Should only be used internally, and might will be removed later.
    Called by code internally to maintain a table of macros

  - ### addImport

    @Deprecated public void addImport​(freemarker.core.LibraryLoad ll)
    Deprecated.
    Should only be used internally, and might will be removed later.
    Called by code internally to maintain a list of imports

  - ### getSource

    public 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. A strange legacy in the behavior of this method is that it replaces tab characters with spaces according the value of `getParserConfiguration()`/`ParserConfiguration.getTabSize()` (which usually comes from `Configuration.getTabSize()`), because tab characters move the column number with more than 1 in error messages. However, if you set the tab size to 1, this method leaves the tab characters as is.
    Parameters:
      `beginColumn` - the first column of the requested source, 1-based
      `beginLine` - the first line of the requested source, 1-based
      `endColumn` - the last column of the requested source, 1-based. If this is beyond the last character of the line, it assumes that you want to whole line.
      `endLine` - the last line of the requested source, 1-based
    See Also:
      `TemplateObject.getSource()`

  - ### getRootTreeNode

    @Deprecated public freemarker.core.TemplateElement getRootTreeNode()
    Deprecated.
    Should only be used internally, and might will be removed later.

  - ### getMacros

    @Deprecated public Map getMacros()
    Deprecated.
    Should only be used internally, and might will be removed later.

  - ### getImports

    @Deprecated public List getImports()
    Deprecated.
    Should only be used internally, and might will be removed later.

  - ### addPrefixNSMapping

    @Deprecated public void addPrefixNSMapping​(String prefix, String nsURI)
    Deprecated.
    Should only be used internally, and might will be removed later.
    This is used internally.

  - ### getDefaultNS

    public String getDefaultNS()

  - ### getNamespaceForPrefix

    public String getNamespaceForPrefix​(String prefix)
    Returns:
      the NamespaceUri mapped to this prefix in this template. (Or null if there is none.)

  - ### getPrefixForNamespace

    public String getPrefixForNamespace​(String nsURI)
    Returns:
      the prefix mapped to this nsURI in this template. (Or null if there is none.)

  - ### getPrefixedName

    public String getPrefixedName​(String localName, String nsURI)
    Returns:
      the prefixed name, based on the ns_prefixes defined in this template's header for the local name and node namespace passed in as parameters.

  - ### containingElements

    @Deprecated public List containingElements​(int column, int line)
    Deprecated.
    Should only be used internally, and might will be removed later.
    Returns:
      an array of the `TemplateElement`s containing the given column and line numbers.