freemarker.core

## Class TemplateConfiguration

- java.lang.Object
- - freemarker.core.Configurable
  - - freemarker.core.TemplateConfiguration

All Implemented Interfaces:
  ParserConfiguration

    public final class TemplateConfiguration
    extends Configurable
    implements ParserConfiguration

Used for customizing the configuration settings for individual `Template`-s (or rather groups of templates), relatively to the common setting values coming from the `Configuration`. This was designed with the standard template loading mechanism of FreeMarker in mind (`Configuration.getTemplate(String)` and `TemplateCache`), though can also be reused for custom template loading and caching solutions.

Note on the `locale` setting: When used with the standard template loading/caching mechanism ( `Configuration.getTemplate(String)` and its overloads), localized lookup happens before the `locale` specified here could have effect. The `locale` will be only set in the template that the localized lookup has already found.

Note on the encoding setting `encoding`: See `setEncoding(String)`.

Note that the result value of the reader methods (getter and "is" methods) is usually not useful unless the value of that setting was already set on this object. Otherwise you will get the value from the parent `Configuration`, which is `Configuration.getDefaultConfiguration()` before this object is associated to a `Configuration`.

If you are using this class for your own template loading and caching solution, rather than with the standard one, you should be aware of a few more details:

- This class implements both `Configurable` and `ParserConfiguration`. This means that it can influence both the template parsing phase and the runtime settings. For both aspects (i.e., `ParserConfiguration` and `Configurable`) to take effect, you have first pass this object to the `Template` constructor (this is where the `ParserConfiguration` interface is used), and then you have to call `apply(Template)` on the resulting `Template` object (this is where the `Configurable` aspect is used).
- `apply(Template)` only change the settings that weren't yet set on the `Template` (but are inherited from the `Configuration`). This is primarily because if the template configures itself via the `#ftl` header, those values should have precedence. A consequence of this is that if you want to configure the same `Template` with multiple `TemplateConfiguration`-s, you either should merge them to a single one before that (with `merge(TemplateConfiguration)`), or you have to apply them in reverse order of their intended precedence.

Since:
  2.3.24
See Also:
  `Template.Template(String, String, Reader, Configuration, ParserConfiguration, String)`

### Nested Class Summary

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

`Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException`

### Field Summary

### 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, 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, 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, URL_ESCAPING_CHARSET_KEY, URL_ESCAPING_CHARSET_KEY_CAMEL_CASE, URL_ESCAPING_CHARSET_KEY_SNAKE_CASE`

### Constructor Summary

Constructors
Constructor and Description
`TemplateConfiguration()` Creates a new instance.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `apply(Template template)` Sets those settings of the `Template` which aren't yet set in the `Template` and are set in this `TemplateConfiguration`, leaves the other settings as is.
`int` `getAutoEscapingPolicy()` The getter pair of `setAutoEscapingPolicy(int)`.
`String` `getEncoding()`
`Version` `getIncompatibleImprovements()` Returns `Configuration.getIncompatibleImprovements()` from the parent `Configuration`.
`int` `getNamingConvention()` The getter pair of `setNamingConvention(int)`.
`OutputFormat` `getOutputFormat()` The getter pair of `setOutputFormat(OutputFormat)`.
`Configuration` `getParentConfiguration()` Returns the parent `Configuration`, or `null` if none was associated yet.
`boolean` `getRecognizeStandardFileExtensions()` Getter pair of `setRecognizeStandardFileExtensions(boolean)`.
`boolean` `getStrictSyntaxMode()` The getter pair of `setStrictSyntaxMode(boolean)`.
`int` `getTabSize()` Getter pair of `setTabSize(int)`.
`int` `getTagSyntax()` The getter pair of `setTagSyntax(int)`.
`boolean` `getWhitespaceStripping()` The getter pair of `getWhitespaceStripping()`.
`boolean` `isAutoEscapingPolicySet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isEncodingSet()`
`boolean` `isNamingConventionSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isOutputFormatSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isRecognizeStandardFileExtensionsSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isStrictSyntaxModeSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isTabSizeSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isTagSyntaxSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`boolean` `isWhitespaceStrippingSet()` Tells if this setting is set directly in this object or its value is coming from the `parent`.
`void` `merge(TemplateConfiguration tc)` Set all settings in this `TemplateConfiguration` that were set in the parameter `TemplateConfiguration`, possibly overwriting the earlier value in this object.
`void` `setAutoEscapingPolicy(int autoEscapingPolicy)` Sets the output format of the template; see `Configuration.setAutoEscapingPolicy(int)` for more.
`void` `setEncoding(String encoding)` When the standard template loading/caching mechanism is used, this forces the charset used for reading the template "file", overriding everything but the encoding coming from the `#ftl` header.
`void` `setNamingConvention(int namingConvention)` See `Configuration.setNamingConvention(int)`.
`void` `setOutputFormat(OutputFormat outputFormat)` Sets the output format of the template; see `Configuration.setOutputFormat(OutputFormat)` for more.
`void` `setParentConfiguration(Configuration cfg)` Associates this instance with a `Configuration`; usually you don't call this, as it's called internally when this instance is added to a `Configuration`.
`void` `setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions)` See `Configuration.setRecognizeStandardFileExtensions(boolean)`.
`void` `setStrictBeanModels(boolean strict)`
`void` `setStrictSyntaxMode(boolean strictSyntaxMode)` See `Configuration.setStrictSyntaxMode(boolean)`.
`void` `setTabSize(int tabSize)` See `Configuration.setTabSize(int)`.
`void` `setTagSyntax(int tagSyntax)` See `Configuration.setTagSyntax(int)`.
`void` `setWhitespaceStripping(boolean whitespaceStripping)` See `Configuration.setWhitespaceStripping(boolean)`.

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

`addAutoImport, addAutoInclude, clone, doAutoImportsAndIncludes, getArithmeticEngine, getAutoFlush, getAutoImports, getAutoImportsWithoutFallback, getAutoIncludes, getAutoIncludesWithoutFallback, getBooleanFormat, 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, getURLEscapingCharset, hasCustomFormats, invalidSettingValueException, isAPIBuiltinEnabled, isAPIBuiltinEnabledSet, isArithmeticEngineSet, isAutoFlushSet, isAutoImportsSet, isAutoIncludesSet, isBooleanFormatSet, isClassicCompatible, isClassicCompatibleSet, 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, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setDateFormat, setDateTimeFormat, setLazyAutoImports, setLazyImports, setLocale, setLogTemplateExceptions, setNewBuiltinClassResolver, setNumberFormat, setObjectWrapper, setOutputEncoding, setSetting, setSettings, setSettings, setShowErrorTips, setSQLDateAndTimeTimeZone, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setURLEscapingCharset, unknownSettingException`

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

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

### Methods inherited from interface freemarker.core.ParserConfiguration

`getArithmeticEngine`

### Constructor Detail

#### TemplateConfiguration

    public TemplateConfiguration()

Creates a new instance. The parent will be `Configuration.getDefaultConfiguration()` initially, but it will be changed to the real parent `Configuration` when this object is added to the `Configuration`. (It's not allowed to add the same instance to multiple `Configuration`-s).

### Method Detail

#### setParentConfiguration

    public void setParentConfiguration(Configuration cfg)

Associates this instance with a `Configuration`; usually you don't call this, as it's called internally when this instance is added to a `Configuration`. This method can be called only once (except with the same `Configuration` parameter again, as that changes nothing anyway).

Throws:
  `IllegalArgumentException` - if the argument is `null` or not a `Configuration`
  `IllegalStateException` - if this object is already associated to a different `Configuration` object, or if the `Configuration` has `#getIncompatibleImprovements()` less than 2.3.22 and this object tries to change any non-parser settings

#### getParentConfiguration

    public Configuration getParentConfiguration()

Returns the parent `Configuration`, or `null` if none was associated yet.

#### merge

    public void merge(TemplateConfiguration tc)

Set all settings in this `TemplateConfiguration` that were set in the parameter `TemplateConfiguration`, possibly overwriting the earlier value in this object. (A setting is said to be set in a `TemplateConfiguration` if it was explicitly set via a setter method, as opposed to be inherited.)

#### apply

    public void apply(Template template)

Sets those settings of the `Template` which aren't yet set in the `Template` and are set in this `TemplateConfiguration`, leaves the other settings as is. A setting is said to be set in a `TemplateConfiguration` or `Template` if it was explicitly set via a setter method on that object, as opposed to be inherited from the `Configuration`.

Note that this method doesn't deal with settings that influence the parser, as those are already baked in at this point via the `ParserConfiguration`.

Note that the `encoding` setting of the `Template` counts as unset if it's `null`, even if `null` was set via `Template.setEncoding(String)`.

Throws:
  `IllegalStateException` - If the parent configuration wasn't yet set.

#### setTagSyntax

    public void setTagSyntax(int tagSyntax)

See `Configuration.setTagSyntax(int)`.

#### getTagSyntax

    public int getTagSyntax()

The getter pair of `setTagSyntax(int)`.

Specified by:
  `getTagSyntax` in interface `ParserConfiguration`

#### isTagSyntaxSet

    public boolean isTagSyntaxSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setNamingConvention

    public void setNamingConvention(int namingConvention)

See `Configuration.setNamingConvention(int)`.

#### getNamingConvention

    public int getNamingConvention()

The getter pair of `setNamingConvention(int)`.

Specified by:
  `getNamingConvention` in interface `ParserConfiguration`

#### isNamingConventionSet

    public boolean isNamingConventionSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setWhitespaceStripping

    public void setWhitespaceStripping(boolean whitespaceStripping)

See `Configuration.setWhitespaceStripping(boolean)`.

#### getWhitespaceStripping

    public boolean getWhitespaceStripping()

The getter pair of `getWhitespaceStripping()`.

Specified by:
  `getWhitespaceStripping` in interface `ParserConfiguration`

#### isWhitespaceStrippingSet

    public boolean isWhitespaceStrippingSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setAutoEscapingPolicy

    public void setAutoEscapingPolicy(int autoEscapingPolicy)

Sets the output format of the template; see `Configuration.setAutoEscapingPolicy(int)` for more.

#### getAutoEscapingPolicy

    public int getAutoEscapingPolicy()

The getter pair of `setAutoEscapingPolicy(int)`.

Specified by:
  `getAutoEscapingPolicy` in interface `ParserConfiguration`

#### isAutoEscapingPolicySet

    public boolean isAutoEscapingPolicySet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setOutputFormat

    public void setOutputFormat(OutputFormat outputFormat)

Sets the output format of the template; see `Configuration.setOutputFormat(OutputFormat)` for more.

#### getOutputFormat

    public OutputFormat getOutputFormat()

The getter pair of `setOutputFormat(OutputFormat)`.

Specified by:
  `getOutputFormat` in interface `ParserConfiguration`

#### isOutputFormatSet

    public boolean isOutputFormatSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setRecognizeStandardFileExtensions

    public void setRecognizeStandardFileExtensions(boolean recognizeStandardFileExtensions)

See `Configuration.setRecognizeStandardFileExtensions(boolean)`.

#### getRecognizeStandardFileExtensions

    public boolean getRecognizeStandardFileExtensions()

Getter pair of `setRecognizeStandardFileExtensions(boolean)`.

Specified by:
  `getRecognizeStandardFileExtensions` in interface `ParserConfiguration`

#### isRecognizeStandardFileExtensionsSet

    public boolean isRecognizeStandardFileExtensionsSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setStrictSyntaxMode

    public void setStrictSyntaxMode(boolean strictSyntaxMode)

See `Configuration.setStrictSyntaxMode(boolean)`.

#### getStrictSyntaxMode

    public boolean getStrictSyntaxMode()

The getter pair of `setStrictSyntaxMode(boolean)`.

Specified by:
  `getStrictSyntaxMode` in interface `ParserConfiguration`

#### isStrictSyntaxModeSet

    public boolean isStrictSyntaxModeSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

#### setStrictBeanModels

    public void setStrictBeanModels(boolean strict)

Overrides:
  `setStrictBeanModels` in class `Configurable`

#### getEncoding

    public String getEncoding()

#### setEncoding

    public void setEncoding(String encoding)

When the standard template loading/caching mechanism is used, this forces the charset used for reading the template "file", overriding everything but the encoding coming from the `#ftl` header. This setting overrides the locale-specific encodings set via `Configuration.setEncoding(java.util.Locale, String)`. It also overrides the `encoding` parameter of `Configuration.getTemplate(String, String)` (and of its overloads) and the `encoding` parameter of the `#include` directive. This works like that because specifying the encoding where you are requesting the template is error prone and deprecated.

If you are developing your own template loading/caching mechanism instead of the standard one, note that the above behavior is not guaranteed by this class alone; you have to ensure it. Also, read the note on `encoding` in the documentation of `apply(Template)`.

#### isEncodingSet

    public boolean isEncodingSet()

#### setTabSize

    public void setTabSize(int tabSize)

See `Configuration.setTabSize(int)`.

Since:
  2.3.25

#### getTabSize

    public int getTabSize()

Getter pair of `setTabSize(int)`.

Specified by:
  `getTabSize` in interface `ParserConfiguration`
Since:
  2.3.25

#### isTabSizeSet

    public boolean isTabSizeSet()

Tells if this setting is set directly in this object or its value is coming from the `parent`.

Since:
  2.3.25

#### getIncompatibleImprovements

    public Version getIncompatibleImprovements()

Returns `Configuration.getIncompatibleImprovements()` from the parent `Configuration`. This mostly just exist to satisfy the `ParserConfiguration` interface.

Specified by:
  `getIncompatibleImprovements` in interface `ParserConfiguration`
Throws:
  `IllegalStateException` - If the parent configuration wasn't yet set.