Class Engine
Settings
object instead of directly using
this class.
fmpp.Engine
vs Settings
:
The design of the Engine
API is driven by the internal
architecture of FMPP. It doesn't consider front-ends, doesn't know
configuration files or similar high-level concepts. Settings
wraps the Engine
object, and implements end-user (front-end) centric
concepts, as the settings and configuration files described in the FMPP
Manual. For a programmer, the API of Engine
is more straightforward
than the API of Settings
object. But Settings
is better
if you want FMPP behave similarly as described in the FMPP Manual from the
viewpoint of end-user, or if you need some of its extra features, like
configuration files.
Engine parameters:
Engine
parameters are very similar to "settings" discussed in the
FMPP Manual. You will usually find trivial one-to-one correspondence between
settings and Engine
parameters, but not always, as Settings
is
a higher level API that adds some new concepts.
The value of Engine
parameters can't be set while a processing session is
executing; attempting that will cause IllegalStateException
.
Thus, for example, you can't change an Engine
parameter from an executing
template. Also, you should not change the objects stored as "data" (i.e. the
variables that are visible for all templates) while the processing session is
executing, even though it's not prevented technically.
Life-cycle: The same Engine
object can be used for multiple
processing sessions. However, the typical usage is that it's used
only for a single processing session. The state of the engine object possibly
changes during sessions because of the engine attributes (see
setAttribute(String, Object)
), and because long-lived objects as local
data builders and progress listeners can maintain state through multiple sessions.
These objects should behave so that the output of a session is not influenced
by earlier sessions.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final freemarker.template.Version
The default value of therecommendDefaults
setting, whennull
is passed for it to theEngine
constructor.static final String
A commonly used reserved parameter value:"host"
.static final String
A commonly used reserved parameter value:"source"
.static final String
A commonly used reserved parameter value:"source"
.static final int
Processing mode: Copy the file as-is (binary copy).static final int
Processing mode: Execute the file as templatestatic final int
Processing mode: Ignore the file.static final int
Processing mode: N/Astatic final int
Processing mode: Render XML with an FTL template.static final int
Used with the "skipUnchanged" engine parameter: skip all unchanged filesstatic final int
Used with the "skipUnchnaged" engine parameter: never skip filesstatic final int
Used with the "skipUnchanged" engine parameter: skip unchanged static filesstatic final freemarker.template.Version
static final freemarker.template.Version
static final String
Used as the value of the "xmlEngine" engine parameter: Let FreeMarker choose.static final String
Used as the value of the "xmlEngine" engine parameter: keep the current JVM level setting.static final String
Used as the value of the "xmlEngine" engine parameter: Force the usage of Jaxen.static final String
Used as the value of the "xmlEngine" engine parameter: Force the usage of Xalan. -
Constructor Summary
ConstructorsConstructorDescriptionEngine()
Deprecated.Engine
(freemarker.ext.beans.BeansWrapper objectWrapper) Deprecated.UseEngine(Version, Version, BeansWrapper)
instead.Engine
(freemarker.ext.beans.BeansWrapper objectWrapper, freemarker.template.Version freemarkerIncompatibleImprovements) Deprecated.UseEngine(Version, Version, BeansWrapper)
instead.Engine
(freemarker.template.Version recommendedDefaults) Engine
(freemarker.template.Version recommendedDefaults, freemarker.template.Version freemarkerIncompatibleImprovements, freemarker.ext.beans.BeansWrapper objectWrapper) Creates a new FMPP engine instance. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Convenience method for adding aBoolean
object.void
Convenience method for adding aByte
object.void
Convenience method for adding aCharacter
object.void
Convenience method for adding aDouble
object.void
Convenience method for adding aFloat
object.void
Convenience method for adding aInteger
object.void
Convenience method for adding aLong
object.void
Convenience method for adding aShort
object.void
Adds a variable that will be visible for all templates when the processing session executes.void
Adds all entries withaddData(String, Object)
.void
addFooterChooser
(int layer, String pattern, String footer) Adds a new entry to the end of path-pattern -> footer mapping list of the given layer.void
addFooterChooser
(String pattern, String footer) Deprecated.UseaddFooterChooser(int, String, String)
instead.void
addFreemarkerLink
(String name, File fileOrDir) Adds a FreeMarker link.void
addHeaderChooser
(int layer, String pattern, String footer) Adds a new entry to the end of path-pattern -> header mapping list of the given layer.void
addHeaderChooser
(String pattern, String header) Deprecated.UseaddHeaderChooser(int, String, String)
instead.void
addLocalDataBuilder
(int layer, String pathPattern, LocalDataBuilder builder) Adds a local data builder.void
addModeChooser
(String pattern, int pmode) Adds a new entry to the end of path-pattern -> processing-mode mapping list.void
addOutputFormatChooser
(String pathPattern, freemarker.core.OutputFormat outputFormat) Adds a new entry to the end of path-pattern -> output-format mapping list.void
addProgressListener
(ProgressListener listener) Adds a progress listener to the list of progress listeners.void
addRemoveExtension
(String extension) Adds an extension to the list of extensions to remove.void
addRemovePostfix
(String postfix) Adds a postfix to the list of file name postfixes to remove.void
addReplaceExtension
(String oldExtension, String newExtension) Adds an old-exension -> new-extension pair to the list of extension replacements.void
addTurnChooser
(String pattern, int turn) Adds a new entry to the end of path-pattern -> turn-number mapping list.void
addXmlRenderingConfiguration
(XmlRenderingConfiguration xmlRendering) Adds as XML rendering configuration.void
checkXmlSupportAvailability
(String requiredForThis) Checks if XML support is available.void
Removes all attributes.void
Removes all data.void
Removes all footer choosers.void
Removes all FreeMarker links.void
Removes all header choosers.void
Removes all local data builders.void
Removes all processing mode choosers.void
Removes all output format choosers.void
Removes all progress listeners from the list of progress listeners that were added withaddProgressListener(fmpp.ProgressListener)
.void
void
void
void
Deprecated.UseclearData()
instead.void
Removes all turn choosers.void
Removes all XML rendering configurations.boolean
getAttribute
(String name) Reads an engine attribute.static String
Returns FMPP build info.boolean
Gets the value of a variable.Returns the directory used as data root directory.static freemarker.template.Version
getDefaultFreemarkerIncompatibleImprovements
(freemarker.template.Version fmppRecommendedDefaults) The default value of thefreemarkerIncompatibleImprovements
setting, whennull
is passed for it to theEngine
constructor.boolean
boolean
freemarker.template.Version
Returns the FreeMarker "incompatible improvements" setting.getFreemarkerLink
(String name) Returns the list of files associated with a FreeMarker link name.static freemarker.template.Version
Returns the FreeMarker version used.static String
Deprecated.UsegetFreeMarkerVersion()
instead.boolean
boolean
boolean
int
Returns the actual (non-null) locale in use.boolean
Getter pair ofsetMapCommonExtensionsToOutputFormats(boolean)
.boolean
Retruns the output encoding used; It can be"source"
(since that can't be resolved to a concrete charset), but nevernull
or"host"
.freemarker.core.OutputFormat
Getter pair ofsetOutputFormat(OutputFormat)
.freemarker.core.OutputFormat
getOutputFormat
(String name) Resolves an FreeMarker "output format" name to anOutputFormat
object.Returns the output root directory.static String
getProgressListenerEventName
(int event) Converts anProgressListener.EVENT_...
constant to English text.freemarker.template.Version
See the similarly named constructor parameter ofEngine(Version, Version, BeansWrapper)
.boolean
Getter pair ofsetRemoveFreemarkerExtensions(boolean)
.int
Returns the source encoding used for the template files.Returns the source root directory.boolean
int
Returns theTemplateEnvironment
.Retruns the output encoding used; It can be"output"
(since that can't be resolved to a concrete charset), but nevernull
.boolean
static freemarker.template.Version
Returns the FMPP version number.static String
Deprecated.UsegetVersion()
instead.Gets the XML entiry resolver used for reading XML documents.boolean
Tells ifgetTemplateEnvironment()
will throw exception or not.boolean
Quickly tells if XML support is available.void
Processes a list of files.void
Hack to processes a single file.removeAttribute
(String name) Removes an attribute.removeData
(String name) Removes a variable that would be visible for all templates when the processing session executes.void
setAlwaysCreateDirectories
(boolean enable) Sets whether for source directories a corresponding output directory will be created even if no file output went into it.setAttribute
(String name, Object value) Adds/replaces an engine attribute.void
setBooleanFormat
(String format) Sets the boolean format used to convert boolean to strings, as defined byConfigurable.setBooleanFormat(String)
.void
setCaseSensitive
(boolean cs) Sets if the engine differentiates upper- and lower-case letters when it compares paths or matches path patterns with paths.void
setDataRoot
(File dataRoot) Sets the root directory of data files.void
setDateFormat
(String format) Sets the format used to convert date values (year + month + day) to strings.void
setDateTimeFormat
(String format) Sets the format used to convert date-time values (year + month + day + hour + minute + second + millisecond) to strings.void
setDontTraverseDirectories
(boolean dontTraverseDirs) void
setExpertMode
(boolean expertMode) Allows some features that are considered dangerous.void
setIgnoreCvsFiles
(boolean ignoreCvsFiles) Sets if the CVS files inside the source root directory should be ignored or not.void
setIgnoreSvnFiles
(boolean ignoreSvnFiles) Sets if the SVN files inside the source root directory should be ignored or not.void
setIgnoreTemporaryFiles
(boolean ignoreTemporaryFiles) Set if well-known temporary files inside the source root directory should be ignored or not.void
setInterpolationSyntax
(int interpolationSyntax) Sets theinterpolationSyntax
setting of FreeMarker.void
Sets the locale (country, language).void
Sets the locale (country, language).void
setMapCommonExtensionsToOutputFormats
(boolean mapCommonExtensionsToOutputFormats) Sets if some very commonly used file extensions (see below) should be automatically associated with a FreeMarkerOutputFormat
, for the purpose of auto-escaping.void
setNumberFormat
(String format) Sets the number format used to convert numbers to strings, as defined byConfigurable.setNumberFormat(String)
.void
setOldTemplateSyntax
(boolean oldSyntax) Sets if the#
is required in FTL tags or not.void
setOutputEncoding
(String outputEncoding) Sets the encoding used for textural output (template generated files).void
setOutputFormat
(freemarker.core.OutputFormat outputFormat) Sets theOutputFormat
used in templates when there's no more specific one chosen by path pattern.void
setOutputRoot
(File outputRoot) Sets the root directory of output files.void
setRemoveFreemarkerExtensions
(boolean removeFreemarkerExtensions) Sets if the standard FreeMarker file extensions (ftl
,ftlh
,ftlx
) should be removed from the output file name.void
setSkipUnchanged
(int skipWhat) Sets what source file can be skipped if it was not modified after the last modification time of the output file.void
setSourceEncoding
(String encoding) Sets the encoding (charset) of textual source files.void
setSourceRoot
(File srcRoot) Sets the root directory of source files.void
Same assetSQLDateAndTimeTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone.void
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values.void
setStopOnError
(boolean stopOnError) void
setTagSyntax
(int tagSyntax) Sets thetagSyntax
setting of FreeMarker.void
setTemplateDataModelBuilder
(TemplateDataModelBuilder tdmBuilder) Deprecated.void
setTemplateDataModelBuilder
(String className) Deprecated.void
setTimeFormat
(String format) Sets the format used to convert time values (hour + minute + second + millisecond) to strings.void
setTimeZone
(String zone) Same assetTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone.void
setTimeZone
(TimeZone zone) Sets the time zone used to display date/time/date-time values.void
setUrlEscapingCharset
(String urlEscapingCharset) Sets the charset used for URL escaping.void
setValidateXml
(boolean validateXml) Sets if XML documents should be validated when they are loaded.void
setXmlEntityResolver
(Object xmlEntityResolver) Sets the XML entiry resolver used for reading XML documents.void
setXpathEngine
(String xpathEngine) Sets if which XPath engine should be used.static void
validateRecommendedDefaults
(freemarker.template.Version recommendedDefaults) Check if therecommendedDefaults
is in the supported range.freemarker.template.TemplateModel
Wraps any object asTemplateModel
.
-
Field Details
-
PMODE_NONE
public static final int PMODE_NONEProcessing mode: N/A- See Also:
-
PMODE_EXECUTE
public static final int PMODE_EXECUTEProcessing mode: Execute the file as template- See Also:
-
PMODE_COPY
public static final int PMODE_COPYProcessing mode: Copy the file as-is (binary copy).- See Also:
-
PMODE_IGNORE
public static final int PMODE_IGNOREProcessing mode: Ignore the file.- See Also:
-
PMODE_RENDER_XML
public static final int PMODE_RENDER_XMLProcessing mode: Render XML with an FTL template.- See Also:
-
SKIP_NONE
public static final int SKIP_NONEUsed with the "skipUnchnaged" engine parameter: never skip files- See Also:
-
SKIP_STATIC
public static final int SKIP_STATICUsed with the "skipUnchanged" engine parameter: skip unchanged static files- See Also:
-
SKIP_ALL
public static final int SKIP_ALLUsed with the "skipUnchanged" engine parameter: skip all unchanged files- See Also:
-
PARAMETER_VALUE_SOURCE
A commonly used reserved parameter value:"source"
.- See Also:
-
PARAMETER_VALUE_OUTPUT
A commonly used reserved parameter value:"source"
.- See Also:
-
PARAMETER_VALUE_HOST
A commonly used reserved parameter value:"host"
.- See Also:
-
XPATH_ENGINE_DONT_SET
Used as the value of the "xmlEngine" engine parameter: keep the current JVM level setting.- See Also:
-
XPATH_ENGINE_DEFAULT
Used as the value of the "xmlEngine" engine parameter: Let FreeMarker choose.- See Also:
-
XPATH_ENGINE_XALAN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Xalan.- See Also:
-
XPATH_ENGINE_JAXEN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Jaxen.- See Also:
-
VERSION_0_9_15
public static final freemarker.template.Version VERSION_0_9_15 -
VERSION_0_9_16
public static final freemarker.template.Version VERSION_0_9_16 -
DEFAULT_RECOMMENDED_DEFAULTS
public static final freemarker.template.Version DEFAULT_RECOMMENDED_DEFAULTSThe default value of therecommendDefaults
setting, whennull
is passed for it to theEngine
constructor. This was exposed as sometimes you need this information earlier than calling theEngine
constructor.- Since:
- 0.9.16
-
-
Constructor Details
-
Engine
public Engine()Deprecated.UseEngine(Version)
instead.Same asEngine((Version) null)
. -
Engine
public Engine(freemarker.template.Version recommendedDefaults) -
Engine
public Engine(freemarker.ext.beans.BeansWrapper objectWrapper) Deprecated.UseEngine(Version, Version, BeansWrapper)
instead.Same asEngine(null, objectWrapper, null)
. -
Engine
public Engine(freemarker.ext.beans.BeansWrapper objectWrapper, freemarker.template.Version freemarkerIncompatibleImprovements) Deprecated.UseEngine(Version, Version, BeansWrapper)
instead. -
Engine
public Engine(freemarker.template.Version recommendedDefaults, freemarker.template.Version freemarkerIncompatibleImprovements, freemarker.ext.beans.BeansWrapper objectWrapper) Creates a new FMPP engine instance. Use the setter methods (assetProgressListener
) to configure the new instance.- Parameters:
recommendedDefaults
- Instructs the engine to use the setting value defaults recommended as of the specified FMPP version. When you start a new project, set this to the current FMPP version. In older projects changing this setting can break things (check what changes below). Ifnull
, then it defaults to the lowest allowed value, 0.9.15. (That's the lowest allowed because this setting was added in 0.9.16.)The defaults change as follows:
- 0.9.15: This is the baseline (and the default)
- 0.9.16: The following defaults change (compared to 0.9.15):
freemarkerIncompatibleImprovements
to 2.3.28, thus, among many things, templates withftlh
andftlx
file extensions will useHTML
andXML
auto-escaping respectively.mapCommonExtensionsToOutputFormats
totrue
, thus, templates with common file extensions likehtml
,xml
etc. will have auto-escaping.removeFreemarkerExtensions
totrue
, thus, theftl
,ftlh
, andftlx
file extensions are automatically removed from the output file name.- The list of file extensions that are treated as binary files is extended (see them under "Settings" / "Processing mode choosing" in the FMPP Manual)
objectWrapper
to aDefaultObjectWrapper
, iffreemarkerIncompatibleImprovements
is at least 2.3.21} There are more details, but see that at theobjectWrapper
parameter.
freemarkerIncompatibleImprovements
- Sets the "incompatible improvements" version of FreeMarker. You should set this to the current FreeMarker version in new projects. SeeConfiguration(Version)
for details. If this isnull
and therecommendedDefaults
argument is 0.9.16, then "incompatible improvements" defaults to 2.3.28. If this isnull
andrecommendedDefaults
is 0.9.15 (the lowest possible value) then the default is chosen by FreeMarker (to 2.3.0 for maximum backward compatibility, at least currently).objectWrapper
- The FreeMarkerObjectWrapper
that this instance will use. Just usenull
if you don't know what's this. When this parameter isnull
, FMPP chooses the default, considering FreeMarker best practices and backward compatibility concerns. So it's somewhat complex, and depends on both therecommendedDefaults
and thefmIncompImprovements
arguments. IfrecommendedDefaults
is at least 0.9.16, andfmIncompImprovements
is eithernull
or at least 2.3.22, then FMPP creates aDefaultObjectWrapper
with itsincompatibleImprovements
setting set to FreeMarkerincompatibleImprovements
, itsforceLegacyNonListCollections
setting set tofalse
, itsiterableSupport
setting totrue
, and itstreatDefaultMethodsAsBeanMembers
setting set totrue
. Otherwise, FMPP creates aBeansWrapper
(not aDefaultObjectWrapper
) with itssimpleMapWrapper
setting set totrue
, and also, if the FreeMarkerincompatibleImprovements
will be at least2.3.21
, it's created usingBeansWrapperBuilder
instead ofnew BeansWrapper()
, which means that that the resultingBeansWrapper
will be a shared singleton with read-only settings.- Since:
- 0.9.16
-
-
Method Details
-
validateRecommendedDefaults
public static void validateRecommendedDefaults(freemarker.template.Version recommendedDefaults) Check if therecommendedDefaults
is in the supported range.- Parameters:
recommendedDefaults
- The version to validate. Ifnull
, the method returns without doing anything.- Throws:
IllegalArgumentException
- If the specified version is out of the valid range- Since:
- 0.9.16
-
getDefaultFreemarkerIncompatibleImprovements
public static freemarker.template.Version getDefaultFreemarkerIncompatibleImprovements(freemarker.template.Version fmppRecommendedDefaults) The default value of thefreemarkerIncompatibleImprovements
setting, whennull
is passed for it to theEngine
constructor. This was exposed as sometimes you need this information earlier than calling theEngine
constructor.- Since:
- 0.9.16
-
process
Processes a list of files.The source root and output root directory must be set (non-null) prior to calling this method.
- Parameters:
sources
- The list of files to process. All file must be inside the source root. The files will be processed in the order as they appear in the list, except that if you use multiple turns, they are re-sorted based on the associated turns (the original order of files is kept inside turns).- Throws:
ProcessingException
- ifEngine.process
has thrown any exception. The message of this exception holds nothing interesting (just a static text). Call itsgetCause()
method to get the exception that caused the termination. Note that all (so even non-checked exceptions) thrown be the engine are catched and wrapped by this exeption.- See Also:
-
process
Hack to processes a single file.If the source root and/or output root directory is not set, they will be set for the time of this method call to the parent directories of the source and output files respectively.
- Parameters:
src
- the source file (not directory). Can't be null.out
- the output file (not directory). Can't be null.- Throws:
ProcessingException
- ifEngine.process
has thrown any exception. The message of this exception holds nothing interesting (just a static text). Call itsgetCause()
method to get the exception that caused the termination. Note that all (so even non-checked exceptions) thrown be the engine are catched and wrapped by this exception.- See Also:
-
getRecommendedDefaults
public freemarker.template.Version getRecommendedDefaults()See the similarly named constructor parameter ofEngine(Version, Version, BeansWrapper)
. -
getStopOnError
public boolean getStopOnError() -
setStopOnError
public void setStopOnError(boolean stopOnError) -
getOutputRoot
Returns the output root directory. This can be null. However, it is never null while a processing session is running, since the output root must be specified for successfully start a processing session.The returned
File
is always a canonicalFile
. -
setOutputRoot
Sets the root directory of output files. If it is null, the output directory will be used if the output is a directory, otherwise the parent directory of the output file. Initially this engine parameter is null.- Throws:
IOException
-
getSourceRoot
Returns the source root directory. This can be null. However, it is never null while a processing session is running, since the source root must be specified for successfully start a processing session.The returned
File
is always a canonicalFile
. -
setSourceRoot
Sets the root directory of source files. If it is null, the source directory will be used if the source is a directory, otherwise the parent directory of the source file.- Throws:
IOException
-
getDataRoot
Returns the directory used as data root directory. This will be the source root, if the data directory was not set (null). Note that the data-root can be null, when the source root is also null. However, it is never null while a processing session is runing, since the source root must be specified for successfully start a processing session.The returned
File
is always a canonicalFile
. -
setDataRoot
Sets the root directory of data files. If it is"source"
ornull
, then the source directory will be used.- Throws:
IOException
-
addFreemarkerLink
Adds a FreeMarker link. FreeMarker links are fake files/directories visible in the source root directory. They are visible for the predefined FreeMarker directives only (thus, not forpp
variables). A FreeMarker link acts as an alias or hard-link to another file or directory. This is a hack that allows you to<#include ...>
or<#import ...>
files that are outside the source root directory.The link is visible as a file or directory in the source root directory with name
@
name
. For example, if the link name is"inc"
, then it can be used as<#include '/@inc/blah.ftl'>
(assuming the link points to a directory that contains fileblah.ftl
).In the generic case, a FreeMarker link is associated with a list of files/directories, not just with a single file/directory. For example, if
inc
is associated with/home/joe/inc1
and/home/joe/inc2
(in this order), then<#include '/@inc/blah.ftl'>
will try to read/home/joe/inc1/blah.ftl
, and if that file is missing, then/home/joe/inc2/blah.ftl
. You can associate the name with multiple files/directories by calling this method with the same name for multiple times. The earlier you have added a file/directory, the higher its priority is.- Parameters:
name
- the name of fake entry in the source root directory, minus the@
prefix. To prevent confusion, the name can't start with @.fileOrDir
- the file or directory the link will point to. It can be a outside the source root directory.- Throws:
IOException
-
getFreemarkerLink
Returns the list of files associated with a FreeMarker link name.- Parameters:
name
- the name of the link (do not use the@
prefix)- Returns:
- the list of canonical
File
-s associated with this link, ornull
, if no FreeMarker link with the given name exist.
-
clearFreemarkerLinks
public void clearFreemarkerLinks()Removes all FreeMarker links.- See Also:
-
addProgressListener
Adds a progress listener to the list of progress listeners. All progress listeners of the list will be invoked on the events of the engine.If you want a local data loader or engine attribute to listen engine events, do not add it with this method. It will be automatically notified about events, they need not be added here.
Note that if you try to add the same object for multiple times, the object will added only in the first occasion.
-
clearProgressListeners
public void clearProgressListeners()Removes all progress listeners from the list of progress listeners that were added withaddProgressListener(fmpp.ProgressListener)
. It does not affect other listening objects, as local data loaders or engine attributes. -
setTemplateDataModelBuilder
Deprecated.Sets the class that will be instantiated to create the template specfic variables.- See Also:
-
setTemplateDataModelBuilder
Deprecated.- Throws:
DataModelBuildingException
- See Also:
-
getTemplateDataModelBuilder
- See Also:
-
setSourceEncoding
Sets the encoding (charset) of textual source files. Note that according to FreeMarker rules, this can be overridden in a template with<#ftl encoding="...">
.Initially the encoding is ISO-8859-1.
- Parameters:
encoding
- The encoding, or"host"
if the default encoding (file.encoding
system property) of the host machine should be used.null
is the same as"host"
.
-
getSourceEncoding
Returns the source encoding used for the template files. This is notnull
or"host"
; this is always a concrete encoding, such as"UTF-8"
. -
setLocale
Sets the locale (country, language).Initially the locale is
en_US
.- Parameters:
locale
- The locale, or null if the default locale of the host machine should be used.
-
setLocale
Sets the locale (country, language).Initially the locale is
en_US
.- Parameters:
locale
- The locale, or "host" if the default locale of the host machine should be used. Null is the same as "host".
-
getLocale
Returns the actual (non-null) locale in use. -
setOldTemplateSyntax
public void setOldTemplateSyntax(boolean oldSyntax) Sets if the#
is required in FTL tags or not. In the old template syntax#
was not required. The default and recommended value for this engine parameter isfalse
. -
getOldTemplateSyntax
public boolean getOldTemplateSyntax()- See Also:
-
setTagSyntax
public void setTagSyntax(int tagSyntax) Sets thetagSyntax
setting of FreeMarker. The recommended value for new projects isConfiguration.AUTO_DETECT_TAG_SYNTAX
, the defalt with FreeMarker 2.3.x isConfiguration.ANGLE_BRACKET_TAG_SYNTAX
. -
getTagSyntax
public int getTagSyntax()- See Also:
-
setInterpolationSyntax
public void setInterpolationSyntax(int interpolationSyntax) Sets theinterpolationSyntax
setting of FreeMarker. Possible values:Configuration.LEGACY_INTERPOLATION_SYNTAX
(default),Configuration.DOLLAR_INTERPOLATION_SYNTAX
,Configuration.SQUARE_BRACKET_INTERPOLATION_SYNTAX
.- Since:
- 0.9.16
-
getInterpolationSyntax
public int getInterpolationSyntax()- Since:
- 0.9.16
- See Also:
-
setOutputEncoding
Sets the encoding used for textural output (template generated files). By default it is"source"
.- Parameters:
outputEncoding
- The name of encoding. If it is"source"
, then the encoding of the source (template file) will be used for the output.null
is the same as"source"
. If it is"host"
then the default encoding of the host machine will be used.
-
getOutputEncoding
Retruns the output encoding used; It can be"source"
(since that can't be resolved to a concrete charset), but nevernull
or"host"
. -
setUrlEscapingCharset
Sets the charset used for URL escaping. By default it is"output"
.- Parameters:
urlEscapingCharset
- The name of charset (encoding) that is used for URL escaping. If it is"output"
, then the encoding of the output will be used.null
is the same as"output"
. If it is"host"
then the default encoding of the host machine will be used.
-
getUrlEscapingCharset
Retruns the output encoding used; It can be"output"
(since that can't be resolved to a concrete charset), but nevernull
. -
setNumberFormat
Sets the number format used to convert numbers to strings, as defined byConfigurable.setNumberFormat(String)
. At least on FreeMarker 2.3.21, this is a pattern asDecimalFormat
defines it, or the reserved values"number"
or"currency"
. -
setBooleanFormat
Sets the boolean format used to convert boolean to strings, as defined byConfigurable.setBooleanFormat(String)
. Note that it can't be"true,false"
; for that you have to print the boolean value with${foo?c}
. -
getNumberFormat
- See Also:
-
setDateFormat
Sets the format used to convert date values (year + month + day) to strings. SeeConfigurable.setDateFormat(String)
in the FreeMarker API for more information.The default is the format suggested by the underlying Java platform implementation for the current locale.
-
getDateFormat
- See Also:
-
setTimeFormat
Sets the format used to convert time values (hour + minute + second + millisecond) to strings. SeeConfigurable.setTimeFormat(String)
in the FreeMarker API for more information.The default is the format suggested by the underlying Java platform implementation for the current locale.
-
getTimeFormat
- See Also:
-
setDateTimeFormat
Sets the format used to convert date-time values (year + month + day + hour + minute + second + millisecond) to strings. SeeConfigurable.setDateTimeFormat(String)
in the FreeMarker API for more information.The default is the format suggested by the underlying Java platform implementation for the current locale.
-
getDateTimeFormat
- See Also:
-
setTimeZone
Sets the time zone used to display date/time/date-time values. See FreeMarker'sConfiguration.setTimeZone(TimeZone)
for more information. -
setTimeZone
Same assetTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone. If the value comes from a string source anyway, it's recommended to use this instead of the other overload. -
setSQLDateAndTimeTimeZone
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values. See FreeMarker'sConfigurable.setSQLDateAndTimeTimeZone(TimeZone)
for more information. -
setSQLDateAndTimeTimeZone
Same assetSQLDateAndTimeTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone. If the value comes from a string source anyway, it's recommended to use this instead of the other overload. -
getTimeZone
- See Also:
-
setMapCommonExtensionsToOutputFormats
public void setMapCommonExtensionsToOutputFormats(boolean mapCommonExtensionsToOutputFormats) Sets if some very commonly used file extensions (see below) should be automatically associated with a FreeMarkerOutputFormat
, for the purpose of auto-escaping. This defaults totrue
ifgetRecommendedDefaults()
is at least 0.9.16, otherwise it defaults tofalse
.The list of common file extensions are (case-insensitive):
- HTML output format:
html
,htm
- XHTML output format:
xhtml
,xhtm
,xht
- XML output format:
xml
,xsd
,xsl
,xslt
,svg
,wsdl
,dita
,ditamap
- RTF output format:
rtf
Furthermore, the
.ftl
ending (case-insensitive) is ignored when this setting is applied, soexample.rtf.ftl
will be mapped to RTF output format.- Since:
- 0.9.16
- HTML output format:
-
getMapCommonExtensionsToOutputFormats
public boolean getMapCommonExtensionsToOutputFormats()Getter pair ofsetMapCommonExtensionsToOutputFormats(boolean)
.- Since:
- 0.9.16
-
setOutputFormat
public void setOutputFormat(freemarker.core.OutputFormat outputFormat) Sets theOutputFormat
used in templates when there's no more specific one chosen by path pattern.- Parameters:
outputFormat
- Notnull
; useUndefinedOutputFormat.INSTANCE
instead.- Since:
- 0.9.16
-
getOutputFormat
public freemarker.core.OutputFormat getOutputFormat()Getter pair ofsetOutputFormat(OutputFormat)
.- Returns:
- Not
null
. - Since:
- 0.9.16
-
addOutputFormatChooser
Adds a new entry to the end of path-pattern -> output-format mapping list. This corresponds to theoutputFormatsByPath
setting in theSettings
API.- Since:
- 0.9.16
-
getOutputFormat
public freemarker.core.OutputFormat getOutputFormat(String name) throws freemarker.core.UnregisteredOutputFormatException Resolves an FreeMarker "output format" name to anOutputFormat
object.- Throws:
freemarker.core.UnregisteredOutputFormatException
- Since:
- 0.9.16
- See Also:
-
addModeChooser
Adds a new entry to the end of path-pattern -> processing-mode mapping list.- Parameters:
pattern
- a path pattern as "*.txt" or "/docs/**/item_??.xml". You have to use slash (/) or backslash (\) or the platform specific separator to spearate directories.pmode
- the mode in which you want to process the files. Use thePMODE_...
constants.
-
addHeaderChooser
Deprecated.UseaddHeaderChooser(int, String, String)
instead.Adds a new entry to the end of path-pattern -> header mapping list of layer 0. -
addHeaderChooser
Adds a new entry to the end of path-pattern -> header mapping list of the given layer. Layers are indexed from 0. The lower the layer index is, the earlier the header occurs in the text. -
addTurnChooser
Adds a new entry to the end of path-pattern -> turn-number mapping list. -
clearOutputFormatChoosers
public void clearOutputFormatChoosers()Removes all output format choosers. This corresponds to theoutputFormatsByPath
setting in theSettings
API.- Since:
- 0.9.16
-
clearModeChoosers
public void clearModeChoosers()Removes all processing mode choosers. This is the initial state after the instantiation ofEngine
(i.e. no processing mode choosers). -
clearHeaderChoosers
public void clearHeaderChoosers()Removes all header choosers. -
clearTurnChoosers
public void clearTurnChoosers()Removes all turn choosers. -
setCaseSensitive
public void setCaseSensitive(boolean cs) Sets if the engine differentiates upper- and lower-case letters when it compares paths or matches path patterns with paths. False by default (ignores case). -
getCaseSensitive
public boolean getCaseSensitive()- See Also:
-
setExpertMode
public void setExpertMode(boolean expertMode) Allows some features that are considered dangerous. These are currently:- The source and the output file is the same
-
getExpertMode
public boolean getExpertMode()- See Also:
-
addRemovePostfix
Adds a postfix to the list of file name postfixes to remove. If the source file name before the first dot ends with a string in the list, then it will be removed from the output file name. For example, if "_t" is in the list, then the output file for "example_t.html" will be "example.html". If the file name does not contains dot, then it still works: "example_t" will become to "example".- Parameters:
postfix
- the postfix to remove. Can't be null or empty string, and can't contain dot.
-
addRemoveExtension
Adds an extension to the list of extensions to remove. If the source file name ends with an extension in the list, then it will be removed from the output file name. For example, if "t" is in the list, then the output file for "example.html.t" will be "example.html". The extension to remove can contain dots (as tar.gz).- Parameters:
extension
- the extension to remove without the dot. Can't be null or empty string, and can't start with dot.
-
addReplaceExtension
Adds an old-exension -> new-extension pair to the list of extension replacements. If a source file name ends with the old extension, then it will be replaced with the new extension in the output file name.- Parameters:
oldExtension
- the old extension without the preceding dot.newExtension
- the new extension without the preceding dot.
-
clearRemovePostfixes
public void clearRemovePostfixes() -
clearRemoveExtensions
public void clearRemoveExtensions() -
clearReplaceExtensions
public void clearReplaceExtensions() -
setRemoveFreemarkerExtensions
public void setRemoveFreemarkerExtensions(boolean removeFreemarkerExtensions) Sets if the standard FreeMarker file extensions (ftl
,ftlh
,ftlx
) should be removed from the output file name. Defaults totrue
ifgetRecommendedDefaults()
is at least 0.9.16.- Since:
- 0.9.16
-
getRemoveFreemarkerExtensions
public boolean getRemoveFreemarkerExtensions()Getter pair ofsetRemoveFreemarkerExtensions(boolean)
.- Since:
- 0.9.16
-
setDontTraverseDirectories
public void setDontTraverseDirectories(boolean dontTraverseDirs) Sets theEngine
should automatically process the files and directories inside a directory whose processing was asked through the publicEngine
API. Defaults totrue
. It is set tofalse
by front-ends that explicitly specify the list of source files and source directories, rather than expecting theEngine
to discover them. -
getDontTraverseDirectories
public boolean getDontTraverseDirectories() -
setSkipUnchanged
public void setSkipUnchanged(int skipWhat) Sets what source file can be skipped if it was not modified after the last modification time of the output file. Also, if the output is not existing, the source file will be processed. Note that this feature will not work for templates that rename or drop the original output file during the template execution.The initial value of this engine parameter is
SKIP_NONE
.- Parameters:
skipWhat
- aSKIP_...
contant.
-
getSkipUnchanged
public int getSkipUnchanged() -
setAlwaysCreateDirectories
public void setAlwaysCreateDirectories(boolean enable) Sets whether for source directories a corresponding output directory will be created even if no file output went into it. Defaults tofalse
.Notes:
- Even if this is set to
true
, if a directory contains anignoredir.fmpp
file, it will not create output directory. - If the directory contains a file called
createdir.fmpp
, the directory will be created even if this setting isfalse
.
- Even if this is set to
-
getAlwaysCreateDirectories
public boolean getAlwaysCreateDirectories() -
setIgnoreCvsFiles
public void setIgnoreCvsFiles(boolean ignoreCvsFiles) Sets if the CVS files inside the source root directory should be ignored or not. This engine parameter is initially true.The CVS files are:
**
/.cvsignore
,**
/CVS/**
and**
/.#*
-
getIgnoreCvsFiles
public boolean getIgnoreCvsFiles() -
setIgnoreSvnFiles
public void setIgnoreSvnFiles(boolean ignoreSvnFiles) Sets if the SVN files inside the source root directory should be ignored or not. This engine parameter is initially true.The SVN files are:
**
/SVN/**
-
getIgnoreSvnFiles
public boolean getIgnoreSvnFiles() -
setIgnoreTemporaryFiles
public void setIgnoreTemporaryFiles(boolean ignoreTemporaryFiles) Set if well-known temporary files inside the source root directory should be ignored or not. For the list of well-known temporary file patterns, read the FMPP Manual. -
getIgnoreTemporaryFiles
public boolean getIgnoreTemporaryFiles() -
setXpathEngine
Sets if which XPath engine should be used.- Parameters:
xpathEngine
- one of theXPATH_ENGINE_...
constants, or a class name.
-
getXpathEngine
-
setXmlEntityResolver
Sets the XML entiry resolver used for reading XML documents. The default value isnull
.- Parameters:
xmlEntityResolver
- it must implementorg.xml.sax.EntityResolver
(it was declared asObject
to prevent linkage errors when XML related features are not used on pre-1.4 Java), or it must benull
.- Throws:
InstallationException
-
getXmlEntiryResolver
Gets the XML entiry resolver used for reading XML documents.- Returns:
null
of no resolver is used, or anorg.xml.sax.EntityResolver
(it was declared asObject
to prevent linkage errors when XML related features are not used on pre-1.4 Java).
-
setValidateXml
public void setValidateXml(boolean validateXml) Sets if XML documents should be validated when they are loaded. Defaults totrue
. -
getValidateXml
public boolean getValidateXml() -
addXmlRenderingConfiguration
Adds as XML rendering configuration. -
clearXmlRenderingConfigurations
public void clearXmlRenderingConfigurations()Removes all XML rendering configurations. -
addData
Adds a variable that will be visible for all templates when the processing session executes. -
addData
Convenience method for adding aByte
object.- See Also:
-
addData
Convenience method for adding aShort
object.- See Also:
-
addData
Convenience method for adding aInteger
object.- See Also:
-
addData
Convenience method for adding aLong
object.- See Also:
-
addData
Convenience method for adding aFloat
object.- See Also:
-
addData
Convenience method for adding aDouble
object.- See Also:
-
addData
Convenience method for adding aCharacter
object.- See Also:
-
addData
Convenience method for adding aBoolean
object.- See Also:
-
addData
Adds all entries withaddData(String, Object)
. The name of the variable will be the key of the map entry, and its value will be the value of the map entry. -
clearData
public void clearData()Removes all data.- See Also:
-
getData
Gets the value of a variable. This method accesses the variables that are visible for all templates. It corresponds to settingdata
.Warning! When the processing session is executing, you must not modify the returned object.
- Returns:
null
if no such variable exist. Values are returned exactly as they were added, that is, without FreeMarker's wrapping (but note that some variables initially use FreeMarkerTemplateModel
types, such as variables created by some of the data loaders).- See Also:
-
removeData
Removes a variable that would be visible for all templates when the processing session executes. I does nothing if there is no variable exists for the given name.- Returns:
- the removed value, or
null
if there was no value stored for the given name. - See Also:
-
addLocalDataBuilder
Adds a local data builder. The local data builder will be invoked directly before the execution of templates (if thepathPattern
matches the source file path).- Parameters:
layer
- the index of the layer, stating from 0. 0 is the layer with the highest priority.pathPattern
- the path pattern of source files where this local data builder will be used.builder
- the local data builder object.
-
clearLocalDataBuilders
public void clearLocalDataBuilders()Removes all local data builders.- See Also:
-
getProgressListenerEventName
Converts anProgressListener.EVENT_...
constant to English text. -
wrap
public freemarker.template.TemplateModel wrap(Object obj) throws freemarker.template.TemplateModelException Wraps any object asTemplateModel
.- Throws:
freemarker.template.TemplateModelException
-
getTemplateEnvironment
Returns theTemplateEnvironment
. The template environment is available with this method only when a template execution is in progress, or when aTemplateDataModelBuilder
(deprecated) is running.- Throws:
IllegalStateException
- if the template environment is not available.
-
isTemplateEnvironmentAvailable
public boolean isTemplateEnvironmentAvailable()Tells ifgetTemplateEnvironment()
will throw exception or not. -
setAttribute
Adds/replaces an engine attribute. Attributes are arbitrary key-value pairs that are associated with theEngine
object. FMPP reserves all keys starting withfmpp.
for its own use. Attributes are not understood by theEngine
, but by data loaders, local data builders, and tools that create them.Attributes can be changed (replaced, removed, ...etc.) while the processing session is executing.
- Parameters:
name
- the name of the attribute. To prevent name clashes, it should follow the naming convention of Java classes, e.g."com.example.someproject.something"
.value
- the value of the attribute. If it implementsProgressListener
, then it will receive notifications about the events of theEngine
. If attribute(s) with that value is (are) removed, then the value object doesn't receive more notifications.- Returns:
- The previous value of the attribute, or
null
if there was no attribute with the given name.
-
getAttribute
Reads an engine attribute.- Returns:
null
if no attribute exists with the given name.- See Also:
-
removeAttribute
Removes an attribute. It does nothing if the attribute does not exist.- Returns:
- The value of the removed attribute or
null
if there was no attribute with the given name. - See Also:
-
clearAttribues
public void clearAttribues()Removes all attributes.- See Also:
-
getVersionNumber
Deprecated.Returns the FMPP version number string. FMPP version number string follows themajor.minor.sub
ormajor.minor.sub.nightly
format, where each part (separated by dots) is an non-negative integer number. -
getVersion
public static freemarker.template.Version getVersion()Returns the FMPP version number.- Since:
- 0.9.16
-
getBuildInfo
Returns FMPP build info. This is usually the date of the build, but it can be anything. -
getFreeMarkerVersionNumber
Deprecated. -
getFreeMarkerVersion
public static freemarker.template.Version getFreeMarkerVersion()Returns the FreeMarker version used.- Since:
- 0.9.16
-
getFreemarkerIncomplatibleImprovements
public freemarker.template.Version getFreemarkerIncomplatibleImprovements()Returns the FreeMarker "incompatible improvements" setting. This can only be set in the constructor.- Since:
- 0.9.16
-
isXmlSupportAvailabile
public boolean isXmlSupportAvailabile()Quickly tells if XML support is available. -
checkXmlSupportAvailability
Checks if XML support is available. It can be quicker thanMiscUtil.checkXmlSupportAvailability(String)
, so rather use this.- Parameters:
requiredForThis
- a short sentence that describes for human reader if for what do we need the XML support (e.g."Usage of xml data loader."
or"Set XML entity resolver."
). This sentence is used in error message of theInstallationException
. Can benull
.- Throws:
InstallationException
- if the XML support is not available.
-
Engine(Version)
instead.