Class Engine
- java.lang.Object
-
- fmpp.Engine
-
public class Engine extends java.lang.Object
The bare-bone, low-level preprocessor engine. Since FMPP 0.9.0 you should rather use aSettings
object instead of directly using this class.fmpp.Engine
vsSettings
: The design of theEngine
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 theEngine
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 ofEngine
is more straightforward than the API ofSettings
object. ButSettings
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 andEngine
parameters, but not always, asSettings
is a higher level API that adds some new concepts. The value ofEngine
parameters can't be set while a processing session is executing; attempting that will causeIllegalStateException
. Thus, for example, you can't change anEngine
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 (seesetAttribute(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
Fields Modifier and Type Field Description static freemarker.template.Version
DEFAULT_RECOMMENDED_DEFAULTS
The default value of therecommendDefaults
setting, whennull
is passed for it to theEngine
constructor.static java.lang.String
PARAMETER_VALUE_HOST
A commonly used reserved parameter value:"host"
.static java.lang.String
PARAMETER_VALUE_OUTPUT
A commonly used reserved parameter value:"source"
.static java.lang.String
PARAMETER_VALUE_SOURCE
A commonly used reserved parameter value:"source"
.static int
PMODE_COPY
Processing mode: Copy the file as-is (binary copy).static int
PMODE_EXECUTE
Processing mode: Execute the file as templatestatic int
PMODE_IGNORE
Processing mode: Ignore the file.static int
PMODE_NONE
Processing mode: N/Astatic int
PMODE_RENDER_XML
Processing mode: Render XML with an FTL template.static int
SKIP_ALL
Used with the "skipUnchanged" engine parameter: skip all unchanged filesstatic int
SKIP_NONE
Used with the "skipUnchnaged" engine parameter: never skip filesstatic int
SKIP_STATIC
Used with the "skipUnchanged" engine parameter: skip unchanged static filesstatic freemarker.template.Version
VERSION_0_9_15
static freemarker.template.Version
VERSION_0_9_16
static java.lang.String
XPATH_ENGINE_DEFAULT
Used as the value of the "xmlEngine" engine parameter: Let FreeMarker choose.static java.lang.String
XPATH_ENGINE_DONT_SET
Used as the value of the "xmlEngine" engine parameter: keep the current JVM level setting.static java.lang.String
XPATH_ENGINE_JAXEN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Jaxen.static java.lang.String
XPATH_ENGINE_XALAN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Xalan.
-
Constructor Summary
Constructors Constructor Description Engine()
Deprecated.UseEngine(Version)
instead.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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addData(java.lang.String name, boolean value)
Convenience method for adding aBoolean
object.void
addData(java.lang.String name, byte value)
Convenience method for adding aByte
object.void
addData(java.lang.String name, char value)
Convenience method for adding aCharacter
object.void
addData(java.lang.String name, double value)
Convenience method for adding aDouble
object.void
addData(java.lang.String name, float value)
Convenience method for adding aFloat
object.void
addData(java.lang.String name, int value)
Convenience method for adding aInteger
object.void
addData(java.lang.String name, long value)
Convenience method for adding aLong
object.void
addData(java.lang.String name, short value)
Convenience method for adding aShort
object.void
addData(java.lang.String name, java.lang.Object value)
Adds a variable that will be visible for all templates when the processing session executes.void
addData(java.util.Map map)
Adds all entries withaddData(String, Object)
.void
addFooterChooser(int layer, java.lang.String pattern, java.lang.String footer)
Adds a new entry to the end of path-pattern -> footer mapping list of the given layer.void
addFooterChooser(java.lang.String pattern, java.lang.String footer)
Deprecated.UseaddFooterChooser(int, String, String)
instead.void
addFreemarkerLink(java.lang.String name, java.io.File fileOrDir)
Adds a FreeMarker link.void
addHeaderChooser(int layer, java.lang.String pattern, java.lang.String footer)
Adds a new entry to the end of path-pattern -> header mapping list of the given layer.void
addHeaderChooser(java.lang.String pattern, java.lang.String header)
Deprecated.UseaddHeaderChooser(int, String, String)
instead.void
addLocalDataBuilder(int layer, java.lang.String pathPattern, LocalDataBuilder builder)
Adds a local data builder.void
addModeChooser(java.lang.String pattern, int pmode)
Adds a new entry to the end of path-pattern -> processing-mode mapping list.void
addOutputFormatChooser(java.lang.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(java.lang.String extension)
Adds an extension to the list of extensions to remove.void
addRemovePostfix(java.lang.String postfix)
Adds a postfix to the list of file name postfixes to remove.void
addReplaceExtension(java.lang.String oldExtension, java.lang.String newExtension)
Adds an old-exension -> new-extension pair to the list of extension replacements.void
addTurnChooser(java.lang.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(java.lang.String requiredForThis)
Checks if XML support is available.void
clearAttribues()
Removes all attributes.void
clearData()
Removes all data.void
clearFooterChoosers()
Removes all footer choosers.void
clearFreemarkerLinks()
Removes all FreeMarker links.void
clearHeaderChoosers()
Removes all header choosers.void
clearLocalDataBuilders()
Removes all local data builders.void
clearModeChoosers()
Removes all processing mode choosers.void
clearOutputFormatChoosers()
Removes all output format choosers.void
clearProgressListeners()
Removes all progress listeners from the list of progress listeners that were added withaddProgressListener(fmpp.ProgressListener)
.void
clearRemoveExtensions()
void
clearRemovePostfixes()
void
clearReplaceExtensions()
void
clearSharedVariables()
Deprecated.UseclearData()
instead.void
clearTurnChoosers()
Removes all turn choosers.void
clearXmlRenderingConfigurations()
Removes all XML rendering configurations.boolean
getAlwaysCreateDirectories()
java.lang.Object
getAttribute(java.lang.String name)
Reads an engine attribute.static java.lang.String
getBuildInfo()
Returns FMPP build info.boolean
getCaseSensitive()
java.lang.Object
getData(java.lang.String name)
Gets the value of a variable.java.io.File
getDataRoot()
Returns the directory used as data root directory.java.lang.String
getDateFormat()
java.lang.String
getDateTimeFormat()
static freemarker.template.Version
getDefaultFreemarkerIncompatibleImprovements(freemarker.template.Version fmppRecommendedDefaults)
The default value of thefreemarkerIncompatibleImprovements
setting, whennull
is passed for it to theEngine
constructor.boolean
getDontTraverseDirectories()
boolean
getExpertMode()
freemarker.template.Version
getFreemarkerIncomplatibleImprovements()
Returns the FreeMarker "incompatible improvements" setting.java.util.List
getFreemarkerLink(java.lang.String name)
Returns the list of files associated with a FreeMarker link name.static freemarker.template.Version
getFreeMarkerVersion()
Returns the FreeMarker version used.static java.lang.String
getFreeMarkerVersionNumber()
Deprecated.UsegetFreeMarkerVersion()
instead.boolean
getIgnoreCvsFiles()
boolean
getIgnoreSvnFiles()
boolean
getIgnoreTemporaryFiles()
int
getInterpolationSyntax()
java.util.Locale
getLocale()
Returns the actual (non-null) locale in use.boolean
getMapCommonExtensionsToOutputFormats()
Getter pair ofsetMapCommonExtensionsToOutputFormats(boolean)
.java.lang.String
getNumberFormat()
boolean
getOldTemplateSyntax()
java.lang.String
getOutputEncoding()
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
getOutputFormat()
Getter pair ofsetOutputFormat(OutputFormat)
.freemarker.core.OutputFormat
getOutputFormat(java.lang.String name)
Resolves an FreeMarker "output format" name to anOutputFormat
object.java.io.File
getOutputRoot()
Returns the output root directory.static java.lang.String
getProgressListenerEventName(int event)
Converts anProgressListener.EVENT_...
constant to English text.freemarker.template.Version
getRecommendedDefaults()
See the similarly named constructor parameter ofEngine(Version, Version, BeansWrapper)
.boolean
getRemoveFreemarkerExtensions()
Getter pair ofsetRemoveFreemarkerExtensions(boolean)
.int
getSkipUnchanged()
java.lang.String
getSourceEncoding()
Returns the source encoding used for the template files.java.io.File
getSourceRoot()
Returns the source root directory.boolean
getStopOnError()
int
getTagSyntax()
TemplateDataModelBuilder
getTemplateDataModelBuilder()
TemplateEnvironment
getTemplateEnvironment()
Returns theTemplateEnvironment
.java.lang.String
getTimeFormat()
java.util.TimeZone
getTimeZone()
java.lang.String
getUrlEscapingCharset()
Retruns the output encoding used; It can be"output"
(since that can't be resolved to a concrete charset), but nevernull
.boolean
getValidateXml()
static freemarker.template.Version
getVersion()
Returns the FMPP version number.static java.lang.String
getVersionNumber()
Deprecated.UsegetVersion()
instead.java.lang.Object
getXmlEntiryResolver()
Gets the XML entiry resolver used for reading XML documents.java.lang.String
getXpathEngine()
boolean
isTemplateEnvironmentAvailable()
Tells ifgetTemplateEnvironment()
will throw exception or not.boolean
isXmlSupportAvailabile()
Quickly tells if XML support is available.void
process(java.io.File[] sources)
Processes a list of files.void
process(java.io.File src, java.io.File out)
Hack to processes a single file.java.lang.Object
removeAttribute(java.lang.String name)
Removes an attribute.java.lang.Object
removeData(java.lang.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.java.lang.Object
setAttribute(java.lang.String name, java.lang.Object value)
Adds/replaces an engine attribute.void
setBooleanFormat(java.lang.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(java.io.File dataRoot)
Sets the root directory of data files.void
setDateFormat(java.lang.String format)
Sets the format used to convert date values (year + month + day) to strings.void
setDateTimeFormat(java.lang.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
setLocale(java.lang.String locale)
Sets the locale (country, language).void
setLocale(java.util.Locale locale)
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(java.lang.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(java.lang.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(java.io.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(java.lang.String encoding)
Sets the encoding (charset) of textual source files.void
setSourceRoot(java.io.File srcRoot)
Sets the root directory of source files.void
setSQLDateAndTimeTimeZone(java.lang.String zone)
Same assetSQLDateAndTimeTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone.void
setSQLDateAndTimeTimeZone(java.util.TimeZone zone)
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(java.lang.String className)
Deprecated.void
setTimeFormat(java.lang.String format)
Sets the format used to convert time values (hour + minute + second + millisecond) to strings.void
setTimeZone(java.lang.String zone)
Same assetTimeZone(TimeZone)
, but lets FreeMarker parse the value to time zone.void
setTimeZone(java.util.TimeZone zone)
Sets the time zone used to display date/time/date-time values.void
setUrlEscapingCharset(java.lang.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(java.lang.Object xmlEntityResolver)
Sets the XML entiry resolver used for reading XML documents.void
setXpathEngine(java.lang.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
wrap(java.lang.Object obj)
Wraps any object asTemplateModel
.
-
-
-
Field Detail
-
PMODE_NONE
public static final int PMODE_NONE
Processing mode: N/A- See Also:
- Constant Field Values
-
PMODE_EXECUTE
public static final int PMODE_EXECUTE
Processing mode: Execute the file as template- See Also:
- Constant Field Values
-
PMODE_COPY
public static final int PMODE_COPY
Processing mode: Copy the file as-is (binary copy).- See Also:
- Constant Field Values
-
PMODE_IGNORE
public static final int PMODE_IGNORE
Processing mode: Ignore the file.- See Also:
- Constant Field Values
-
PMODE_RENDER_XML
public static final int PMODE_RENDER_XML
Processing mode: Render XML with an FTL template.- See Also:
- Constant Field Values
-
SKIP_NONE
public static final int SKIP_NONE
Used with the "skipUnchnaged" engine parameter: never skip files- See Also:
- Constant Field Values
-
SKIP_STATIC
public static final int SKIP_STATIC
Used with the "skipUnchanged" engine parameter: skip unchanged static files- See Also:
- Constant Field Values
-
SKIP_ALL
public static final int SKIP_ALL
Used with the "skipUnchanged" engine parameter: skip all unchanged files- See Also:
- Constant Field Values
-
PARAMETER_VALUE_SOURCE
public static final java.lang.String PARAMETER_VALUE_SOURCE
A commonly used reserved parameter value:"source"
.- See Also:
- Constant Field Values
-
PARAMETER_VALUE_OUTPUT
public static final java.lang.String PARAMETER_VALUE_OUTPUT
A commonly used reserved parameter value:"source"
.- See Also:
- Constant Field Values
-
PARAMETER_VALUE_HOST
public static final java.lang.String PARAMETER_VALUE_HOST
A commonly used reserved parameter value:"host"
.- See Also:
- Constant Field Values
-
XPATH_ENGINE_DONT_SET
public static final java.lang.String XPATH_ENGINE_DONT_SET
Used as the value of the "xmlEngine" engine parameter: keep the current JVM level setting.- See Also:
- Constant Field Values
-
XPATH_ENGINE_DEFAULT
public static final java.lang.String XPATH_ENGINE_DEFAULT
Used as the value of the "xmlEngine" engine parameter: Let FreeMarker choose.- See Also:
- Constant Field Values
-
XPATH_ENGINE_XALAN
public static final java.lang.String XPATH_ENGINE_XALAN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Xalan.- See Also:
- Constant Field Values
-
XPATH_ENGINE_JAXEN
public static final java.lang.String XPATH_ENGINE_JAXEN
Used as the value of the "xmlEngine" engine parameter: Force the usage of Jaxen.- See Also:
- Constant Field Values
-
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_DEFAULTS
The 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 Detail
-
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 Detail
-
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:
java.lang.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
public void process(java.io.File[] sources) throws ProcessingException
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(File, File)
-
process
public void process(java.io.File src, java.io.File out) throws ProcessingException
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:
process(File[])
-
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
public java.io.File 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
public void setOutputRoot(java.io.File outputRoot) throws java.io.IOException
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:
java.io.IOException
-
getSourceRoot
public java.io.File 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
public void setSourceRoot(java.io.File srcRoot) throws java.io.IOException
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:
java.io.IOException
-
getDataRoot
public java.io.File 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
public void setDataRoot(java.io.File dataRoot) throws java.io.IOException
Sets the root directory of data files. If it is"source"
ornull
, then the source directory will be used.- Throws:
java.io.IOException
-
addFreemarkerLink
public void addFreemarkerLink(java.lang.String name, java.io.File fileOrDir) throws java.io.IOException
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:
java.io.IOException
-
getFreemarkerLink
public java.util.List getFreemarkerLink(java.lang.String name)
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:
addFreemarkerLink(String, File)
-
addProgressListener
public void addProgressListener(ProgressListener listener)
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
public void setTemplateDataModelBuilder(TemplateDataModelBuilder tdmBuilder)
Deprecated.Sets the class that will be instantiated to create the template specfic variables.- See Also:
TemplateDataModelBuilder
-
setTemplateDataModelBuilder
public void setTemplateDataModelBuilder(java.lang.String className) throws DataModelBuildingException
Deprecated.
-
getTemplateDataModelBuilder
public TemplateDataModelBuilder getTemplateDataModelBuilder()
-
setSourceEncoding
public void setSourceEncoding(java.lang.String encoding)
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
public java.lang.String 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
public void setLocale(java.util.Locale locale)
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
public void setLocale(java.lang.String locale)
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
public java.util.Locale 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:
setOldTemplateSyntax(boolean)
-
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:
setTagSyntax(int)
-
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:
setInterpolationSyntax(int)
-
setOutputEncoding
public void setOutputEncoding(java.lang.String outputEncoding)
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
public java.lang.String 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
public void setUrlEscapingCharset(java.lang.String urlEscapingCharset)
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
public java.lang.String getUrlEscapingCharset()
Retruns the output encoding used; It can be"output"
(since that can't be resolved to a concrete charset), but nevernull
.
-
setNumberFormat
public void setNumberFormat(java.lang.String format)
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
public void setBooleanFormat(java.lang.String format)
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
public java.lang.String getNumberFormat()
- See Also:
setNumberFormat(java.lang.String)
-
setDateFormat
public void setDateFormat(java.lang.String format)
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
public java.lang.String getDateFormat()
- See Also:
setDateFormat(java.lang.String)
-
setTimeFormat
public void setTimeFormat(java.lang.String format)
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
public java.lang.String getTimeFormat()
- See Also:
setTimeFormat(java.lang.String)
-
setDateTimeFormat
public void setDateTimeFormat(java.lang.String format)
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
public java.lang.String getDateTimeFormat()
- See Also:
setDateTimeFormat(java.lang.String)
-
setTimeZone
public void setTimeZone(java.util.TimeZone zone)
Sets the time zone used to display date/time/date-time values. See FreeMarker'sConfiguration.setTimeZone(TimeZone)
for more information.
-
setTimeZone
public void setTimeZone(java.lang.String zone)
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
public void setSQLDateAndTimeTimeZone(java.util.TimeZone zone)
Sets the time zone used when dealing withjava.sql.Date
andjava.sql.Time
values. See FreeMarker'sConfigurable.setSQLDateAndTimeTimeZone(TimeZone)
for more information.
-
setSQLDateAndTimeTimeZone
public void setSQLDateAndTimeTimeZone(java.lang.String zone)
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
public java.util.TimeZone getTimeZone()
- See Also:
setTimeZone(java.util.TimeZone)
-
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
public void addOutputFormatChooser(java.lang.String pathPattern, freemarker.core.OutputFormat outputFormat)
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(java.lang.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:
Configuration.getOutputFormat(String)
-
addModeChooser
public void addModeChooser(java.lang.String pattern, int pmode)
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
public void addHeaderChooser(java.lang.String pattern, java.lang.String header)
Deprecated.UseaddHeaderChooser(int, String, String)
instead.Adds a new entry to the end of path-pattern -> header mapping list of layer 0.
-
addHeaderChooser
public void addHeaderChooser(int layer, java.lang.String pattern, java.lang.String footer)
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.
-
addFooterChooser
public void addFooterChooser(java.lang.String pattern, java.lang.String footer)
Deprecated.UseaddFooterChooser(int, String, String)
instead.Adds a new entry to the end of path-pattern -> footer mapping list of layer 0.
-
addFooterChooser
public void addFooterChooser(int layer, java.lang.String pattern, java.lang.String footer)
Adds a new entry to the end of path-pattern -> footer mapping list of the given layer. Layers are indexed from 0. The lower the layer index is, the later the footer occurs in the text.
-
addTurnChooser
public void addTurnChooser(java.lang.String pattern, int turn)
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.
-
clearFooterChoosers
public void clearFooterChoosers()
Removes all footer 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:
setCaseSensitive(boolean)
-
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:
setExpertMode(boolean)
-
addRemovePostfix
public void addRemovePostfix(java.lang.String postfix)
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
public void addRemoveExtension(java.lang.String extension)
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
public void addReplaceExtension(java.lang.String oldExtension, java.lang.String newExtension)
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
public void setXpathEngine(java.lang.String xpathEngine)
Sets if which XPath engine should be used.- Parameters:
xpathEngine
- one of theXPATH_ENGINE_...
constants, or a class name.
-
getXpathEngine
public java.lang.String getXpathEngine()
-
setXmlEntityResolver
public void setXmlEntityResolver(java.lang.Object xmlEntityResolver) throws InstallationException
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
public java.lang.Object 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
public void addXmlRenderingConfiguration(XmlRenderingConfiguration xmlRendering)
Adds as XML rendering configuration.
-
clearXmlRenderingConfigurations
public void clearXmlRenderingConfigurations()
Removes all XML rendering configurations.
-
addData
public void addData(java.lang.String name, java.lang.Object value)
Adds a variable that will be visible for all templates when the processing session executes.
-
addData
public void addData(java.lang.String name, byte value)
Convenience method for adding aByte
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, short value)
Convenience method for adding aShort
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, int value)
Convenience method for adding aInteger
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, long value)
Convenience method for adding aLong
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, float value)
Convenience method for adding aFloat
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, double value)
Convenience method for adding aDouble
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, char value)
Convenience method for adding aCharacter
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.lang.String name, boolean value)
Convenience method for adding aBoolean
object.- See Also:
addData(String, Object)
-
addData
public void addData(java.util.Map map)
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:
addData(String, Object)
-
getData
public java.lang.Object getData(java.lang.String name)
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:
addData(String, Object)
-
removeData
public java.lang.Object removeData(java.lang.String name)
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:
addData(String, Object)
-
clearSharedVariables
public void clearSharedVariables()
Deprecated.UseclearData()
instead.
-
addLocalDataBuilder
public void addLocalDataBuilder(int layer, java.lang.String pathPattern, LocalDataBuilder builder)
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.
-
getProgressListenerEventName
public static java.lang.String getProgressListenerEventName(int event)
Converts anProgressListener.EVENT_...
constant to English text.
-
wrap
public freemarker.template.TemplateModel wrap(java.lang.Object obj) throws freemarker.template.TemplateModelException
Wraps any object asTemplateModel
.- Throws:
freemarker.template.TemplateModelException
-
getTemplateEnvironment
public TemplateEnvironment 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:
java.lang.IllegalStateException
- if the template environment is not available.
-
isTemplateEnvironmentAvailable
public boolean isTemplateEnvironmentAvailable()
Tells ifgetTemplateEnvironment()
will throw exception or not.
-
setAttribute
public java.lang.Object setAttribute(java.lang.String name, java.lang.Object value)
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
public java.lang.Object getAttribute(java.lang.String name)
Reads an engine attribute.- Returns:
null
if no attribute exists with the given name.- See Also:
setAttribute(String, Object)
-
removeAttribute
public java.lang.Object removeAttribute(java.lang.String name)
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:
setAttribute(String, Object)
-
clearAttribues
public void clearAttribues()
Removes all attributes.- See Also:
setAttribute(String, Object)
-
getVersionNumber
public static java.lang.String 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
public static java.lang.String getBuildInfo()
Returns FMPP build info. This is usually the date of the build, but it can be anything.
-
getFreeMarkerVersionNumber
public static java.lang.String 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
public void checkXmlSupportAvailability(java.lang.String requiredForThis) throws InstallationException
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.
-
-