Package fmpp

Class Engine

  • public class Engine
extends java.lang.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 Detail

      • 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 the recommendDefaults 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

    • Constructor Detail

      • 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 Detail

      • 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:
        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 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​(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 - 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(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 - 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:
        process(File[])

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

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

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

      • setDataRoot

        public void setDataRoot​(java.io.File dataRoot)
                 throws java.io.IOException
        Sets the root directory of data files. If it is "source" or null, 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 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:
        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, or null, if no FreeMarker link with the given name exist.

      • 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.

      • 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 &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 java.lang.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​(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 is false.

      • 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.

      • 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

      • 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 never null 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 never null.

      • setNumberFormat

        public void setNumberFormat​(java.lang.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​(java.lang.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}.

      • setDateFormat

        public void setDateFormat​(java.lang.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.

      • setTimeFormat

        public void setTimeFormat​(java.lang.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.

      • 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. 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.

      • setTimeZone

        public void setTimeZone​(java.util.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​(java.lang.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​(java.util.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​(java.lang.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.

      • 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

      • 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​(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 the outputFormatsByPath setting in the Settings 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 an OutputFormat 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 the PMODE_... constants.

      • addHeaderChooser

        public void addHeaderChooser​(java.lang.String pattern,
                             java.lang.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,
                             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.
        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,
                             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 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).

      • 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

      • 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 to true if getRecommendedDefaults() is at least 0.9.16.
        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​(java.lang.String xpathEngine)
        Sets if which XPath engine should be used.
        Parameters:
        xpathEngine - one of the XPATH_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 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 java.lang.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​(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 a Byte object.
        See Also:
        addData(String, Object)

      • addData

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

      • addData

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

      • addData

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

      • addData

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

      • addData

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

      • addData

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

      • addData

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

      • addData

        public void addData​(java.util.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.

      • 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 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:
        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.
        Use clearData() 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 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.

      • getProgressListenerEventName

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

      • wrap

        public freemarker.template.TemplateModel wrap​(java.lang.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:
        java.lang.IllegalStateException - if the template environment is not available.

      • isTemplateEnvironmentAvailable

        public boolean isTemplateEnvironmentAvailable()
        Tells if getTemplateEnvironment() 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 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 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)

      • getVersionNumber

        public static java.lang.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 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.
        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​(java.lang.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.