Package fmpp

Class Engine

java.lang.Object
fmpp.Engine
public class Engine extends Object
The bare-bone, low-level preprocessor engine. Since FMPP 0.9.0 you should rather use a 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 Details

    • PMODE_NONE

      public static final int PMODE_NONE
      Processing mode: N/A
      See Also:

    • PMODE_EXECUTE

      public static final int PMODE_EXECUTE
      Processing mode: Execute the file as template
      See Also:

    • PMODE_COPY

      public static final int PMODE_COPY
      Processing mode: Copy the file as-is (binary copy).
      See Also:

    • PMODE_IGNORE

      public static final int PMODE_IGNORE
      Processing mode: Ignore the file.
      See Also:

    • PMODE_RENDER_XML

      public static final int PMODE_RENDER_XML
      Processing mode: Render XML with an FTL template.
      See Also:

    • SKIP_NONE

      public static final int SKIP_NONE
      Used with the "skipUnchnaged" engine parameter: never skip files
      See Also:

    • SKIP_STATIC

      public static final int SKIP_STATIC
      Used with the "skipUnchanged" engine parameter: skip unchanged static files
      See Also:

    • SKIP_ALL

      public static final int SKIP_ALL
      Used with the "skipUnchanged" engine parameter: skip all unchanged files
      See Also:

    • PARAMETER_VALUE_SOURCE

      public static final String PARAMETER_VALUE_SOURCE
      A commonly used reserved parameter value: "source".
      See Also:

    • PARAMETER_VALUE_OUTPUT

      public static final String PARAMETER_VALUE_OUTPUT
      A commonly used reserved parameter value: "source".
      See Also:

    • PARAMETER_VALUE_HOST

      public static final String PARAMETER_VALUE_HOST
      A commonly used reserved parameter value: "host".
      See Also:

    • XPATH_ENGINE_DONT_SET

      public static final String XPATH_ENGINE_DONT_SET
      Used as the value of the "xmlEngine" engine parameter: keep the current JVM level setting.
      See Also:

    • XPATH_ENGINE_DEFAULT

      public static final String XPATH_ENGINE_DEFAULT
      Used as the value of the "xmlEngine" engine parameter: Let FreeMarker choose.
      See Also:

    • XPATH_ENGINE_XALAN

      public static final String XPATH_ENGINE_XALAN
      Used as the value of the "xmlEngine" engine parameter: Force the usage of Xalan.
      See Also:

    • XPATH_ENGINE_JAXEN

      public static final String 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

  • Constructor Details

    • Engine

      public Engine()
      Deprecated.
      Use Engine(Version) instead.
      Same as Engine((Version) null).

    • Engine

      public Engine(freemarker.template.Version recommendedDefaults)
      Same as Engine(recommendedDefaults, null, null).

    • Engine

      public Engine(freemarker.ext.beans.BeansWrapper objectWrapper)
      Deprecated.
      Use Engine(Version, Version, BeansWrapper) instead.
      Same as Engine(null, objectWrapper, null).

    • Engine

      public Engine(freemarker.ext.beans.BeansWrapper objectWrapper, freemarker.template.Version freemarkerIncompatibleImprovements)
      Deprecated.
      Use Engine(Version, Version, BeansWrapper) instead.
      Same as Engine(null, objectWrapper, fmIncompImprovements).

    • 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 (as setProgressListener) 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). If null, 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 with ftlh and ftlx file extensions will use HTML and XML auto-escaping respectively.
        • mapCommonExtensionsToOutputFormats to true, thus, templates with common file extensions like html, xml etc. will have auto-escaping.
        • removeFreemarkerExtensions to true, thus, the ftl, ftlh, and ftlx 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 a DefaultObjectWrapper, if freemarkerIncompatibleImprovements is at least 2.3.21} There are more details, but see that at the objectWrapper parameter.
      freemarkerIncompatibleImprovements - Sets the "incompatible improvements" version of FreeMarker. You should set this to the current FreeMarker version in new projects. See Configuration(Version) for details. If this is null and the recommendedDefaults argument is 0.9.16, then "incompatible improvements" defaults to 2.3.28. If this is null and recommendedDefaults 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 FreeMarker ObjectWrapper that this instance will use. Just use null if you don't know what's this. When this parameter is null, FMPP chooses the default, considering FreeMarker best practices and backward compatibility concerns. So it's somewhat complex, and depends on both the recommendedDefaults and the fmIncompImprovements arguments. If recommendedDefaults is at least 0.9.16, and fmIncompImprovements is either null or at least 2.3.22, then FMPP creates a DefaultObjectWrapper with its incompatibleImprovements setting set to FreeMarker incompatibleImprovements, its forceLegacyNonListCollections setting set to false, its iterableSupport setting to true, and its treatDefaultMethodsAsBeanMembers setting set to true. Otherwise, FMPP creates a BeansWrapper (not a DefaultObjectWrapper) with its simpleMapWrapper setting set to true, and also, if the FreeMarker incompatibleImprovements will be at least 2.3.21, it's created using BeansWrapperBuilder instead of new BeansWrapper(), which means that that the resulting BeansWrapper 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 the recommendedDefaults is in the supported range.
      Parameters:
      recommendedDefaults - The version to validate. If null, 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 the freemarkerIncompatibleImprovements setting, when null is passed for it to the Engine constructor. This was exposed as sometimes you need this information earlier than calling the Engine constructor.
      Since:
      0.9.16

    • process

      public void process(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 - if Engine.process has thrown any exception. The message of this exception holds nothing interesting (just a static text). Call its getCause() 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

      public void process(File src, 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 - if Engine.process has thrown any exception. The message of this exception holds nothing interesting (just a static text). Call its getCause() 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 of Engine(Version, Version, BeansWrapper).

    • getStopOnError

      public boolean getStopOnError()

    • setStopOnError

      public void setStopOnError(boolean stopOnError)

    • getOutputRoot

      public 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 canonical File.

    • setOutputRoot

      public void setOutputRoot(File outputRoot) throws 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:
      IOException

    • getSourceRoot

      public 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 canonical File.

    • setSourceRoot

      public void setSourceRoot(File srcRoot) throws 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:
      IOException

    • getDataRoot

      public 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 canonical File.

    • setDataRoot

      public void setDataRoot(File dataRoot) throws IOException
      Sets the root directory of data files. If it is "source" or null, then the source directory will be used.
      Throws:
      IOException

    • addFreemarkerLink

      public void addFreemarkerLink(String name, File fileOrDir) throws 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 for pp 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 file blah.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

      public List getFreemarkerLink(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, or null, if no FreeMarker link with the given name exist.

    • clearFreemarkerLinks

      public void clearFreemarkerLinks()
      Removes all FreeMarker links.
      See Also:

    • 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 with addProgressListener(fmpp.ProgressListener). It does not affect other listening objects, as local data loaders or engine attributes.

    • setTemplateDataModelBuilder

      public void setTemplateDataModelBuilder(TemplateDataModelBuilder tdmBuilder)
      Deprecated.
      Use addLocalDataBuilder(int, String, LocalDataBuilder) instead
      Sets the class that will be instantiated to create the template specfic variables.
      See Also:

    • setTemplateDataModelBuilder

      public void setTemplateDataModelBuilder(String className) throws DataModelBuildingException
      Deprecated.
      Use addLocalDataBuilder(int, String, LocalDataBuilder) instead
      Throws:
      DataModelBuildingException
      See Also:

    • getTemplateDataModelBuilder

      public TemplateDataModelBuilder getTemplateDataModelBuilder()
      See Also:

    • setSourceEncoding

      public void setSourceEncoding(String encoding)
      Sets the encoding (charset) of textual source files. Note that according to FreeMarker rules, this can be overridden in a template with &lt;#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 String getSourceEncoding()
      Returns the source encoding used for the template files. This is not null or "host"; this is always a concrete encoding, such as "UTF-8".

    • setLocale

      public void setLocale(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(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 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 is false.

    • getOldTemplateSyntax

      public boolean getOldTemplateSyntax()
      See Also:

    • setTagSyntax

      public void setTagSyntax(int tagSyntax)
      Sets the tagSyntax setting of FreeMarker. The recommended value for new projects is Configuration.AUTO_DETECT_TAG_SYNTAX, the defalt with FreeMarker 2.3.x is Configuration.ANGLE_BRACKET_TAG_SYNTAX.

    • getTagSyntax

      public int getTagSyntax()
      See Also:

    • setInterpolationSyntax

      public void setInterpolationSyntax(int interpolationSyntax)
      Sets the interpolationSyntax 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

      public void setOutputEncoding(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 String getOutputEncoding()
      Retruns the output encoding used; It can be "source" (since that can't be resolved to a concrete charset), but never null or "host".

    • setUrlEscapingCharset

      public void setUrlEscapingCharset(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 String getUrlEscapingCharset()
      Retruns the output encoding used; It can be "output" (since that can't be resolved to a concrete charset), but never null.

    • setNumberFormat

      public void setNumberFormat(String format)
      Sets the number format used to convert numbers to strings, as defined by Configurable.setNumberFormat(String). At least on FreeMarker 2.3.21, this is a pattern as DecimalFormat defines it, or the reserved values "number" or "currency".

    • setBooleanFormat

      public void setBooleanFormat(String format)
      Sets the boolean format used to convert boolean to strings, as defined by Configurable.setBooleanFormat(String). Note that it can't be "true,false"; for that you have to print the boolean value with ${foo?c}.

    • getNumberFormat

      public String getNumberFormat()
      See Also:

    • setDateFormat

      public void setDateFormat(String format)
      Sets the format used to convert date values (year + month + day) to strings. See Configurable.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 String getDateFormat()
      See Also:

    • setTimeFormat

      public void setTimeFormat(String format)
      Sets the format used to convert time values (hour + minute + second + millisecond) to strings. See Configurable.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 String getTimeFormat()
      See Also:

    • setDateTimeFormat

      public void setDateTimeFormat(String format)
      Sets the format used to convert date-time values (year + month + day + hour + minute + second + millisecond) to strings. See Configurable.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 String getDateTimeFormat()
      See Also:

    • setTimeZone

      public void setTimeZone(TimeZone zone)
      Sets the time zone used to display date/time/date-time values. See FreeMarker's Configuration.setTimeZone(TimeZone) for more information.

    • setTimeZone

      public void setTimeZone(String zone)
      Same as setTimeZone(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(TimeZone zone)
      Sets the time zone used when dealing with java.sql.Date and java.sql.Time values. See FreeMarker's Configurable.setSQLDateAndTimeTimeZone(TimeZone) for more information.

    • setSQLDateAndTimeTimeZone

      public void setSQLDateAndTimeTimeZone(String zone)
      Same as setSQLDateAndTimeTimeZone(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 TimeZone 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 FreeMarker OutputFormat, for the purpose of auto-escaping. This defaults to true if getRecommendedDefaults() is at least 0.9.16, otherwise it defaults to false.

      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, so example.rtf.ftl will be mapped to RTF output format.

      Since:
      0.9.16

    • getMapCommonExtensionsToOutputFormats

      public boolean getMapCommonExtensionsToOutputFormats()
      Getter pair of setMapCommonExtensionsToOutputFormats(boolean).
      Since:
      0.9.16

    • setOutputFormat

      public void setOutputFormat(freemarker.core.OutputFormat outputFormat)
      Sets the OutputFormat used in templates when there's no more specific one chosen by path pattern.
      Parameters:
      outputFormat - Not null; use UndefinedOutputFormat.INSTANCE instead.
      Since:
      0.9.16

    • getOutputFormat

      public freemarker.core.OutputFormat getOutputFormat()
      Getter pair of setOutputFormat(OutputFormat).
      Returns:
      Not null.
      Since:
      0.9.16

    • addOutputFormatChooser

      public void addOutputFormatChooser(String pathPattern, freemarker.core.OutputFormat outputFormat)
      Adds a new entry to the end of path-pattern -> output-format mapping list. This corresponds to the outputFormatsByPath setting in the Settings API.
      Since:
      0.9.16

    • getOutputFormat

      public freemarker.core.OutputFormat getOutputFormat(String name) throws freemarker.core.UnregisteredOutputFormatException
      Resolves an FreeMarker "output format" name to an OutputFormat object.
      Throws:
      freemarker.core.UnregisteredOutputFormatException
      Since:
      0.9.16
      See Also:
      • Configuration.getOutputFormat(String)

    • addModeChooser

      public void addModeChooser(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 the PMODE_... constants.

    • addHeaderChooser

      public void addHeaderChooser(String pattern, String header)
      Deprecated.
      Use addHeaderChooser(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, String pattern, 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(String pattern, String footer)
      Deprecated.
      Use addFooterChooser(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, String pattern, 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(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 the outputFormatsByPath setting in the Settings API.
      Since:
      0.9.16

    • clearModeChoosers

      public void clearModeChoosers()
      Removes all processing mode choosers. This is the initial state after the instantiation of Engine (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:

    • 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

      public void addRemovePostfix(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(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(String oldExtension, 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 to true if getRecommendedDefaults() is at least 0.9.16.
      Since:
      0.9.16

    • getRemoveFreemarkerExtensions

      public boolean getRemoveFreemarkerExtensions()
      Getter pair of setRemoveFreemarkerExtensions(boolean).
      Since:
      0.9.16

    • setDontTraverseDirectories

      public void setDontTraverseDirectories(boolean dontTraverseDirs)
      Sets the Engine should automatically process the files and directories inside a directory whose processing was asked through the public Engine API. Defaults to true. It is set to false by front-ends that explicitly specify the list of source files and source directories, rather than expecting the Engine 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 - a SKIP_... 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 to false.

      Notes:

      • Even if this is set to true, if a directory contains an ignoredir.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 is false.

    • 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(String xpathEngine)
      Sets if which XPath engine should be used.
      Parameters:
      xpathEngine - one of the XPATH_ENGINE_... constants, or a class name.

    • getXpathEngine

      public String getXpathEngine()

    • setXmlEntityResolver

      public void setXmlEntityResolver(Object xmlEntityResolver) throws InstallationException
      Sets the XML entiry resolver used for reading XML documents. The default value is null.
      Parameters:
      xmlEntityResolver - it must implement org.xml.sax.EntityResolver (it was declared as Object to prevent linkage errors when XML related features are not used on pre-1.4 Java), or it must be null.
      Throws:
      InstallationException

    • getXmlEntiryResolver

      public Object getXmlEntiryResolver()
      Gets the XML entiry resolver used for reading XML documents.
      Returns:
      null of no resolver is used, or an org.xml.sax.EntityResolver (it was declared as Object 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 to true.

    • 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(String name, Object value)
      Adds a variable that will be visible for all templates when the processing session executes.

    • addData

      public void addData(String name, byte value)
      Convenience method for adding a Byte object.
      See Also:

    • addData

      public void addData(String name, short value)
      Convenience method for adding a Short object.
      See Also:

    • addData

      public void addData(String name, int value)
      Convenience method for adding a Integer object.
      See Also:

    • addData

      public void addData(String name, long value)
      Convenience method for adding a Long object.
      See Also:

    • addData

      public void addData(String name, float value)
      Convenience method for adding a Float object.
      See Also:

    • addData

      public void addData(String name, double value)
      Convenience method for adding a Double object.
      See Also:

    • addData

      public void addData(String name, char value)
      Convenience method for adding a Character object.
      See Also:

    • addData

      public void addData(String name, boolean value)
      Convenience method for adding a Boolean object.
      See Also:

    • addData

      public void addData(Map map)
      Adds all entries with addData(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

      public Object getData(String name)
      Gets the value of a variable. This method accesses the variables that are visible for all templates. It corresponds to setting data.

      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 FreeMarker TemplateModel types, such as variables created by some of the data loaders).
      See Also:

    • removeData

      public Object removeData(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:

    • clearSharedVariables

      public void clearSharedVariables()
      Deprecated.
      Use clearData() instead.

    • addLocalDataBuilder

      public void addLocalDataBuilder(int layer, String pathPattern, LocalDataBuilder builder)
      Adds a local data builder. The local data builder will be invoked directly before the execution of templates (if the pathPattern 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

      public static String getProgressListenerEventName(int event)
      Converts an ProgressListener.EVENT_... constant to English text.

    • wrap

      public freemarker.template.TemplateModel wrap(Object obj) throws freemarker.template.TemplateModelException
      Wraps any object as TemplateModel.
      Throws:
      freemarker.template.TemplateModelException

    • getTemplateEnvironment

      public TemplateEnvironment getTemplateEnvironment()
      Returns the TemplateEnvironment. The template environment is available with this method only when a template execution is in progress, or when a TemplateDataModelBuilder (deprecated) is running.
      Throws:
      IllegalStateException - if the template environment is not available.

    • isTemplateEnvironmentAvailable

      public boolean isTemplateEnvironmentAvailable()
      Tells if getTemplateEnvironment() will throw exception or not.

    • setAttribute

      public Object setAttribute(String name, Object value)
      Adds/replaces an engine attribute. Attributes are arbitrary key-value pairs that are associated with the Engine object. FMPP reserves all keys starting with fmpp. for its own use. Attributes are not understood by the Engine, 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 implements ProgressListener, then it will receive notifications about the events of the Engine. 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 Object getAttribute(String name)
      Reads an engine attribute.
      Returns:
      null if no attribute exists with the given name.
      See Also:

    • removeAttribute

      public Object removeAttribute(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:

    • clearAttribues

      public void clearAttribues()
      Removes all attributes.
      See Also:

    • getVersionNumber

      public static String getVersionNumber()
      Deprecated.
      Use getVersion() instead. If you have need a String, it has a proper Version.toString().
      Returns the FMPP version number string. FMPP version number string follows the major.minor.sub or major.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 String getBuildInfo()
      Returns FMPP build info. This is usually the date of the build, but it can be anything.

    • getFreeMarkerVersionNumber

      public static String getFreeMarkerVersionNumber()
      Deprecated.
      Use getFreeMarkerVersion() instead. If you have need a String, it has a proper Version.toString().

    • 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(String requiredForThis) throws InstallationException
      Checks if XML support is available. It can be quicker than MiscUtil.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 the InstallationException. Can be null.
      Throws:
      InstallationException - if the XML support is not available.