fmpp
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 a Settings object instead of directly using this class.

fmpp.Engine vs fmpp.setting.Settings: The design of the Engine object API is driven by the internal architecture of FMPP system. It doesn't consider front-ends, doesn't know configuration files or similar high-level stuff. Settings wraps the Engine object, and implements end-user (front-end) centric concepts, as the settings and configuration files described in the FMPP Manual. The API of Engine is more natural and convenient than the API of a Map-like object as a Settings object. But Settings are far easier to use if you want FMPP behave as described in the FMPP Manual from the viewpoint of end-user. In principle, if FMPP is used embedded in a way that the end-user will never face FMPP (doesn't use the FMPP Manual, etc.), using the Engine object directly can be a good solution. But, since the Java programmers get know FMPP through the higher-level concepts (they try it with the command-line tool, etc.), I say, just use Settings always. The resource usage overhead is negligible, and all capabilities of the Engine will be available, plus some extra features (as configuration files). So basically, the introduction of Settings has degraded Engine to an internally used object.

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. Settings use the front-end/end-user's viewpoint, and are mostly built on the top of engine parameters, while engine parameters use FMPP system implementation driven approach.
The value of engine parameters can't be set while a processing session is executing. An attempt to do so will result in 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 (because it can't be...).

Life-cycle: The engine object can be used for multiple processing sessions. However, the typical usage is that it is 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 plugged long-lived objects as local data builders and progress listeners can maintain state through multiple sessions. These objects should behave so that the output files of a session is not influenced by earlier sessions.

Field Summary

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 template
static int	PMODE_IGNORE Processing mode: Ignore the file.
static int	PMODE_NONE Processing mode: N/A
static 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 files
static int	SKIP_NONE Used with the "skipUnchnaged" engine parameter: never skip files
static int	SKIP_STATIC Used with the "skipUnchanged" engine parameter: skip unchanged static files
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

Engine()
Same as Engine(null).

Engine(freemarker.ext.beans.BeansWrapper beansWrapper)
Creates a new FMPP engine instance.

Method Summary

void	addData(java.util.Map map) Adds all entries with addData(String, Object).
void	addData(java.lang.String name, boolean value) Convenience method for adding a Boolean object.
void	addData(java.lang.String name, byte value) Convenience method for adding a Byte object.
void	addData(java.lang.String name, char value) Convenience method for adding a Character object.
void	addData(java.lang.String name, double value) Convenience method for adding a Double object.
void	addData(java.lang.String name, float value) Convenience method for adding a Float object.
void	addData(java.lang.String name, int value) Convenience method for adding a Integer object.
void	addData(java.lang.String name, long value) Convenience method for adding a Long 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.lang.String name, short value) Convenience method for adding a Short 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. Use addFooterChooser(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. Use addHeaderChooser(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	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	clearProgressListeners() Removes all progress listeners from the list of progress listeners that were added with addProgressListener(fmpp.ProgressListener).
void	clearRemoveExtensions()
void	clearRemovePostfixes()
void	clearReplaceExtensions()
void	clearSharedVariables() Deprecated. Use clearData() instead.
void	clearTurnChoosers() Removes all turn choosers.
void	clearXmlRenderingConfigurations() Removes all XML rendering configurations.
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()
boolean	getExpertMode()
java.util.List	getFreemarkerLink(java.lang.String name) Returns the list of files associated with a FreeMarker link name.
static java.lang.String	getFreeMarkerVersionNumber()
boolean	getIgnoreCvsFiles()
boolean	getIgnoreSvnFiles()
boolean	getIgnoreTemporaryFiles()
java.util.Locale	getLocale() Returns the actual (non-null) locale in use.
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 never null or "host".
java.io.File	getOutputRoot() Returns the output root directory.
static java.lang.String	getProgressListenerEventName(int event) Converts an ProgressListener.EVENT_...
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 the TemplateEnvironment.
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 never null.
boolean	getValidateXml()
static java.lang.String	getVersionNumber() Returns the FMPP version number string.
java.lang.Object	getXmlEntiryResolver() Gets the XML entiry resolver used for reading XML documents.
java.lang.String	getXpathEngine()
boolean	isTemplateEnvironmentAvailable() Tells if getTemplateEnvironment() 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.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Adds/replaces an engine attribute.
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	setExpertMode(boolean expertMode) Allows some features that are considerd dangerous.
void	setIgnoreCvsFiles(boolean ignoreCvsFiles) Sets if the CVS files inside the source root directory should be ignoread or not.
void	setIgnoreSvnFiles(boolean ignoreSvnFiles) Sets if the SVN files inside the source root directory should be ignoread or not.
void	setIgnoreTemporaryFiles(boolean ignoreTemporaryFiles) Set if well-known temporary files inside the source root directory should be ingored or not.
void	setLocale(java.util.Locale locale) Sets the locale (country, language).
void	setLocale(java.lang.String locale) Sets the locale (country, language).
void	setNumberFormat(java.lang.String format) Sets the number format used to convert numbers to strings.
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	setOutputRoot(java.io.File outputRoot) Sets the root directory of output files.
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	setStopOnError(boolean stopOnError)
void	setTagSyntax(int tagSyntax) Sets the tagSyntax setting of FreeMarker.
void	setTemplateDataModelBuilder(java.lang.String className)
void	setTemplateDataModelBuilder(TemplateDataModelBuilder tdmBuilder) Sets the class that will be instantiated to create the template specfic variables.
void	setTimeFormat(java.lang.String format) Sets the format used to convert time values (hour + minute + second + millisecond) to strings.
void	setTimeZone(java.util.TimeZone zone) Sets the time zone used to display 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.
freemarker.template.TemplateModel	wrap(java.lang.Object obj) Wraps any object as TemplateModel.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Constructor Detail

Engine

public Engine()

Same as Engine(null).

Engine

public Engine(freemarker.ext.beans.BeansWrapper beansWrapper)

Creates a new FMPP engine instance. Use the setter methods (as setProgressListener) to configure the new instance.

Parameters:

beansWrapper - the FreeMarker beans-wrapper that this instance will use. Just use null if you don't know what's this. If you do know what's this, note that FMPP by default (when this parameter is null) uses a BeansWrapper with simpleMapWrapper set to true.

Method Detail

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 diretories 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 exeption.

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 runing, 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 runing, 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 @ preifx)

Returns:

the list of canonical files 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:

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

setTemplateDataModelBuilder

public void setTemplateDataModelBuilder(TemplateDataModelBuilder tdmBuilder)

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

Throws:

DataModelBuildingException

See Also:

setTemplateDataModelBuilder(TemplateDataModelBuilder)

getTemplateDataModelBuilder

public TemplateDataModelBuilder getTemplateDataModelBuilder()

See Also:

setTemplateDataModelBuilder(TemplateDataModelBuilder)

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

getOldTemplateSyntax

public boolean getOldTemplateSyntax()

See Also:

setOldTemplateSyntax(boolean)

setTagSyntax

public void setTagSyntax(int tagSyntax)

Sets the tagSyntax setting of FreeMarker. The recommendend value for new projects is Configuration.AUTO_DETECT_TAG_SYNTAX, the defalt with FreeMarker 2.3.x is Configuration.ANGLE_BRACKET_TAG_SYNTAX, the default with FreeMarker 2.4 and later is Configuration.AUTO_DETECT_TAG_SYNTAX.

getTagSyntax

public int getTagSyntax()

See Also:

setTagSyntax(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 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. This is a pattern as java.text.DecimalFormat defines, or the reserved values "number" or "currency".

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. This is a pattern as java.text.SimpleDateFormat defines, or the reserved values "short" or "medium" or "long". Please read the FreeMarker Manual 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. This is a pattern as java.text.SimpleDateFormat defines, or the reserved values "short" or "medium" or "long". Please read the FreeMarker Manual 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. This is a pattern as java.text.SimpleDateFormat defines, or the reserved values "short" or "medium" or "long", or "short_medium", "short_long" or "medium_short", etc. Please read the FreeMarker Manual 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 time values. By default, the time zone where you are, will be used.

getTimeZone

public java.util.TimeZone getTimeZone()

See Also:

setTimeZone(java.util.TimeZone)

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.

clearModeChoosers

public void clearModeChoosers()

Removes all processing mode choosers. This is the inital state after the instantiantion 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:

setCaseSensitive(boolean)

setExpertMode

public void setExpertMode(boolean expertMode)

Allows some features that are considerd 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()

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()

setIgnoreCvsFiles

public void setIgnoreCvsFiles(boolean ignoreCvsFiles)

Sets if the CVS files inside the source root directory should be ignoread 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 ignoread 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 ingored 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 is declared as Object to prevent linkage errors when XML related features are not used), 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 is declared as Object to prevent linkage errors when XML related features are not used).

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.

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

clearLocalDataBuilders

public void clearLocalDataBuilders()

Removes all local data builders.

See Also:

addLocalDataBuilder(int, String, LocalDataBuilder)

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)

clearAttribues

public void clearAttribues()

Removes all attributes.

See Also:

setAttribute(String, Object)

getVersionNumber

public static java.lang.String getVersionNumber()

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.

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()

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.