public final class Environment extends Configurable
Data models that need to access the Environment object that represents the template processing on the
current thread can use the getCurrentEnvironment()
method.
If you need to modify or read this object before or after the process call, use
Template.createProcessingEnvironment(Object rootMap, Writer out, ObjectWrapper wrapper)
Modifier and Type | Class and Description |
---|---|
class |
Environment.Namespace |
Configurable.SettingValueAssignmentException, Configurable.UnknownSettingException
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 and Description |
---|
Environment(Template template,
TemplateHashModel rootDataModel,
java.io.Writer out) |
Modifier and Type | Method and Description |
---|---|
java.lang.Object |
__getitem__(java.lang.String key)
A hook that Jython uses.
|
void |
__setitem__(java.lang.String key,
java.lang.Object o)
A hook that Jython uses.
|
boolean |
applyEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "==" operator. |
boolean |
applyEqualsOperatorLenient(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "==" operator, except that if the two types
are incompatible, they are treated as non-equal instead of throwing an exception. |
boolean |
applyGreaterThanOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL ">" operator. |
boolean |
applyLessThanOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "<" operator. |
boolean |
applyLessThanOrEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL "<" operator. |
boolean |
applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue,
TemplateModel rightValue)
Compares two
TemplateModel -s according the rules of the FTL ">=" operator. |
java.text.NumberFormat |
getCNumberFormat()
Deprecated.
Use
getCTemplateNumberFormat() instead. This method can't return the format used when
Incompatible Improvements is 2.3.32,
or greater, and instead it will fall back to return the format that was used for 2.3.31. Also, as its described
earlier, this method was inconsistent with ?c between Incompatible Improvements 2.3.21 and 2.3.30, while
getCTemplateNumberFormat() behaves as ?c for all Incompatible Improvements value. |
Configuration |
getConfiguration() |
TemplateNumberFormat |
getCTemplateNumberFormat()
|
DirectiveCallPlace |
getCurrentDirectiveCallPlace()
Gets the currently executing custom directive's call place information, or
null if there's no
executing custom directive. |
static Environment |
getCurrentEnvironment()
Retrieves the environment object associated with the current thread, or
null if there's no template
processing going on in this thread. |
Environment.Namespace |
getCurrentNamespace()
Returns the current namespace.
|
Template |
getCurrentTemplate()
Returns the
Template that we are "lexically" inside at the moment. |
TemplateNodeModel |
getCurrentVisitorNode() |
java.lang.Object |
getCustomState(java.lang.Object identityKey)
Returns the value of a custom state variable, or
null if it's missing; see
setCustomState(Object, Object) for more. |
TemplateHashModel |
getDataModel()
Returns a view of the data-model (also known as the template context in some other template engines)
that falls back to shared variables.
|
TemplateModel |
getDataModelOrSharedVariable(java.lang.String name)
Returns the variable from the data-model, or if it's not there, then from the
Configuration.setSharedVariables(Map) shared variables}
|
java.lang.String |
getDefaultNS() |
Environment.Namespace |
getGlobalNamespace()
Returns the name-space that contains the globally visible non-data-model variables (usually created with
<#global ...> ). |
TemplateModel |
getGlobalVariable(java.lang.String name)
Returns the globally visible variable of the given name, or
null . |
TemplateHashModel |
getGlobalVariables()
Returns the read-only hash of globally visible variables.
|
java.util.Set |
getKnownVariableNames()
Returns a set of variable names that are known at the time of call.
|
TemplateModel |
getLocalVariable(java.lang.String name)
Returns the loop or macro local variable corresponding to this variable name.
|
Environment.Namespace |
getMainNamespace()
Returns the main namespace.
|
Template |
getMainTemplate()
Returns the topmost
Template , with other words, the one for which this Environment was created. |
Environment.Namespace |
getNamespace(java.lang.String name)
Returns the name-space for the name if exists, or null.
|
java.lang.String |
getNamespaceForPrefix(java.lang.String prefix) |
java.io.Writer |
getOut() |
java.lang.String |
getPrefixForNamespace(java.lang.String nsURI) |
Template |
getTemplate()
Deprecated.
Use
getMainTemplate() instead (or getCurrentNamespace() and then
Environment.Namespace.getTemplate() ); the value returned by this method is often not what you expect when
it comes to macro/function invocations. |
TemplateDateFormat |
getTemplateDateFormat(int dateType,
java.lang.Class<? extends java.util.Date> dateClass)
Gets a
TemplateDateFormat using the date/time/datetime format settings and the current locale and time
zone. |
TemplateDateFormat |
getTemplateDateFormat(java.lang.String formatString,
int dateType,
java.lang.Class<? extends java.util.Date> dateClass)
Gets a
TemplateDateFormat for the specified format string and the current locale and time zone. |
TemplateDateFormat |
getTemplateDateFormat(java.lang.String formatString,
int dateType,
java.lang.Class<? extends java.util.Date> dateClass,
java.util.Locale locale)
Like
getTemplateDateFormat(String, int, Class) , but allows you to use a different locale than the
current one. |
TemplateDateFormat |
getTemplateDateFormat(java.lang.String formatString,
int dateType,
java.lang.Class<? extends java.util.Date> dateClass,
java.util.Locale locale,
java.util.TimeZone timeZone,
java.util.TimeZone sqlDateAndTimeTimeZone)
Like
getTemplateDateFormat(String, int, Class) , but allows you to use a different locale and time zone
than the current one. |
TemplateDateFormat |
getTemplateDateFormat(java.lang.String formatString,
int dateType,
java.util.Locale locale,
java.util.TimeZone timeZone,
boolean zonelessInput)
Gets a
TemplateDateFormat for the specified parameters. |
Template |
getTemplateForImporting(java.lang.String name)
Gets a template for importing; used with
importLib(Template importedTemplate, String namespace) . |
Template |
getTemplateForInclusion(java.lang.String name,
java.lang.String encoding,
boolean parse)
Same as
getTemplateForInclusion(String, String, boolean, boolean) with false
ignoreMissing argument. |
Template |
getTemplateForInclusion(java.lang.String name,
java.lang.String encoding,
boolean parseAsFTL,
boolean ignoreMissing)
Gets a template for inclusion; used for implementing
include(Template includedTemplate) . |
TemplateNumberFormat |
getTemplateNumberFormat()
Returns the current number format (
Configurable.getNumberFormat() ) as TemplateNumberFormat . |
TemplateNumberFormat |
getTemplateNumberFormat(java.lang.String formatString)
Returns the number format as
TemplateNumberFormat for the given format string and the current locale. |
TemplateNumberFormat |
getTemplateNumberFormat(java.lang.String formatString,
java.util.Locale locale)
Returns the number format as
TemplateNumberFormat , for the given format string and locale. |
TemplateModel |
getVariable(java.lang.String name)
Returns the variable that is visible in this context, or
null if the variable is not found. |
Environment.Namespace |
importLib(java.lang.String templateName,
java.lang.String targetNsVarName)
Emulates
import directive, except that templateName must be template root relative. |
Environment.Namespace |
importLib(java.lang.String templateName,
java.lang.String targetNsVarName,
boolean lazy)
Like
importLib(String, String) , but you can specify if you want a
lazy import or not. |
Environment.Namespace |
importLib(Template loadedTemplate,
java.lang.String targetNsVarName)
Does what the
#import directive does, but with an already loaded template. |
void |
include(java.lang.String name,
java.lang.String encoding,
boolean parse)
Emulates
include directive, except that name must be template root relative. |
void |
include(Template includedTemplate)
Processes a Template in the context of this
Environment , including its output in the
Environment 's Writer. |
boolean |
isInAttemptBlock()
Tells if we are inside an #attempt block (but before #recover).
|
void |
outputInstructionStack(java.io.PrintWriter pw)
Prints the current FTL stack trace.
|
void |
process()
Processes the template to which this environment belongs to.
|
java.lang.String |
rootBasedToAbsoluteTemplateName(java.lang.String rootBasedName)
Converts a root based name (a name that's either relative to the root, or is absolute), which are typically used
by the API (such as for
Configuration.getTemplate(String) ), to an absolute name, which can be safely
passed to <#include path> and such, as it won't be misinterpreted to be relative to the directory of the
template. |
void |
setBooleanFormat(java.lang.String booleanFormat)
The string value for the boolean
true and false values, usually intended for human consumption
(not for a computer language), separated with comma. |
void |
setCFormat(CFormat cFormat)
Sets the format (usually a computer language) used for
?c , ?cn , and for the
"c" ("computer" before 2.3.32) number_format , and the
"c" boolean_format . |
void |
setCurrentVisitorNode(TemplateNodeModel node)
sets TemplateNodeModel as the current visitor node.
|
java.lang.Object |
setCustomState(java.lang.Object identityKey,
java.lang.Object value)
Sets the value of a custom state variable.
|
void |
setDateFormat(java.lang.String dateFormat)
Sets the format used to convert
Date -s that are date-only (no time part) values to string-s,
also the format that someString?date will use to parse strings. |
void |
setDateTimeFormat(java.lang.String dateTimeFormat)
Sets the format used to convert
Date -s that are date-time (timestamp) values to string-s,
also the format that someString?datetime will use to parse strings. |
void |
setGlobalVariable(java.lang.String name,
TemplateModel value)
Sets a variable in the global namespace, like
<#global name=value> . |
void |
setLocale(java.util.Locale locale)
Sets the locale used for number and date formatting (among others), also the locale used for searching
localized template variations when no locale was explicitly requested.
|
void |
setLocalVariable(java.lang.String name,
TemplateModel value)
Sets a local variable that's on the top-level inside a macro or function invocation, like
<#local name=value> . |
void |
setNumberFormat(java.lang.String formatName)
Sets the number format used to convert numbers to strings.
|
void |
setOut(java.io.Writer out) |
void |
setOutputEncoding(java.lang.String outputEncoding)
Informs FreeMarker about the charset used for the output.
|
void |
setSQLDateAndTimeTimeZone(java.util.TimeZone timeZone)
Sets the time zone used when dealing with
java.sql.Date and
java.sql.Time values. |
void |
setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Sets the exception handler used to handle exceptions occurring inside templates.
|
void |
setTimeFormat(java.lang.String timeFormat)
Sets the format used to convert
Date -s that are time (no date part) values to string-s, also
the format that someString?time will use to parse strings. |
void |
setTimeZone(java.util.TimeZone timeZone)
Sets the time zone to use when formatting date/time values.
|
void |
setURLEscapingCharset(java.lang.String urlEscapingCharset)
Sets the URL escaping (URL encoding, percentage encoding) charset.
|
void |
setVariable(java.lang.String name,
TemplateModel value)
Sets a variable in the current namespace, like
<#assign name=value> . |
java.lang.String |
toFullTemplateName(java.lang.String baseName,
java.lang.String targetName)
Resolves a reference to a template (like the one used in
#include or #import ), assuming a base
name. |
void |
visit(freemarker.core.TemplateElement element,
TemplateDirectiveModel directiveModel,
java.util.Map args,
java.util.List bodyParameterNames)
Deprecated.
Should be internal API
|
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, setClassicCompatible, setClassicCompatibleAsInt, setCustomAttribute, setCustomDateFormats, setCustomNumberFormats, setLazyAutoImports, setLazyImports, setLogTemplateExceptions, setNewBuiltinClassResolver, setObjectWrapper, setSetting, setSettings, setSettings, setShowErrorTips, setStrictBeanModels, settingValueAssignmentException, setTruncateBuiltinAlgorithm, setWrapUncheckedExceptions, unknownSettingException
public Environment(Template template, TemplateHashModel rootDataModel, java.io.Writer out)
public static Environment getCurrentEnvironment()
null
if there's no template
processing going on in this thread. Data model implementations that need access to the environment can call this
method to obtain the environment object that represents the template processing that is currently running on the
current thread.@Deprecated public Template getTemplate()
getMainTemplate()
instead (or getCurrentNamespace()
and then
Environment.Namespace.getTemplate()
); the value returned by this method is often not what you expect when
it comes to macro/function invocations.Configurable.getParent()
. If Configuration.getIncompatibleImprovements()
is
at least 2.3.22, then that will be the same as getMainTemplate()
. Otherwise the returned value follows
the Environment
parent switchings that occur at #include
/#import
and #nested
directive calls, that is, it's not very meaningful outside FreeMarker internals.public Template getMainTemplate()
Template
, with other words, the one for which this Environment
was created.
That template will never change, like #include
or macro calls don't change it. This method never returns
null
.getCurrentNamespace()
public Template getCurrentTemplate()
Template
that we are "lexically" inside at the moment. This template will change when
entering an #include
or calling a macro or function in another template, or returning to yet another
template with #nested
. When you are calling a directive that's implemented in Java or a Java method
from a template, the current template will be the last current template, not null
. This method never
returns null
.getMainTemplate()
,
getCurrentNamespace()
public DirectiveCallPlace getCurrentDirectiveCallPlace()
null
if there's no
executing custom directive. This currently only works for calls made from templates with the <@...>
syntax. This should only be called from the TemplateDirectiveModel
that was invoked with <@...>
,
otherwise its return value is not defined by this API (it's usually null
).public void process() throws TemplateException, java.io.IOException
TemplateException
java.io.IOException
@Deprecated public void visit(freemarker.core.TemplateElement element, TemplateDirectiveModel directiveModel, java.util.Map args, java.util.List bodyParameterNames) throws TemplateException, java.io.IOException
TemplateException
java.io.IOException
public boolean isInAttemptBlock()
TemplateExceptionHandler
-s, as then they may don't want to print the error to the output, as
#attempt will roll it back anyway.public void setTemplateExceptionHandler(TemplateExceptionHandler templateExceptionHandler)
Configurable
TemplateExceptionHandler.DEBUG_HANDLER
. The recommended values are:
TemplateExceptionHandler.RETHROW_HANDLER
TemplateExceptionHandler.HTML_DEBUG_HANDLER
TemplateExceptionHandler.DEBUG_HANDLER
All of these will let the exception propagate further, so that you can catch it around
Template.process(Object, Writer)
for example. The difference is in what they print on the output before
they do that.
Note that the TemplateExceptionHandler
is not meant to be used for generating HTTP error pages.
Neither is it meant to be used to roll back the printed output. These should be solved outside template
processing when the exception raises from Template.process
.
TemplateExceptionHandler
meant to be used if you want to include special content in the template
output, or if you want to suppress certain exceptions. If you suppress an exception, and the
Configurable.getLogTemplateExceptions()
returns false
, then it's the responsibility of the
TemplateExceptionHandler
to log the exception (if you want it to be logged).
public void setLocale(java.util.Locale locale)
Configurable
Configuration
level it
defaults to the default locale of system (of the JVM), for server-side application usually you should set it
explicitly in the Configuration
to use the preferred locale of your application instead.setLocale
in class Configurable
Configuration.getTemplate(String, Locale)
public void setTimeZone(java.util.TimeZone timeZone)
Configurable
TimeZone.getDefault()
), regardless of the "locale" FreeMarker setting,
so in a server application you probably want to set it explicitly in the Environment
to match the
preferred time zone of target audience (like the Web page visitor).
If you or the templates set the time zone, you should probably also set
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
!
setTimeZone
in class Configurable
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
public void setSQLDateAndTimeTimeZone(java.util.TimeZone timeZone)
Configurable
java.sql.Date
and
java.sql.Time
values. It defaults to null
for backward compatibility, but in most
applications this should be set to the JVM default time zone (server default time zone), because that's what
most JDBC drivers will use when constructing the java.sql.Date
and
java.sql.Time
values. If this setting is null
, FreeMarker will use the value of
(Configurable.getTimeZone()
) for java.sql.Date
and java.sql.Time
values,
which often gives bad results.
This setting doesn't influence the formatting of other kind of values (like of
java.sql.Timestamp
or plain java.util.Date
values).
To decide what value you need, a few things has to be understood:
Date
and its subclasses store (milliseconds since
the epoch). Obviously, this is impossible to do. So JDBC just chooses a physical time which, when rendered
with the JVM default time zone, will give the same field values as those stored
in the database. (Actually, you can give JDBC a calendar, and so it can use other time zones too, but most
application won't care using those overloads.) For example, assume that the system time zone is GMT+02:00.
Then, 2014-07-12 in the database will be translated to physical time 2014-07-11 22:00:00 UTC, because that
rendered in GMT+02:00 gives 2014-07-12 00:00:00. Similarly, 11:57:00 in the database will be translated to
physical time 1970-01-01 09:57:00 UTC. Thus, the physical time stored in the returned value depends on the
default system time zone of the JDBC client, not just on the content of the database. (This used to be the
default behavior of ORM-s, like Hibernate, too.)
time_zone
FreeMarker configuration setting sets the time zone used for the
template output. For example, when a web page visitor has a preferred time zone, the web application framework
may calls setTimeZone(TimeZone)
with that time zone. Thus, the visitor will
see java.sql.Timestamp
and plain java.util.Date
values as
they look in his own time zone. While
this is desirable for those types, as they meant to represent physical points on the time line, this is not
necessarily desirable for date-only and time-only values. When sql_date_and_time_time_zone
is
null
, time_zone
is used for rendering all kind of date/time/dateTime values, including
java.sql.Date
and java.sql.Time
, and then if, for example,
time_zone
is GMT+00:00, the
values from the earlier examples will be shown as 2014-07-11 (one day off) and 09:57:00 (2 hours off). While
those are the time zone correct renderings, those values are probably meant to be shown "as is".
java.sql.Timestamp
values as well. Timestamps in databases refer to a point on
the physical time line, and thus doesn't have the inherent problem of date-only and time-only values.
FreeMarker assumes that the JDBC driver converts time stamps coming from the database so that they store
the distance from the epoch (1970-01-01 00:00:00 UTC), as requested by the Date
API.
Then time stamps can be safely rendered in different time zones, and thus need no special treatment.
setSQLDateAndTimeTimeZone
in class Configurable
timeZone
- Maybe null
, in which case java.sql.Date
and
java.sql.Time
values will be formatted in the time zone returned by
Configurable.getTimeZone()
.
(Note that since null
is an allowed value for this setting, it will not cause
Configurable.getSQLDateAndTimeTimeZone()
to fall back to the parent configuration.)Configurable.setTimeZone(TimeZone)
public void setURLEscapingCharset(java.lang.String urlEscapingCharset)
Configurable
null
, the output encoding
(Configurable.setOutputEncoding(String)
) will be used for URL escaping.
Defaults to null
.setURLEscapingCharset
in class Configurable
public void setOutputEncoding(java.lang.String outputEncoding)
Configurable
null
means that the output encoding is not known.
Defaults to null
(unknown).
setOutputEncoding
in class Configurable
public boolean applyEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "==" operator.TemplateException
public boolean applyEqualsOperatorLenient(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "==" operator, except that if the two types
are incompatible, they are treated as non-equal instead of throwing an exception. Comparing dates of different
types (date-only VS time-only VS date-time) will still throw an exception, however.TemplateException
public boolean applyLessThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "<" operator.TemplateException
public boolean applyLessThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL "<" operator.TemplateException
public boolean applyGreaterThanOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL ">" operator.TemplateException
public boolean applyWithGreaterThanOrEqualsOperator(TemplateModel leftValue, TemplateModel rightValue) throws TemplateException
TemplateModel
-s according the rules of the FTL ">=" operator.TemplateException
public void setOut(java.io.Writer out)
public java.io.Writer getOut()
public void setNumberFormat(java.lang.String formatName)
Configurable
"number"
: The number format returned by NumberFormat.getNumberInstance(Locale)
. This is the
default."c"
(recognized since 2.3.32): The number format used by FTL's c
built-in (like in
someNumber?c
). So with this ${someNumber}
will output the same as
${someNumber?c}
. This should only be used if the template solely generates source code,
configuration file, or other content that's not read by normal users. If the template contains parts that's
read by normal users (like typical a web page), you are not supposed to use this."computer"
: The old (deprecated) name for "c"
. Recognized by all FreeMarker versions."currency"
: The number format returned by NumberFormat.getCurrencyInstance(Locale)
"percent"
: The number format returned by NumberFormat.getPercentInstance(Locale)
DecimalFormat
pattern (like "0.##"
). This syntax is extended by FreeMarker
so that you can specify options like the rounding mode and the symbols used after a 2nd semicolon. For
example, ",000;; roundingMode=halfUp groupingSeparator=_"
will format numbers like ",000"
would, but with half-up rounding mode, and _
as the group separator. See more about "extended Java
decimal format" in the FreeMarker Manual.
@
character followed by a letter then it's interpreted as a custom number
format, but only if either Configuration.getIncompatibleImprovements()
is at least 2.3.24, or
there's any custom formats defined (even if custom date/time/dateTime format). The format of a such string
is "@name"
or "@name parameters"
, where
name
is the key in the Map
set by Configurable.setCustomNumberFormats(Map)
, and
parameters
is parsed by the custom TemplateNumberFormat
.
Defaults to "number".
setNumberFormat
in class Configurable
public TemplateNumberFormat getTemplateNumberFormat() throws TemplateValueFormatException
Configurable.getNumberFormat()
) as TemplateNumberFormat
.
Performance notes: The result is stored for reuse, so calling this method frequently is usually not a problem.
However, at least as of this writing (2.3.24), changing the current locale setLocale(Locale)
or changing
the current number format (setNumberFormat(String)
) will drop the stored value, so it will have to be
recalculated.
TemplateValueFormatException
public TemplateNumberFormat getTemplateNumberFormat(java.lang.String formatString) throws TemplateValueFormatException
TemplateNumberFormat
for the given format string and the current locale.
(The current locale is the locale returned by Configurable.getLocale()
.) Note that the result will be cached in the
Environment
instance (though at least in 2.3.24 the cache will be flushed if the current locale of the
Environment
is changed).formatString
- A string that you could also use as the value of the numberFormat
configuration setting. Can't
be null
.TemplateValueFormatException
public TemplateNumberFormat getTemplateNumberFormat(java.lang.String formatString, java.util.Locale locale) throws TemplateValueFormatException
TemplateNumberFormat
, for the given format string and locale. To get a
number format for the current locale, use getTemplateNumberFormat(String)
instead.
Note on performance (which was true at least for 2.3.24): Unless the locale happens to be equal to the current
locale, the Environment
-level format cache can't be used, so the format string has to be parsed and the
matching factory has to be get an invoked, which is much more expensive than getting the format from the cache.
Thus the returned format should be stored by the caller for later reuse (but only within the current thread and
in relation to the current Environment
), if it will be needed frequently.
formatString
- A string that you could also use as the value of the numberFormat
configuration setting.locale
- The locale of the number format; not null
.TemplateValueFormatException
@Deprecated public java.text.NumberFormat getCNumberFormat()
getCTemplateNumberFormat()
instead. This method can't return the format used when
Incompatible Improvements is 2.3.32,
or greater, and instead it will fall back to return the format that was used for 2.3.31. Also, as its described
earlier, this method was inconsistent with ?c
between Incompatible Improvements 2.3.21 and 2.3.30, while
getCTemplateNumberFormat()
behaves as ?c
for all Incompatible Improvements value.NumberFormat
used for the c built-in, except, if
Incompatible Improvements is less than 2.3.31,
this will wrongly give the format that the c built-in used before Incompatible Improvements 2.3.21.
See more at Configuration.Configuration(Version)
.public TemplateNumberFormat getCTemplateNumberFormat()
TemplateNumberFormat
that ?c
/?cn
uses.
Calling this method for many times is fine, as it internally caches the result object.
Remember that TemplateNumberFormat
-s aren't thread-safe objects, so the resulting object should only
be used in the same thread where this Environment
runs.public void setCFormat(CFormat cFormat)
Configurable
?c
, ?cn
, and for the
"c"
("computer"
before 2.3.32) number_format
, and the
"c"
boolean_format
.
The default value depends on incompatible_improvements
.
If that's 2.3.32 or higher, then it's "JavaScript or JSON"
,
otherwise it's "legacy"
.
setCFormat
in class Configurable
public void setTimeFormat(java.lang.String timeFormat)
Configurable
Date
-s that are time (no date part) values to string-s, also
the format that someString?time
will use to parse strings.
For the possible values see Configurable.setDateTimeFormat(String)
.
Defaults to ""
, which is equivalent to "medium"
.
setTimeFormat
in class Configurable
public void setDateFormat(java.lang.String dateFormat)
Configurable
Date
-s that are date-only (no time part) values to string-s,
also the format that someString?date
will use to parse strings.
For the possible values see Configurable.setDateTimeFormat(String)
.
Defaults to ""
which is equivalent to "medium"
.
setDateFormat
in class Configurable
public void setDateTimeFormat(java.lang.String dateTimeFormat)
Configurable
Date
-s that are date-time (timestamp) values to string-s,
also the format that someString?datetime
will use to parse strings.
The possible setting values are (the quotation marks aren't part of the value itself):
Patterns accepted by Java's SimpleDateFormat
, for example "dd.MM.yyyy HH:mm:ss"
(where
HH
means 24 hours format) or "MM/dd/yyyy hh:mm:ss a"
(where a
prints AM or PM, if
the current language is English).
"xs"
for XML Schema format, or "iso"
for ISO 8601:2004 format.
These formats allow various additional options, separated with space, like in
"iso m nz"
(or with _
, like in "iso_m_nz"
; this is useful in a case like
lastModified?string.iso_m_nz
). The options and their meanings are:
Accuracy options:
ms
= Milliseconds, always shown with all 3 digits, even if it's all 0-s.
Example: 13:45:05.800
s
= Seconds (fraction seconds are dropped even if non-0), like 13:45:05
m
= Minutes, like 13:45
. This isn't allowed for "xs".
h
= Hours, like 13
. This isn't allowed for "xs".
Neither = Up to millisecond accuracy, but trailing millisecond 0-s are removed, also the whole
milliseconds part if it would be 0 otherwise. Example: 13:45:05.8
Time zone offset visibility options:
fz
= "Force Zone", always show time zone offset (even for for
java.sql.Date
and java.sql.Time
values).
But, because ISO 8601 doesn't allow for dates (means date without time of the day) to
show the zone offset, this option will have no effect in the case of "iso"
with
dates.
nz
= "No Zone", never show time zone offset
Neither = always show time zone offset, except for java.sql.Date
and java.sql.Time
, and for "iso"
date values.
Time zone options:
u
= Use UTC instead of what the time_zone
setting suggests. However,
java.sql.Date
and java.sql.Time
aren't affected
by this (see Configurable.setSQLDateAndTimeTimeZone(TimeZone)
to understand why)
fu
= "Force UTC", that is, use UTC instead of what the time_zone
or the
sql_date_and_time_time_zone
setting suggests. This also effects
java.sql.Date
and java.sql.Time
values
Neither = Use the time zone suggested by the time_zone
or the
sql_date_and_time_time_zone
configuration setting (Configurable.setTimeZone(TimeZone)
and
Configurable.setSQLDateAndTimeTimeZone(TimeZone)
).
The options can be specified in any order.
Options from the same category are mutually exclusive, like using m
and s
together is an error.
The accuracy and time zone offset visibility options don't influence parsing, only formatting. For example, even if you use "iso m nz", "2012-01-01T15:30:05.125+01" will be parsed successfully and with milliseconds accuracy. The time zone options (like "u") influence what time zone is chosen only when parsing a string that doesn't contain time zone offset.
Parsing with "iso"
understands both extend format and basic format, like
20141225T235018
. It doesn't, however, support the parsing of all kind of ISO 8601 strings: if
there's a date part, it must use year, month and day of the month values (not week of the year), and the
day can't be omitted.
The output of "iso"
is deliberately so that it's also a good representation of the value with
XML Schema format, except for 0 and negative years, where it's impossible. Also note that the time zone
offset is omitted for date values in the "iso"
format, while it's preserved for the "xs"
format.
"short"
, "medium"
, "long"
, or "full"
, which that has locale-dependent
meaning defined by the Java platform (see in the documentation of DateFormat
).
For date-time values, you can specify the length of the date and time part independently, be separating
them with _
, like "short_medium"
. ("medium"
means
"medium_medium"
for date-time values.)
Anything that starts with "@"
followed by a letter is interpreted as a custom
date/time/dateTime format, but only if either Configuration.getIncompatibleImprovements()
is at least 2.3.24, or there's any custom formats defined (even if custom number format). The format of
such string is "@name"
or "@name parameters"
, where
name
is the key in the Map
set by Configurable.setCustomDateFormats(Map)
, and
parameters
is parsed by the custom number format.
Defaults to ""
, which is equivalent to "medium_medium"
.
setDateTimeFormat
in class Configurable
public void setBooleanFormat(java.lang.String booleanFormat)
Configurable
true
and false
values, usually intended for human consumption
(not for a computer language), separated with comma. For example, "yes,no"
. Note that white-space is
significant, so "yes, no"
is WRONG (unless you want that leading space before "no"). Because the proper
way of formatting booleans depends on the context too much, it's probably the best to leave this setting on its
default, which will enforce explicit formatting, like ${aBoolean?string('on', 'off')}
.
For backward compatibility the default is "true,false"
, but using that value is denied for automatic
boolean-to-string conversion, like ${myBoolean}
will fail with it. If you generate the piece of
output for "computer audience" as opposed to "human audience", then you should write
${myBoolean?c}
, which will print true
or false
. If you really want to always
format for computer audience, then it's might be reasonable to set this setting to c
.
Note that automatic boolean-to-string conversion only exists since FreeMarker 2.3.20. Earlier this setting
only influenced the result of myBool?string
.
setBooleanFormat
in class Configurable
public Configuration getConfiguration()
public TemplateDateFormat getTemplateDateFormat(int dateType, java.lang.Class<? extends java.util.Date> dateClass) throws TemplateValueFormatException
TemplateDateFormat
using the date/time/datetime format settings and the current locale and time
zone. (The current locale is the locale returned by Configurable.getLocale()
. The current time zone is
Configurable.getTimeZone()
or Configurable.getSQLDateAndTimeTimeZone()
).dateType
- The FTL date type; see the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
dateClass
- The exact Date
class, like Date
or Time
; this can influences
time zone selection. See also: setSQLDateAndTimeTimeZone(TimeZone)
TemplateValueFormatException
public TemplateDateFormat getTemplateDateFormat(java.lang.String formatString, int dateType, java.lang.Class<? extends java.util.Date> dateClass) throws TemplateValueFormatException
TemplateDateFormat
for the specified format string and the current locale and time zone. (The
current locale is the locale returned by Configurable.getLocale()
. The current time zone is Configurable.getTimeZone()
or
Configurable.getSQLDateAndTimeTimeZone()
).
Note on performance: The result will be cached in the Environment
instance. However, at least in 2.3.24
the cached entries that depend on the current locale or the current time zone or the current date/time/datetime
format of the Environment
will be lost when those settings are changed.
formatString
- Like "iso m"
or "dd.MM.yyyy HH:mm"
or "@somethingCustom"
or
"@somethingCustom params"
TemplateValueFormatException
public TemplateDateFormat getTemplateDateFormat(java.lang.String formatString, int dateType, java.lang.Class<? extends java.util.Date> dateClass, java.util.Locale locale) throws TemplateValueFormatException
getTemplateDateFormat(String, int, Class)
, but allows you to use a different locale than the
current one. If you want to use the current locale, use getTemplateDateFormat(String, int, Class)
instead.
Performance notes regarding the locale and time zone parameters of
getTemplateDateFormat(String, int, Locale, TimeZone, boolean)
apply.
locale
- Can't be null
; See the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
TemplateValueFormatException
getTemplateDateFormat(String, int, Class)
public TemplateDateFormat getTemplateDateFormat(java.lang.String formatString, int dateType, java.lang.Class<? extends java.util.Date> dateClass, java.util.Locale locale, java.util.TimeZone timeZone, java.util.TimeZone sqlDateAndTimeTimeZone) throws TemplateValueFormatException
getTemplateDateFormat(String, int, Class)
, but allows you to use a different locale and time zone
than the current one. If you want to use the current locale and time zone, use
getTemplateDateFormat(String, int, Class)
instead.
Performance notes regarding the locale and time zone parameters of
getTemplateDateFormat(String, int, Locale, TimeZone, boolean)
apply.
timeZone
- The TimeZone
used if dateClass
is not an SQL date-only or time-only type. Can't be
null
.sqlDateAndTimeTimeZone
- The TimeZone
used if dateClass
is an SQL date-only or time-only type. Can't be
null
.TemplateValueFormatException
getTemplateDateFormat(String, int, Class)
public TemplateDateFormat getTemplateDateFormat(java.lang.String formatString, int dateType, java.util.Locale locale, java.util.TimeZone timeZone, boolean zonelessInput) throws TemplateValueFormatException
TemplateDateFormat
for the specified parameters. This is mostly meant to be used by
TemplateDateFormatFactory
implementations to delegate to a format based on a specific format string. It
works well for that, as its parameters are the same low level values as the parameters of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
. For other tasks
consider the other overloads of this method.
Note on performance (which was true at least for 2.3.24): Unless the locale happens to be equal to the current
locale and the time zone with one of the current time zones (Configurable.getTimeZone()
or
Configurable.getSQLDateAndTimeTimeZone()
), the Environment
-level format cache can't be used, so the format
string has to be parsed and the matching factory has to be get an invoked, which is much more expensive than
getting the format from the cache. Thus the returned format should be stored by the caller for later reuse (but
only within the current thread and in relation to the current Environment
), if it will be needed
frequently.
formatString
- Like "iso m"
or "dd.MM.yyyy HH:mm"
or "@somethingCustom"
or
"@somethingCustom params"
dateType
- The FTL date type; see the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
timeZone
- Not null
; See the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
locale
- Not null
; See the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
zonelessInput
- See the similar parameter of
TemplateDateFormatFactory.get(String, int, Locale, TimeZone, boolean, Environment)
TemplateValueFormatException
public TemplateModel getLocalVariable(java.lang.String name) throws TemplateModelException
null
if no such variable exists with the given name, or the variable was set to
null
. Doesn't read namespace or global variables.TemplateModelException
public TemplateModel getVariable(java.lang.String name) throws TemplateModelException
null
if the variable is not found. This is the
correspondent to an FTL top-level variable reading expression. That is, it tries to find the the variable in this
order:
TemplateModelException
public TemplateModel getGlobalVariable(java.lang.String name) throws TemplateModelException
null
. This corresponds to FTL
.globals.name
. This will first look at variables that were assigned globally via:
<#global ...>
and then at the data model exposed to the template, and then at the
Configuration.setSharedVariables(Map) shared variables} in the Configuration
.TemplateModelException
public TemplateModel getDataModelOrSharedVariable(java.lang.String name) throws TemplateModelException
TemplateModelException
public void setGlobalVariable(java.lang.String name, TemplateModel value)
<#global name=value>
.
This can be considered a convenient shorthand for getGlobalNamespace().put(name, model)
.
Note that this is not an exact pair of getGlobalVariable(String)
, as that falls back to higher scopes
if the variable is not in the global namespace.
name
- The name of the variable.value
- The new value of the variable. null
in effect removes the local variable (reading it will fall
back to higher scope).public void setVariable(java.lang.String name, TemplateModel value)
<#assign name=value>
.
This can be considered a convenient shorthand for: getCurrentNamespace().put(name, model)
.name
- The name of the variable.value
- The new value of the variable. null
in effect removes the local variable (reading it will fall
back to higher scope).public void setLocalVariable(java.lang.String name, TemplateModel value)
<#local name=value>
.
Note that just like <#local name=value>
, this will not set loop variables; it will totally ignore
them, and might sets a local variable that a loop variable currently "shadows". As such, it's not exactly the
pair of getLocalVariable(String)
, which also reads loop variables.name
- The name of the variable.value
- The new value of the variable. null
in effect removes the local variable (reading it will fall
back to higher scope).java.lang.IllegalStateException
- if the environment is not executing a macro body.public java.util.Set getKnownVariableNames() throws TemplateModelException
Configuration
, names of all global variables that were assigned during the template processing,
names of all variables in the current name-space, names of all local variables and loop variables. If the passed
root data model implements the TemplateHashModelEx
interface, then all names it retrieves through a call
to TemplateHashModelEx.keys()
method are returned as well. The method returns a new Set object on each
call that is completely disconnected from the Environment. That is, modifying the set will have no effect on the
Environment object.TemplateModelException
public void outputInstructionStack(java.io.PrintWriter pw)
TemplateException
s incorporate this information
in their stack traces.public Environment.Namespace getNamespace(java.lang.String name)
name
- the template path that you have used with the import
directive or
importLib(String, String)
call, in normalized form. That is, the path must be an absolute
path, and it must not contain "/../" or "/./". The leading "/" is optional.public Environment.Namespace getMainNamespace()
.main
hash.public Environment.Namespace getCurrentNamespace()
.namespace
hash. Initially, the current name
space is the main namespace, but when inside an #import
-ed template, it will change to the namespace of
that import. Note that #include
doesn't affect the namespace, so if you are in an #import
-ed
template and then from there do an #include
, the current namespace will remain the namespace of the
#import
.public Environment.Namespace getGlobalNamespace()
<#global ...>
).public TemplateHashModel getDataModel()
public TemplateHashModel getGlobalVariables()
.globals
hash. That is, you see the variables created with <#global ...>
, and the variables of the
data-model. To create new global variables, use setGlobalVariable
.public TemplateNodeModel getCurrentVisitorNode()
public void setCurrentVisitorNode(TemplateNodeModel node)
public void include(java.lang.String name, java.lang.String encoding, boolean parse) throws java.io.IOException, TemplateException
include
directive, except that name
must be template root relative.
It's the same as include(getTemplateForInclusion(name, encoding, parse))
. But, you may want to
separately call these two methods, so you can determine the source of exceptions more precisely, and thus achieve
more intelligent error handling.
java.io.IOException
TemplateException
getTemplateForInclusion(String name, String encoding, boolean parse)
,
include(Template includedTemplate)
public Template getTemplateForInclusion(java.lang.String name, java.lang.String encoding, boolean parse) throws java.io.IOException
getTemplateForInclusion(String, String, boolean, boolean)
with false
ignoreMissing
argument.java.io.IOException
public Template getTemplateForInclusion(java.lang.String name, java.lang.String encoding, boolean parseAsFTL, boolean ignoreMissing) throws java.io.IOException
include(Template includedTemplate)
. The advantage
over simply using config.getTemplate(...)
is that it chooses the default encoding exactly as the
include
directive does, although that encoding selection mechanism is a historical baggage and
considered to be harmful.name
- the name of the template, relatively to the template root directory (not the to the directory of the
currently executing template file). (Note that you can use
TemplateCache.getFullTemplatePath(freemarker.core.Environment, java.lang.String, java.lang.String)
to convert paths to template root relative
paths.) For more details see the identical parameter of
Configuration.getTemplate(String, Locale, String, boolean, boolean)
encoding
- the charset of the obtained template. If null
, the encoding of the top template that is
currently being processed in this Environment
is used, which can lead to odd situations, so
using null
is not recommended. In most applications, the value of
Configuration.getEncoding(Locale)
(or Configuration.getDefaultEncoding()
) should be
used here.parseAsFTL
- See identical parameter of Configuration.getTemplate(String, Locale, String, boolean, boolean)
ignoreMissing
- See identical parameter of Configuration.getTemplate(String, Locale, String, boolean, boolean)
Configuration.getTemplate(String, Locale, String, boolean, boolean)
java.io.IOException
- Same as exceptions thrown by
Configuration.getTemplate(String, Locale, String, boolean, boolean)
public void include(Template includedTemplate) throws TemplateException, java.io.IOException
Environment
, including its output in the
Environment
's Writer.includedTemplate
- the template to process. Note that it does not need to be a template returned by
getTemplateForInclusion(String name, String encoding, boolean parse)
.TemplateException
java.io.IOException
public Environment.Namespace importLib(java.lang.String templateName, java.lang.String targetNsVarName) throws java.io.IOException, TemplateException
import
directive, except that templateName
must be template root relative.
It's the same as importLib(getTemplateForImporting(templateName), namespace)
. But, you may want to
separately call these two methods, so you can determine the source of exceptions more precisely, and thus achieve
more intelligent error handling.
If it will be a lazy or an eager import is decided by the value of Configurable.getLazyImports()
. You
can also directly control that aspect by using importLib(String, String, boolean)
instead.
null
. This is possibly a lazily self-initializing namespace, which means that it will only
try to get and process the imported template when you access its content.java.io.IOException
TemplateException
getTemplateForImporting(String templateName)
,
importLib(Template includedTemplate, String namespaceVarName)
,
importLib(String, String, boolean)
public Environment.Namespace importLib(Template loadedTemplate, java.lang.String targetNsVarName) throws java.io.IOException, TemplateException
#import
directive does, but with an already loaded template.loadedTemplate
- The template to import. Note that it does not need to be a template returned by
getTemplateForImporting(String name)
. Not null
.targetNsVarName
- The name of the FTL variable that will store the namespace. If null
, the namespace
won't be stored in a variable (but it's still returned).java.io.IOException
TemplateException
getTemplateForImporting(String name)
,
importLib(Template includedTemplate, String namespaceVarName)
public Environment.Namespace importLib(java.lang.String templateName, java.lang.String targetNsVarName, boolean lazy) throws java.io.IOException, TemplateException
importLib(String, String)
, but you can specify if you want a
lazy import or not.null
. This is possibly a lazily self-initializing namespace, which mean that it will only try
to get and process the imported template when you access its content.java.io.IOException
TemplateException
public Template getTemplateForImporting(java.lang.String name) throws java.io.IOException
importLib(Template importedTemplate, String namespace)
. The
advantage over simply using config.getTemplate(...)
is that it chooses the encoding as the
import
directive does.name
- the name of the template, relatively to the template root directory (not the to the directory of the
currently executing template file!). (Note that you can use
TemplateCache.getFullTemplatePath(freemarker.core.Environment, java.lang.String, java.lang.String)
to convert paths to template root relative
paths.)java.io.IOException
public java.lang.String toFullTemplateName(java.lang.String baseName, java.lang.String targetName) throws MalformedTemplateNameException
#include
or #import
), assuming a base
name. This gives a root based, even if non-normalized and possibly non-absolute (but then relative to the root)
template name, that could be used for Configuration.getTemplate(String)
. This is mostly used when a
template refers to another template.
If you need to guarantee that the result is also an absolute path, then apply
rootBasedToAbsoluteTemplateName(String)
on it.
baseName
- The name to which relative targetName
-s are relative to. Maybe null
(happens when
resolving names in nameless templates), which means that the base is the root "directory", and so the
targetName
is returned without change. Assuming TemplateNameFormat.DEFAULT_2_3_0
or
TemplateNameFormat.DEFAULT_2_4_0
, the rules are as follows. If you want to specify a base
directory here, it must end with "/"
. If it doesn't end with "/"
, it's parent
directory will be used as the base path. Might starts with a scheme part (like "foo://"
, or
with TemplateNameFormat.DEFAULT_2_4_0
even just with "foo:"
).targetName
- The name of the template, which is either a relative or absolute name. Assuming
TemplateNameFormat.DEFAULT_2_3_0
or TemplateNameFormat.DEFAULT_2_4_0
, the rules are as
follows. If it starts with "/"
or contains a scheme part separator ("://"
, also, with
TemplateNameFormat.DEFAULT_2_4_0
a ":"
with no "/"
anywhere before it) then
it's an absolute name, otherwise it's a relative path. Relative paths are interpreted relatively to
the baseName
. Absolute names are simply returned as is, ignoring the baseName
, except,
when the baseName
has scheme part while the targetName
doesn't have, then the schema
of the baseName
is prepended to the targetName
.MalformedTemplateNameException
public java.lang.String rootBasedToAbsoluteTemplateName(java.lang.String rootBasedName) throws MalformedTemplateNameException
Configuration.getTemplate(String)
), to an absolute name, which can be safely
passed to <#include path>
and such, as it won't be misinterpreted to be relative to the directory of the
template. For example, "foo/bar.ftl"
is converted to "/foo/bar.ftl"
, while "/foo/bar"
or
"foo://bar/baz"
remains as is, as they are already absolute names (see TemplateNameFormat
for
more about the format of names).
You only need this if the template name will be passed to <#include name>
, <#import name>
,
.get_optional_template(name)
or a similar construct in a template, otherwise using non-absolute root
based names is fine.
MalformedTemplateNameException
public java.lang.String getNamespaceForPrefix(java.lang.String prefix)
public java.lang.String getPrefixForNamespace(java.lang.String nsURI)
public java.lang.String getDefaultNS()
public java.lang.Object __getitem__(java.lang.String key) throws TemplateModelException
TemplateModelException
public void __setitem__(java.lang.String key, java.lang.Object o) throws TemplateException
TemplateException
public java.lang.Object getCustomState(java.lang.Object identityKey)
null
if it's missing; see
setCustomState(Object, Object)
for more.public java.lang.Object setCustomState(java.lang.Object identityKey, java.lang.Object value)
TemplateNumberFormatFactory
-es, TemplateDateFormatFactory
-es, and similar user-implementable,
pluggable objects, which want to maintain an Environment
-scoped state (such as a cache).identityKey
- The key that identifies the variable, by its object identity (not by Object.equals(Object)
).
This should be something like a private static final Object CUSTOM_STATE_KEY = new Object();
in the class that needs this state variable.value
- The value of the variable. Can be anything, even null
.null
if the variable didn't exist.