Package 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, or an IllegalStateException 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(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, 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
TemplateConfiguration()	Creates a new instance.

Method Summary

Modifier and Type	Method	Description
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	getInterpolationSyntax()	The getter pair of setInterpolationSyntax(int).
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	isInterpolationSyntaxSet()	Tells if this setting is set directly in this object or its value is coming from the parent.
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	setInterpolationSyntax(int interpolationSyntax)	See Configuration.setInterpolationSyntax(int).
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, 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, setTemplateExceptionHandler, setTimeFormat, setTimeZone, settingValueAssignmentException, setTruncateBuiltinAlgorithm, setURLEscapingCharset, setWrapUncheckedExceptions, 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 Details

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 Details

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.

setInterpolationSyntax

public void setInterpolationSyntax(int interpolationSyntax)

See Configuration.setInterpolationSyntax(int).

getInterpolationSyntax

public int getInterpolationSyntax()

The getter pair of setInterpolationSyntax(int).

Specified by:

getInterpolationSyntax in interface ParserConfiguration

isInterpolationSyntaxSet

public boolean isInterpolationSyntaxSet()

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.