fmpp.setting
Class Settings

java.lang.Object
  fmpp.setting.Settings

public class Settings
extends java.lang.Object

Stores FMPP settings, loads configuration files, provides other setting handling related utilities.

Settings are typed variables identified with their case-sensitive name. When you set the value of a setting, the value object you supply must be of the correct type. See the description of the TYPE_... to see the available setting types.

Methods that change setting values have a variation that require String value(s) instead of Object(s). These methods should be used when you get the setting values from text-only sources, such as command-line option values, XML attributes or .properties file. To demonstrate the difference, assume you have string value "a, b, c". If you try to use this value for a setting of type list, the normal setter method will interpret the value as a list of length 1, that stores string "a, b, c". If you try to use the same value with the string version of the same method, it will interpret the string as a list of length 3, that stores 3 strings, "a", "b", and "c".

Notes:

• All settings you want to set/get must be defined. See define(java.lang.String, fmpp.setting.Settings.SettingType, boolean, boolean). Standard settings (the settings documented in the FMPP Manual) are initially already defined.
• If you have used an object as the value of a setting, the object must not be changed anymore.
• If a method throws SettingException, then it is ensured that the method doesn't change the Settings object. For example, with add(Map), either all settings in the map will be successfully set, or neither will be set.

You can execute the processing session described by the setting with execute().

Field Summary

static java.lang.String	DEFAULT_CFG_FILE_NAME Primary default file name.
static java.lang.String	DEFAULT_CFG_FILE_NAME_OLD Secondary (legacy) default file name.
static java.lang.String	NAME_APPEND_LOG_FILE
static java.lang.String	NAME_BORDERS
static java.lang.String	NAME_CASE_SENSITIVE
static java.lang.String	NAME_COLUMNS
static java.lang.String	NAME_CONFIGURATION_BASE
static java.lang.String	NAME_DATA
static java.lang.String	NAME_DATA_ROOT
static java.lang.String	NAME_DATE_FORMAT
static java.lang.String	NAME_DATETIME_FORMAT
static java.lang.String	NAME_ECHO_FORMAT
static java.lang.String	NAME_EXPERT
static java.lang.String	NAME_FREEMARKER_LINKS
static java.lang.String	NAME_IGNORE_CVS_FILES
static java.lang.String	NAME_IGNORE_SVN_FILES
static java.lang.String	NAME_IGNORE_TEMPORARY_FILES
static java.lang.String	NAME_INHERIT_CONFIGURATION
static java.lang.String	NAME_LOCAL_DATA
static java.lang.String	NAME_LOCALE
static java.lang.String	NAME_LOG_FILE
static java.lang.String	NAME_MODES
static java.lang.String	NAME_NUMBER_FORMAT
static java.lang.String	NAME_OBJECT_WRAPPER
static java.lang.String	NAME_OUTPUT_ENCODING
static java.lang.String	NAME_OUTPUT_FILE
static java.lang.String	NAME_OUTPUT_ROOT
static java.lang.String	NAME_QUIET
static java.lang.String	NAME_REMOVE_EXTENSIONS
static java.lang.String	NAME_REMOVE_POSTFIXES
static java.lang.String	NAME_REPLACE_EXTENSIONS
static java.lang.String	NAME_SKIP_UNCHANGED
static java.lang.String	NAME_SNIP
static java.lang.String	NAME_SOURCE_ENCODING
static java.lang.String	NAME_SOURCE_ROOT
static java.lang.String	NAME_SOURCES
static java.lang.String	NAME_STOP_ON_ERROR
static java.lang.String	NAME_TAG_SYNTAX
static java.lang.String	NAME_TEMPLATE_DATA
static java.lang.String	NAME_TIME_FORMAT
static java.lang.String	NAME_TIME_ZONE
static java.lang.String	NAME_TURNS
static java.lang.String	NAME_URL_ESCAPING_CHARSET
static java.lang.String	NAME_VALIDATE_XML
static java.lang.String	NAME_XML_CATALOG_FILES
static java.lang.String	NAME_XML_CATALOG_PREFER
static java.lang.String	NAME_XML_RENDERINGS
static java.lang.String	NAME_XPATH_ENGINE
static java.lang.String	OLD_NAME_REMOVE_EXTENSION
static java.lang.String	OLD_NAME_REMOVE_POSTFIX
static java.lang.String	OLD_NAME_REPLACE_EXTENSION
static fmpp.setting.Settings.SettingType	TYPE_ANY Any object.
static fmpp.setting.Settings.SettingType	TYPE_BOOLEAN Boolean setting type.
static fmpp.setting.Settings.SettingType	TYPE_CFG_RELATIVE_PATH "Configuration relative path" setting type.
static fmpp.setting.Settings.SettingType	TYPE_CFG_RELATIVE_PATHS "Configuration relative paths" setting type.
static fmpp.setting.Settings.SettingType	TYPE_DATA_MODEL Data model setting type.
static fmpp.setting.Settings.SettingType	TYPE_HASH Hash setting type.
static fmpp.setting.Settings.SettingType	TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS Hash-of-configuration-relative-paths setting type.
static fmpp.setting.Settings.SettingType	TYPE_INTEGER Integer setting type.
static fmpp.setting.Settings.SettingType	TYPE_LOCAL_DATA_MODEL Local data model setting type.
static fmpp.setting.Settings.SettingType	TYPE_SEQUENCE Sequence setting type.
static fmpp.setting.Settings.SettingType	TYPE_STRING String setting type.
static fmpp.setting.Settings.SettingType	TYPE_UNRESOLVED_CFG_RELATIVE_PATHS "Unresolved configuration relative paths" setting type.
static java.lang.String	VALUE_GLOBAL_DEFAULT
static java.lang.String	VALUE_HOST
static java.lang.String	VALUE_NONE
static java.lang.String	VALUE_OBJECTWRAPPER_SHARED_BEANS_WRAPPER
static java.lang.String	VALUE_OUTPUT
static java.lang.String	VALUE_REALLY_QUIET
static java.lang.String	VALUE_SOURCE
static java.lang.String	VALUE_TAG_SYNTAX_ANGLE_BRACKET
static java.lang.String	VALUE_TAG_SYNTAX_AUTO_DETECT
static java.lang.String	VALUE_TAG_SYNTAX_SQUARE_BRACKET
static java.lang.String	VALUE_XML_CATALOG_PREFER_PUBLIC
static java.lang.String	VALUE_XML_CATALOG_PREFER_SYSTEM

Constructor Summary

Settings(java.io.File baseDir)
Creates a new instance.

Method Summary

void	add(java.util.Map settingMap) Adds all name-value pairs stored in the map with add(String, Object).
void	add(java.lang.String name, java.lang.Object value) Adds a setting value.
void	addDefault(java.lang.String name, java.lang.Object value) Adds a setting value with low priority.
void	addDefaults(java.util.Map settingMap) Adds all entries stored in the map with addDefault(String, Object).
void	addDefaultsWithStrings(java.util.Properties props) Same as addDefaults(Map), but uses a Properties object, so the values are strings.
void	addDefaultWithString(java.lang.String name, java.lang.String value) Same as addDefault(String, Object), but uses string value.
void	addProgressListener(ProgressListener pl) Adds a progress listener.
void	addWithString(java.lang.String name, java.lang.String value) Same as add(String, Object), but uses string value.
void	addWithStrings(java.util.Properties props) Same as add(Map), but uses a Properties object, so the values are strings.
void	clearAttribues() Removes all engine attributes.
void	clearProgressListeners() Removes all progress listeneres.
void	define(java.lang.String name, fmpp.setting.Settings.SettingType type, boolean merge, boolean forceStr) Defines a new setting.
protected void	doProcessing(Engine eng, java.io.File[] sources, java.io.File sourceFile, java.io.File outputFile) Executes the processing session(s) on the Engine level, using the already initialized Engine object.
java.lang.String	dump() Dumps the current content of this object for debugging purposes.
void	execute() Executes a processing session based on the setting values.
void	execute(Engine eng) Deprecated. This method will be soon removed; use execute() instead. Reusing the same engine object for multiple execute(...) calls is error-prone (because engine parameters set for earlier setting values may remain in effect, which is seldom useful, and surprising for most users). Also, this method is not compatible with new methods as addProgressListener(fmpp.ProgressListener), setEngineAttribute(String, Object), doProcessing(fmpp.Engine, java.io.File[], java.io.File, java.io.File), ...etc.
static void	fixVersion08SettingNames(java.util.Properties props) Backward compatibility hack: renames properties that use pre-FMPP 0.9.0 names of settings.
java.lang.Object	get(java.lang.String name) Gets the current value of a setting.
static java.lang.String	getDashedName(java.lang.String name) Converts mixed-case setting name to dashed form, as sourceRoot to source-root.
static java.io.File	getDefaultConfigurationFile(java.io.File dir) Returns the default configuration file in the directory.
java.lang.Object	getEngineAttribute(java.lang.String name) Reads an engine attribute.
java.util.Iterator	getNames() Lists the names of settings that were set.
static java.util.Iterator	getStandardSettingNames() Returns if the given name is the name of a standard setting.
boolean	isDefined(java.lang.String name) Returns if a setting with the given name is defined (do not mix it up with being set).
void	load(java.io.File cfgFile) Loads settings from a configuration file.
void	loadDefaults(java.io.File cfgFile) Same as load, except that it adds the settings with addDefaults(Map).
static int	quietSettingValueToInt(java.lang.String value, java.lang.String name) Returns 0 for verbose mode, 1 for quiet mode, 2 for really-quiet mode.
java.lang.Object	remove(java.lang.String name) Removes a setting value.
java.lang.Object	removeAttribute(java.lang.String name) Removes an engine attribute.
void	set(java.util.Map settingMap) Sets all name-value pairs stored in the map with set(String, Object).
void	set(java.lang.String name, boolean value) Convenience method for setting a Boolean value.
void	set(java.lang.String name, int value) Convenience method for setting an Integer value.
void	set(java.lang.String name, java.lang.Object value) Sets the value of a setting.
void	setDefault(java.lang.String name, boolean value) Convenience method for setting a Boolean value.
void	setDefault(java.lang.String name, int value) Convenience method for setting an Integer value.
void	setDefault(java.lang.String name, java.lang.Object value) Sets the value of a setting if the value doesn't exists yet.
void	setDefaults(java.util.Map settingMap) Sets all name-value pairs stored in the map with setDefault(String, Object).
void	setDefaultsWithStrings(java.util.Properties props) Same as setDefaults(Map), but uses a Properties object, so the values are strings.
void	setDefaultWithString(java.lang.String name, java.lang.String value) Same as setDefault(String, Object), but uses string value.
java.lang.Object	setEngineAttribute(java.lang.String name, java.lang.Object value) Sets an engine attribute.
void	setWithString(java.lang.String name, java.lang.String value) Same as set(String, Object), but uses string value.
void	setWithStrings(java.util.Properties props) Same as set(Map), but uses a Properties object, so the values are strings.
void	trimValues(java.util.Properties props) Trims all property values.
void	undashNames(java.util.Properties props) Convers legacy dashed setting names to the standard format, as source-root to sourceRoot.

Methods inherited from class java.lang.Object

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

Field Detail

NAME_SKIP_UNCHANGED

public static final java.lang.String NAME_SKIP_UNCHANGED

See Also:

Constant Field Values

NAME_TURNS

public static final java.lang.String NAME_TURNS

See Also:

Constant Field Values

NAME_SOURCES

public static final java.lang.String NAME_SOURCES

See Also:

Constant Field Values

NAME_SOURCE_ROOT

public static final java.lang.String NAME_SOURCE_ROOT

See Also:

Constant Field Values

NAME_OUTPUT_ROOT

public static final java.lang.String NAME_OUTPUT_ROOT

See Also:

Constant Field Values

NAME_OUTPUT_FILE

public static final java.lang.String NAME_OUTPUT_FILE

See Also:

Constant Field Values

NAME_DATA_ROOT

public static final java.lang.String NAME_DATA_ROOT

See Also:

Constant Field Values

NAME_OBJECT_WRAPPER

public static final java.lang.String NAME_OBJECT_WRAPPER

See Also:

Constant Field Values

NAME_FREEMARKER_LINKS

public static final java.lang.String NAME_FREEMARKER_LINKS

See Also:

Constant Field Values

NAME_INHERIT_CONFIGURATION

public static final java.lang.String NAME_INHERIT_CONFIGURATION

See Also:

Constant Field Values

NAME_MODES

public static final java.lang.String NAME_MODES

See Also:

Constant Field Values

NAME_BORDERS

public static final java.lang.String NAME_BORDERS

See Also:

Constant Field Values

NAME_DATA

public static final java.lang.String NAME_DATA

See Also:

Constant Field Values

NAME_LOCAL_DATA

public static final java.lang.String NAME_LOCAL_DATA

See Also:

Constant Field Values

NAME_TEMPLATE_DATA

public static final java.lang.String NAME_TEMPLATE_DATA

See Also:

Constant Field Values

NAME_SOURCE_ENCODING

public static final java.lang.String NAME_SOURCE_ENCODING

See Also:

Constant Field Values

NAME_OUTPUT_ENCODING

public static final java.lang.String NAME_OUTPUT_ENCODING

See Also:

Constant Field Values

NAME_URL_ESCAPING_CHARSET

public static final java.lang.String NAME_URL_ESCAPING_CHARSET

See Also:

Constant Field Values

NAME_LOCALE

public static final java.lang.String NAME_LOCALE

See Also:

Constant Field Values

NAME_NUMBER_FORMAT

public static final java.lang.String NAME_NUMBER_FORMAT

See Also:

Constant Field Values

NAME_DATE_FORMAT

public static final java.lang.String NAME_DATE_FORMAT

See Also:

Constant Field Values

NAME_TIME_FORMAT

public static final java.lang.String NAME_TIME_FORMAT

See Also:

Constant Field Values

NAME_DATETIME_FORMAT

public static final java.lang.String NAME_DATETIME_FORMAT

See Also:

Constant Field Values

NAME_TIME_ZONE

public static final java.lang.String NAME_TIME_ZONE

See Also:

Constant Field Values

NAME_TAG_SYNTAX

public static final java.lang.String NAME_TAG_SYNTAX

See Also:

Constant Field Values

NAME_CASE_SENSITIVE

public static final java.lang.String NAME_CASE_SENSITIVE

See Also:

Constant Field Values

NAME_STOP_ON_ERROR

public static final java.lang.String NAME_STOP_ON_ERROR

See Also:

Constant Field Values

NAME_REMOVE_EXTENSIONS

public static final java.lang.String NAME_REMOVE_EXTENSIONS

See Also:

Constant Field Values

OLD_NAME_REMOVE_EXTENSION

public static final java.lang.String OLD_NAME_REMOVE_EXTENSION

See Also:

Constant Field Values

NAME_REMOVE_POSTFIXES

public static final java.lang.String NAME_REMOVE_POSTFIXES

See Also:

Constant Field Values

OLD_NAME_REMOVE_POSTFIX

public static final java.lang.String OLD_NAME_REMOVE_POSTFIX

See Also:

Constant Field Values

NAME_REPLACE_EXTENSIONS

public static final java.lang.String NAME_REPLACE_EXTENSIONS

See Also:

Constant Field Values

OLD_NAME_REPLACE_EXTENSION

public static final java.lang.String OLD_NAME_REPLACE_EXTENSION

See Also:

Constant Field Values

NAME_IGNORE_CVS_FILES

public static final java.lang.String NAME_IGNORE_CVS_FILES

See Also:

Constant Field Values

NAME_IGNORE_SVN_FILES

public static final java.lang.String NAME_IGNORE_SVN_FILES

See Also:

Constant Field Values

NAME_IGNORE_TEMPORARY_FILES

public static final java.lang.String NAME_IGNORE_TEMPORARY_FILES

See Also:

Constant Field Values

NAME_EXPERT

public static final java.lang.String NAME_EXPERT

See Also:

Constant Field Values

NAME_LOG_FILE

public static final java.lang.String NAME_LOG_FILE

See Also:

Constant Field Values

NAME_APPEND_LOG_FILE

public static final java.lang.String NAME_APPEND_LOG_FILE

See Also:

Constant Field Values

NAME_CONFIGURATION_BASE

public static final java.lang.String NAME_CONFIGURATION_BASE

See Also:

Constant Field Values

NAME_ECHO_FORMAT

public static final java.lang.String NAME_ECHO_FORMAT

See Also:

Constant Field Values

NAME_QUIET

public static final java.lang.String NAME_QUIET

See Also:

Constant Field Values

NAME_COLUMNS

public static final java.lang.String NAME_COLUMNS

See Also:

Constant Field Values

NAME_SNIP

public static final java.lang.String NAME_SNIP

See Also:

Constant Field Values

NAME_XPATH_ENGINE

public static final java.lang.String NAME_XPATH_ENGINE

See Also:

Constant Field Values

NAME_XML_CATALOG_FILES

public static final java.lang.String NAME_XML_CATALOG_FILES

See Also:

Constant Field Values

NAME_XML_CATALOG_PREFER

public static final java.lang.String NAME_XML_CATALOG_PREFER

See Also:

Constant Field Values

NAME_VALIDATE_XML

public static final java.lang.String NAME_VALIDATE_XML

See Also:

Constant Field Values

NAME_XML_RENDERINGS

public static final java.lang.String NAME_XML_RENDERINGS

See Also:

Constant Field Values

VALUE_SOURCE

public static final java.lang.String VALUE_SOURCE

See Also:

Constant Field Values

VALUE_HOST

public static final java.lang.String VALUE_HOST

See Also:

Constant Field Values

VALUE_OUTPUT

public static final java.lang.String VALUE_OUTPUT

See Also:

Constant Field Values

VALUE_OBJECTWRAPPER_SHARED_BEANS_WRAPPER

public static final java.lang.String VALUE_OBJECTWRAPPER_SHARED_BEANS_WRAPPER

See Also:

Constant Field Values

VALUE_TAG_SYNTAX_ANGLE_BRACKET

public static final java.lang.String VALUE_TAG_SYNTAX_ANGLE_BRACKET

See Also:

Constant Field Values

VALUE_TAG_SYNTAX_SQUARE_BRACKET

public static final java.lang.String VALUE_TAG_SYNTAX_SQUARE_BRACKET

See Also:

Constant Field Values

VALUE_TAG_SYNTAX_AUTO_DETECT

public static final java.lang.String VALUE_TAG_SYNTAX_AUTO_DETECT

See Also:

Constant Field Values

VALUE_NONE

public static final java.lang.String VALUE_NONE

See Also:

Constant Field Values

VALUE_REALLY_QUIET

public static final java.lang.String VALUE_REALLY_QUIET

See Also:

Constant Field Values

VALUE_XML_CATALOG_PREFER_PUBLIC

public static final java.lang.String VALUE_XML_CATALOG_PREFER_PUBLIC

See Also:

Constant Field Values

VALUE_XML_CATALOG_PREFER_SYSTEM

public static final java.lang.String VALUE_XML_CATALOG_PREFER_SYSTEM

See Also:

Constant Field Values

VALUE_GLOBAL_DEFAULT

public static final java.lang.String VALUE_GLOBAL_DEFAULT

See Also:

Constant Field Values

DEFAULT_CFG_FILE_NAME

public static final java.lang.String DEFAULT_CFG_FILE_NAME

Primary default file name.

See Also:

Constant Field Values

DEFAULT_CFG_FILE_NAME_OLD

public static final java.lang.String DEFAULT_CFG_FILE_NAME_OLD

Secondary (legacy) default file name.

See Also:

Constant Field Values

TYPE_ANY

public static final fmpp.setting.Settings.SettingType TYPE_ANY

Any object.

Input type: Object.

Output type: Object.

String input: any value, stored as is.

Merging: not supported.

TYPE_STRING

public static final fmpp.setting.Settings.SettingType TYPE_STRING

String setting type.

Input type: String, Number, Boolean. The last two is converted to string with toString()

Output type: String.

String input: any value, stored as is.

Merging: not supported

TYPE_INTEGER

public static final fmpp.setting.Settings.SettingType TYPE_INTEGER

Integer setting type.

Input type: Number that can be converted to Integer without lost.

Output type: Integer.

String input: any value, that can be parsed to Integer by Integer.parseInt after trimming. In additional, redundant + sign is supported.

Merging: not supported

TYPE_BOOLEAN

public static final fmpp.setting.Settings.SettingType TYPE_BOOLEAN

Boolean setting type.

Input type: Boolean.

Output type: Boolean.

String input: After trimming and converting to lower-case, "true", "false" or empty string are allowed. Empty string is interpreted as true (consider a properties file that contains a key without value).

Merging: not supported

TYPE_SEQUENCE

public static final fmpp.setting.Settings.SettingType TYPE_SEQUENCE

Sequence setting type.

Input type: List, any array, Vector. No restriction regarding the type of the list items.

Output type: List. No restriction regarding the type of the list items.

String input: TDD expression starting in list mode. If the result is a list that contains a single list, then the contained list will be used. This heuristic is used to fix this user mistake:
--some-list="[a, b, c]"
instead of:
--some-list="a, b, c"

Merging: the two lists are concatenated, with the default (inherited) value coming last.

TYPE_LOCAL_DATA_MODEL

public static final fmpp.setting.Settings.SettingType TYPE_LOCAL_DATA_MODEL

Local data model setting type. This is the same as TYPE_SEQUENCE, just if the value is given as text (string input), it defers the evaluation of the hash parameter of the case function call, and stores that as Fragment. This is required because that hash parameter may uses data loaders, which shouldn't be executed until almost all settings of the Engine are set. This also means that if you set the setting value with Java, the last parameter to the case FunctionCall must be a Fragment instead of Map, if you want to use data loaders in it.

TYPE_HASH

public static final fmpp.setting.Settings.SettingType TYPE_HASH

Hash setting type.

Input type: Map, Dictionary.

Output type: Map.

String input: TDD expression, starting in hash mode.

Merging: the two maps are added (union)

TYPE_CFG_RELATIVE_PATH

public static final fmpp.setting.Settings.SettingType TYPE_CFG_RELATIVE_PATH

"Configuration relative path" setting type.

Input type: String, FileWithSettingValue. Plain File is not allowed.

Output type: FileWithSettingValue.

String input: Any value, trimmed before converting.

Merging: not supported

TYPE_CFG_RELATIVE_PATHS

public static final fmpp.setting.Settings.SettingType TYPE_CFG_RELATIVE_PATHS

"Configuration relative paths" setting type.

Input type: Same as for TYPE_SEQUENCE, but all list items must be string or FileWithSettingValue.

Output type: Same as for TYPE_SEQUENCE, but all list items are FileWithSettingValue-s.

String input: Same as for TYPE_SEQUENCE, but all sequence items must be strings. "force strings" option is on during the TDD interpretation.

Merging: the two list are concatenated.

TYPE_UNRESOLVED_CFG_RELATIVE_PATHS

public static final fmpp.setting.Settings.SettingType TYPE_UNRESOLVED_CFG_RELATIVE_PATHS

"Unresolved configuration relative paths" setting type.

Input type: Same as for TYPE_SEQUENCE, but all list items must be string or FileWithConfigurationBase.

Output type: Same as for TYPE_SEQUENCE, but all list items are FileWithConfigurationBase-s.

String input: Same as for TYPE_SEQUENCE, but all sequence items must be strings. "force strings" option is on during the TDD interpretation.

Merging: the two list are concatenated.

TYPE_DATA_MODEL

public static final fmpp.setting.Settings.SettingType TYPE_DATA_MODEL

Data model setting type.

Input type: Map, Dictionary, Fragment, private class DataList.

Output type: private class DataList extends ArrayList. The list may contains: Map, String, Fragment.

String input: TDD expression, starting in hash mode.

Merging: The tow lists are concatenated.

This type is used for the "data" setting. The hash value of that setting can't be generated until the final value of all other setting is set (because data loaders may use the other settings). This way, the value of the "data" setting is a List that records the changes made on the setting, and not a Map. The Map will be built internally based on the list when you call execute().

TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS

public static final fmpp.setting.Settings.SettingType TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS

Hash-of-configuration-relative-paths setting type.

Input type: Map or Dictionary, that stores a List or Vector or array, that stores strings and/or FileWithSettingValue-s. Also, the map may contains strings and/or FileWithSettingValue directly as value (instead of a list of length 1 that stores the same value).

Output type: Map of List of FileWithSettingValue-s.

String input: TDD expression, starting in hash mode.

Merging: the two maps are added (union)

Constructor Detail

Settings

public Settings(java.io.File baseDir)
         throws SettingException

Creates a new instance. The standard settings will be already defined in the new instance.

Parameters:

baseDir - the base directory used to resolve relative paths in setting names. When you load settings from a configuration file, the parent directory of the file will be used instenad, for the settings coming from the file.

Throws:

SettingException

Method Detail

define

public void define(java.lang.String name,
                   fmpp.setting.Settings.SettingType type,
                   boolean merge,
                   boolean forceStr)
            throws SettingException

Defines a new setting. No setting with the same name already exists.

Parameters:

name - the name of the setting

type - the type of the setting

merge - specifies if when you add a new setting value, and the setting has already set, then the new and old value will be merged, or the new value will replace old value. Note that only a few setting type supports merging, such as list and map.

forceStr - specifies if when parsing string values with TDD interpreter, it should be done with the "force strings" option or not.

Throws:

SettingException

isDefined

public boolean isDefined(java.lang.String name)

Returns if a setting with the given name is defined (do not mix it up with being set).

See Also:

define(java.lang.String, fmpp.setting.Settings.SettingType, boolean, boolean)

getStandardSettingNames

public static java.util.Iterator getStandardSettingNames()

Returns if the given name is the name of a standard setting.

add

public void add(java.lang.String name,
                java.lang.Object value)
         throws SettingException

Adds a setting value. If a setting value already exists, it will be either replaced or merged with the new value, depending on the definition of the setting. When merging, the new value has higher priorty than the old value.

Throws:

SettingException

addDefault

public void addDefault(java.lang.String name,
                       java.lang.Object value)
                throws SettingException

Adds a setting value with low priority. If a setting value already exists, it will be either kept (and thus the method call has no effect) or merged with the new value, depending on the definition of the setting. When merging, the new value has lower priorty than the old value.

Throws:

SettingException

addWithString

public void addWithString(java.lang.String name,
                          java.lang.String value)
                   throws SettingException

Same as add(String, Object), but uses string value.

Throws:

SettingException

addDefaultWithString

public void addDefaultWithString(java.lang.String name,
                                 java.lang.String value)
                          throws SettingException

Same as addDefault(String, Object), but uses string value.

Throws:

SettingException

add

public void add(java.util.Map settingMap)
         throws SettingException

Adds all name-value pairs stored in the map with add(String, Object).

Throws:

SettingException

addDefaults

public void addDefaults(java.util.Map settingMap)
                 throws SettingException

Adds all entries stored in the map with addDefault(String, Object).

Throws:

SettingException

addWithStrings

public void addWithStrings(java.util.Properties props)
                    throws SettingException

Same as add(Map), but uses a Properties object, so the values are strings.

Throws:

SettingException

addDefaultsWithStrings

public void addDefaultsWithStrings(java.util.Properties props)
                            throws SettingException

Same as addDefaults(Map), but uses a Properties object, so the values are strings.

Throws:

SettingException

set

public void set(java.lang.String name,
                java.lang.Object value)
         throws SettingException

Sets the value of a setting. If the setting value already exists, it will be replaced (never merged).

Throws:

SettingException

set

public void set(java.lang.String name,
                boolean value)
         throws SettingException

Convenience method for setting a Boolean value.

Throws:

SettingException

set

public void set(java.lang.String name,
                int value)
         throws SettingException

Convenience method for setting an Integer value.

Throws:

SettingException

setDefault

public void setDefault(java.lang.String name,
                       java.lang.Object value)
                throws SettingException

Sets the value of a setting if the value doesn't exists yet.

Throws:

SettingException

setDefault

public void setDefault(java.lang.String name,
                       boolean value)
                throws SettingException

Convenience method for setting a Boolean value.

Throws:

SettingException

setDefault

public void setDefault(java.lang.String name,
                       int value)
                throws SettingException

Convenience method for setting an Integer value.

Throws:

SettingException

setWithString

public void setWithString(java.lang.String name,
                          java.lang.String value)
                   throws SettingException

Same as set(String, Object), but uses string value.

Throws:

SettingException

setDefaultWithString

public void setDefaultWithString(java.lang.String name,
                                 java.lang.String value)
                          throws SettingException

Same as setDefault(String, Object), but uses string value.

Throws:

SettingException

set

public void set(java.util.Map settingMap)
         throws SettingException

Sets all name-value pairs stored in the map with set(String, Object).

Throws:

SettingException

setDefaults

public void setDefaults(java.util.Map settingMap)
                 throws SettingException

Sets all name-value pairs stored in the map with setDefault(String, Object).

Throws:

SettingException

setWithStrings

public void setWithStrings(java.util.Properties props)
                    throws SettingException

Same as set(Map), but uses a Properties object, so the values are strings.

Throws:

SettingException

setDefaultsWithStrings

public void setDefaultsWithStrings(java.util.Properties props)
                            throws SettingException

Same as setDefaults(Map), but uses a Properties object, so the values are strings.

Throws:

SettingException

load

public void load(java.io.File cfgFile)
          throws SettingException

Loads settings from a configuration file. The file will be interpreted as legacy properties file if its extension is cfg or properties, otherwise it will be interpreted as TDD file. The settings stored in the configuration file will be added to the this object with add(Map).

Note that meta-settings ("configurationBase" and "inheritConfiguration") will not be added to the settings object.

If the setting "configurationBase" or "inheritConfiguration" is set in this setting object, then they will override the meta-settings in the file directly loaded with this method. Files inherited by the directly loaded file, however, are not affected.

Parameters:

cfgFile - the configuration file, or the directory of the configuration file if its file name is one of the default configuration file names.

Throws:

SettingException

See Also:

loadDefaults(File)

loadDefaults

public void loadDefaults(java.io.File cfgFile)
                  throws SettingException

Same as load, except that it adds the settings with addDefaults(Map).

Throws:

SettingException

See Also:

load(File)

get

public java.lang.Object get(java.lang.String name)

Gets the current value of a setting.

Parameters:

name - the name of the setting.

Returns:

The value of the setting, or null if the setting is not set. Do not modify the returned object!

remove

public java.lang.Object remove(java.lang.String name)

Removes a setting value.

Returns:

the removed value, or null if there was no value stored for the setting.

getNames

public java.util.Iterator getNames()

Lists the names of settings that were set.

execute

public void execute()
             throws SettingException,
                    ProcessingException

Executes a processing session based on the setting values. For each call of this method, a new Engine object will be internaly created, and initialized based on the setting values, and then its process method will be called. The method automatically chooses between bulk and single-file processing, based on the presence of the "outputFile" setting.

Settings will go throught semantical checks that are not done when you call other methods. For example, it will be checked if setting "modes" contains valid mode setter function calls, if "sourceRoot" and "outputRoot" are defined for bulk mode, if exactly 1 "sources" is defined for single-file mode, etc.

This method ignores the following settings: "logFile", "appendLogFile", "echoFormat", "quiet", "snip". It's the task of the embedding software (the front-end) to interpret these settings, at least the ones it is interested in. It usually involves adding progress listeners with addProgressListener(ProgressListener).

This method can be called for multiple times, but be aware of that for each call of this method, a new Engine object will be created and initialized, even if you didn't changed the settings since the last call. If this overhead is not acceptable in you case, you can call Engine.process(...) for multiple times within the same execute() call, by overriding the doProcessing(Engine, File[], File, File) method. Also, you can do extra engine initalization there.

Throws:

SettingException - if the settings are not correct, or can't be applied because of some errors occured. This exception, when thrown, is always thrown before the execution of the processing session is stated.

ProcessingException - if Engine.process has thrown any exception, that is, there was an error during the execution of the processing session. 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.

execute

public void execute(Engine eng)
             throws SettingException,
                    ProcessingException

Deprecated. This method will be soon removed; use execute() instead. Reusing the same engine object for multiple execute(...) calls is error-prone (because engine parameters set for earlier setting values may remain in effect, which is seldom useful, and surprising for most users). Also, this method is not compatible with new methods as addProgressListener(fmpp.ProgressListener), setEngineAttribute(String, Object), doProcessing(fmpp.Engine, java.io.File[], java.io.File, java.io.File), ...etc.

Executes a processing session using the setting values and the engine object passed in. The Engine object is not configured regarding the settings that are not specified in this object. Thus, if you don't use clean (new) Engine object, it may brings some unwanted defaults.

Parameters:

eng - the FMPP engine used for the execution. As the settings of the engine will be changed (even if SettingException was thrown!), you should use a new (clean) instance for each invocatons, and don't reuse the old object.

Throws:

SettingException

ProcessingException

See Also:

execute()

addProgressListener

public void addProgressListener(ProgressListener pl)

Adds a progress listener. The progress listener will be added to the internally used Engine object when you call execute().

See Also:

clearProgressListeners()

clearProgressListeners

public void clearProgressListeners()

Removes all progress listeneres.

Warning! Don't use this method together with the deprecated execute(Engine) method!

See Also:

addProgressListener(ProgressListener)

setEngineAttribute

public java.lang.Object setEngineAttribute(java.lang.String name,
                                           java.lang.Object value)

Sets an engine attribute. The attribute will be set in the internally used Engine object when you call execute().

Warning! Don't use this method together with the deprecated execute(Engine) method!

Returns:

The previous value of the attribute, or null if there was no attribute with the given name.

getEngineAttribute

public java.lang.Object getEngineAttribute(java.lang.String name)

Reads an engine attribute.

Warning! Don't use this method together with the deprecated execute(Engine) method!

Returns:

null if no attribute exists with the given name.

See Also:

setEngineAttribute(String, Object)

removeAttribute

public java.lang.Object removeAttribute(java.lang.String name)

Removes an engine attribute. It does nothing if the attribute does not exist.

Warning! Don't use this method together with the deprecated execute(Engine) method!

Returns:

The value of the removed attribute or null if there was no attribute with the given name.

See Also:

setEngineAttribute(String, Object)

clearAttribues

public void clearAttribues()

Removes all engine attributes.

See Also:

Warning! Don't use this method together with the deprecated {@link #execute(Engine)} method!

dump

public java.lang.String dump()

Dumps the current content of this object for debugging purposes.

Warning! Don't use this method together with the deprecated execute(Engine) method!

quietSettingValueToInt

public static int quietSettingValueToInt(java.lang.String value,
                                         java.lang.String name)
                                  throws SettingException

Returns 0 for verbose mode, 1 for quiet mode, 2 for really-quiet mode.

Throws:

SettingException

getDefaultConfigurationFile

public static java.io.File getDefaultConfigurationFile(java.io.File dir)

Returns the default configuration file in the directory.

Returns:

the absolute file, or null if no default configuration file exists in the directory.

undashNames

public void undashNames(java.util.Properties props)
                 throws SettingException

Convers legacy dashed setting names to the standard format, as source-root to sourceRoot.

Parameters:

props - the Properties object to convert.

Throws:

SettingException - if no setting with the given name exists.

trimValues

public void trimValues(java.util.Properties props)

Trims all property values.

doProcessing

protected void doProcessing(Engine eng,
                            java.io.File[] sources,
                            java.io.File sourceFile,
                            java.io.File outputFile)
                     throws SettingException,
                            ProcessingException

Executes the processing session(s) on the Engine level, using the already initialized Engine object.

By overriding this method, you can

• call Engine.process(...) for multiple times, so you can do multiple processing sessions with the same already initialized Engine object.
• do extra Engine initialization.

The inital implementation of this method (that is, the implementation in the Settings class) is something like this:

 if (outputFile == null) {
     eng.process(sources);
 } else {
     eng.process(sourceFile, outputFile);
 }

Warning! Don't override this method if you use the deprecated execute(Engine) method!

Modifying the Settings object in this method has no effect on the Engine object (which is passed in as argument), since all settings are already applied on it. If you need to modify the Engine object, call its methods directly.

An implementation of this method may leak out the initialized Engine object for the caller of execute(). Also, it may does not call Engine.proccess(...), but left it for the caller (who has the out-leaked Engine object). These are extreme, but otherwise legitimate usages.

Parameters:

eng - the already initialized Engine object. You may do extra addjustments on it.

sources - the list of source files, the parameter to Engine.process(File[]). It's null if the processing session uses outputFile setting.

sourceFile - if the session uses outputFile setting, then it' the 1st parameter to Engine.process(File, File), otherwise it is null.

outputFile - if the session uses outputFile setting, then it' the 2nd parameter to Engine.process(File, File), otherwise it is null.

Throws:

SettingException

ProcessingException

getDashedName

public static java.lang.String getDashedName(java.lang.String name)

Converts mixed-case setting name to dashed form, as sourceRoot to source-root.

fixVersion08SettingNames

public static void fixVersion08SettingNames(java.util.Properties props)
                                     throws SettingException

Backward compatibility hack: renames properties that use pre-FMPP 0.9.0 names of settings.

Throws:

SettingException