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 ofObject
(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 theSettings
object. For example, withadd(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()
. - All settings you want to set/get must be defined. See
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
Settings.SettingType
Represents the type of the value of a setting.
-
Field Summary
Fields Modifier and Type Field Description 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_ALWAYS_CREATE_DIRECTORIES
static java.lang.String
NAME_APPEND_LOG_FILE
static java.lang.String
NAME_BOOLEAN_FORMAT
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_INCOMPATIBLE_IMPROVEMENTS
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_INTERPOLATION_SYNTAX
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_MAP_COMMON_EXTENSIONS_TO_OUTPUT_FORMATS
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_FORMAT
static java.lang.String
NAME_OUTPUT_FORMATS_BY_PATH
static java.lang.String
NAME_OUTPUT_ROOT
static java.lang.String
NAME_PRINT_STACK_TRACE
static java.lang.String
NAME_QUIET
static java.lang.String
NAME_RECOMMENDED_DEFAULTS
static java.lang.String
NAME_REMOVE_EXTENSIONS
static java.lang.String
NAME_REMOVE_FREEMARKER_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_SQL_DATE_AND_TIME_TIME_ZONE
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 Settings.SettingType
TYPE_ANY
Any object.static Settings.SettingType
TYPE_BOOLEAN
Boolean setting type.static Settings.SettingType
TYPE_CFG_RELATIVE_PATH
"Configuration relative path" setting type.static Settings.SettingType
TYPE_CFG_RELATIVE_PATHS
"Configuration relative paths" setting type.static Settings.SettingType
TYPE_DATA_MODEL
Data model setting type.static Settings.SettingType
TYPE_HASH
Hash setting type.static Settings.SettingType
TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS
Hash-of-configuration-relative-paths setting type.static Settings.SettingType
TYPE_INTEGER
Integer setting type.static Settings.SettingType
TYPE_LOCAL_DATA_MODEL
Local data model setting type.static Settings.SettingType
TYPE_SEQUENCE
Sequence setting type.static Settings.SettingType
TYPE_STRING
String setting type.static 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_INTERPOLATION_SYNTAX_DOLLAR
static java.lang.String
VALUE_INTERPOLATION_SYNTAX_LEGACY
static java.lang.String
VALUE_INTERPOLATION_SYNTAX_SQUARE_BRACKET
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
Constructors Constructor Description Settings(java.io.File baseDir)
Creates a new instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
add(java.lang.String name, java.lang.Object value)
Adds a setting value.void
add(java.util.Map settingMap)
Adds all name-value pairs stored in the map withadd(String, Object)
.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 withaddDefault(String, Object)
.void
addDefaultsWithStrings(java.util.Properties props)
Same asaddDefaults(Map)
, but uses aProperties
object, so the values are strings.void
addDefaultWithString(java.lang.String name, java.lang.String value)
Same asaddDefault(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 asadd(String, Object)
, but uses string value that will be interpreted bySettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
.void
addWithStrings(java.util.Properties props)
Same asadd(Map)
, but uses aProperties
object, so the values are strings.void
clearAttribues()
Removes all engine attributes.void
clearProgressListeners()
Removes all progress listeneres.void
define(java.lang.String name, 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 theEngine
level, using the already initializedEngine
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.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, like sourceRoot to source-root.static java.io.File
getDefaultConfigurationFile(java.io.File dir)
Returns the default configuration file in the directory.boolean
getDontTraverseDirectories()
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 names of the standard (not user-defined) settings.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 asload
, except that it adds the settings withaddDefaults(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; after thisget(String)
will returnnull
.java.lang.Object
removeAttribute(java.lang.String name)
Removes an engine attribute.void
set(java.lang.String name, boolean value)
Convenience method for setting aBoolean
value.void
set(java.lang.String name, int value)
Convenience method for setting anInteger
value.void
set(java.lang.String name, java.lang.Object value)
Sets the value of a setting.void
set(java.util.Map settingValues)
Callsset(String, Object)
for each name-value pair of theMap
.void
setDefault(java.lang.String name, boolean value)
Convenience method for setting aBoolean
value; seesetDefault(String, Object)
.void
setDefault(java.lang.String name, int value)
Convenience method for setting anInteger
value; seesetDefault(String, Object)
.void
setDefault(java.lang.String name, java.lang.Object value)
Sets the value of a setting if the value wasn't set yet.void
setDefaults(java.util.Map settingValues)
void
setDefaultsWithStrings(java.util.Properties props)
Similar tosetWithStrings(Properties)
, but callssetDefaultWithString(String, String)
instead ofsetWithString(String, String)
.void
setDefaultWithString(java.lang.String name, java.lang.String value)
Same assetDefault(String, Object)
, but uses a string value that will be parsed withSettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
.void
setDontTraverseDirectories(boolean dontTraverseDirs)
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 asset(String, Object)
, but uses string value that will be parsed withSettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
.void
setWithStrings(java.util.Properties props)
CallssetWithString(String, String)
for each name-value pair of theProperties
.void
trimValues(java.util.Properties props)
Trims all property values.void
undashNames(java.util.Properties props)
Converts legacy dashed setting names to the standard format, assource-root
tosourceRoot
.
-
-
-
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_RECOMMENDED_DEFAULTS
public static final java.lang.String NAME_RECOMMENDED_DEFAULTS
- See Also:
- Constant Field Values
-
NAME_FREEMARKER_INCOMPATIBLE_IMPROVEMENTS
public static final java.lang.String NAME_FREEMARKER_INCOMPATIBLE_IMPROVEMENTS
- 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_BOOLEAN_FORMAT
public static final java.lang.String NAME_BOOLEAN_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_SQL_DATE_AND_TIME_TIME_ZONE
public static final java.lang.String NAME_SQL_DATE_AND_TIME_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_INTERPOLATION_SYNTAX
public static final java.lang.String NAME_INTERPOLATION_SYNTAX
- See Also:
- Constant Field Values
-
NAME_OUTPUT_FORMAT
public static final java.lang.String NAME_OUTPUT_FORMAT
- See Also:
- Constant Field Values
-
NAME_OUTPUT_FORMATS_BY_PATH
public static final java.lang.String NAME_OUTPUT_FORMATS_BY_PATH
- See Also:
- Constant Field Values
-
NAME_MAP_COMMON_EXTENSIONS_TO_OUTPUT_FORMATS
public static final java.lang.String NAME_MAP_COMMON_EXTENSIONS_TO_OUTPUT_FORMATS
- 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_REMOVE_FREEMARKER_EXTENSIONS
public static final java.lang.String NAME_REMOVE_FREEMARKER_EXTENSIONS
- See Also:
- Constant Field Values
-
NAME_ALWAYS_CREATE_DIRECTORIES
public static final java.lang.String NAME_ALWAYS_CREATE_DIRECTORIES
- 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_PRINT_STACK_TRACE
public static final java.lang.String NAME_PRINT_STACK_TRACE
- 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_INTERPOLATION_SYNTAX_LEGACY
public static final java.lang.String VALUE_INTERPOLATION_SYNTAX_LEGACY
- See Also:
- Constant Field Values
-
VALUE_INTERPOLATION_SYNTAX_DOLLAR
public static final java.lang.String VALUE_INTERPOLATION_SYNTAX_DOLLAR
- See Also:
- Constant Field Values
-
VALUE_INTERPOLATION_SYNTAX_SQUARE_BRACKET
public static final java.lang.String VALUE_INTERPOLATION_SYNTAX_SQUARE_BRACKET
- 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 Settings.SettingType TYPE_ANY
Any object.Input type:
Object
. Known bug:null
value is allowed (incorrectly), but in effect removes (un-sets) the value.Output type:
Object
.String input: any value, stored as is.
Merging: not supported.
-
TYPE_STRING
public static final Settings.SettingType TYPE_STRING
String setting type.Input type:
String
,Number
,Boolean
. The last two is converted to string withtoString()
Output type:
String
.String input: any value, stored as is.
Merging: not supported
-
TYPE_INTEGER
public static final Settings.SettingType TYPE_INTEGER
Integer setting type.Input type:
Number
that can be converted toInteger
without loss.Output type:
Integer
.String input: any value, that can be parsed to
Integer
byInteger.parseInt
after trimming. In additional, redundant+
sign is supported.Merging: not supported
-
TYPE_BOOLEAN
public static final 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 astrue
(consider a properties file that contains a key without value).Merging: not supported
-
TYPE_SEQUENCE
public static final 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 Settings.SettingType TYPE_LOCAL_DATA_MODEL
Local data model setting type. This is the same asTYPE_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 asFragment
. This is required because that hash parameter may uses data loaders, which shouldn't be executed until almost all settings of theEngine
are set. This also means that if you set the setting value with Java, the last parameter to the caseFunctionCall
must be aFragment
instead ofMap
, if you want to use data loaders in it.
-
TYPE_HASH
public static final 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 Settings.SettingType TYPE_CFG_RELATIVE_PATH
"Configuration relative path" setting type.Input type:
String
,FileWithSettingValue
. PlainFile
is not allowed.Output type:
FileWithSettingValue
.String input: Any value, trimmed before converting.
Merging: not supported
-
TYPE_CFG_RELATIVE_PATHS
public static final 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 orFileWithSettingValue
.Output type: Same as for
TYPE_SEQUENCE
, but all list items areFileWithSettingValue
-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 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 strings orFileWithConfigurationBase
-s.Output type: Same as for
TYPE_SEQUENCE
, but all list items areFileWithConfigurationBase
-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 Settings.SettingType TYPE_DATA_MODEL
Data model setting type.Input type:
Map
,Dictionary
,Fragment
, private classDataList
.Output type: private class
DataList
extendsArrayList
. 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 aMap
. TheMap
will be built internally based on the list when you callexecute()
.
-
TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS
public static final Settings.SettingType TYPE_HASH_OF_SEQUENCE_OF_CFG_RELATIVE_PATHS
Hash-of-configuration-relative-paths setting type.Input type:
Map
orDictionary
, that stores aList
orVector
or array, that stores strings and/orFileWithSettingValue
-s. Also, the map may contains strings and/orFileWithSettingValue
directly as value (instead of a list of length 1 that stores the same value).Output type:
Map
ofList
ofFileWithSettingValue
-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, Settings.SettingType type, boolean merge, boolean forceStr) throws SettingException
Defines a new setting. No setting with the same name can already exists.- Parameters:
name
- the name of the settingtype
- the type of the settingmerge
- 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 types support 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).
-
getStandardSettingNames
public static java.util.Iterator getStandardSettingNames()
Returns names of the standard (not user-defined) settings.
-
add
public void add(java.lang.String name, java.lang.Object value) throws SettingException
Adds a setting value. Adding means that 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 priority than the old value. (With lists, higher priority means being earlier in the list.)- Throws:
SettingException
- See Also:
set(String, Object)
-
addDefault
public void addDefault(java.lang.String name, java.lang.Object value) throws SettingException
Adds a setting value with low priority. Adding means that 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 priority than the old value. (With lists, lower priority means being later in the list.)- Throws:
SettingException
- See Also:
setDefault(String, boolean)
-
addWithString
public void addWithString(java.lang.String name, java.lang.String value) throws SettingException
Same asadd(String, Object)
, but uses string value that will be interpreted bySettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
. Used when the value comes from a strings-only source.- Throws:
SettingException
-
addDefaultWithString
public void addDefaultWithString(java.lang.String name, java.lang.String value) throws SettingException
Same asaddDefault(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 withadd(String, Object)
. Thus, all keys must beString
-s.- Throws:
SettingException
-
addDefaults
public void addDefaults(java.util.Map settingMap) throws SettingException
Adds all entries stored in the map withaddDefault(String, Object)
. Thus, all keys must beString
-s.- Throws:
SettingException
-
addWithStrings
public void addWithStrings(java.util.Properties props) throws SettingException
Same asadd(Map)
, but uses aProperties
object, so the values are strings.- Throws:
SettingException
-
addDefaultsWithStrings
public void addDefaultsWithStrings(java.util.Properties props) throws SettingException
Same asaddDefaults(Map)
, but uses aProperties
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).- Parameters:
name
- The name of the setting. It's validated if a setting with this name is defined, otherwise it throwsSettingException
value
- Notnull
; useremove(String)
to un-set a value. (Known bug: if the type is#TYPE_ANY
,null
will not cause error, and in effect un-set the value.)- Throws:
SettingException
- If the setting name or value is not valid.
-
set
public void set(java.lang.String name, boolean value) throws SettingException
Convenience method for setting aBoolean
value.- Throws:
SettingException
-
set
public void set(java.lang.String name, int value) throws SettingException
Convenience method for setting anInteger
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 wasn't set yet. (The name is misleading, as if the setting value is removed later, it will not get the default value.) Seeset(String, Object)
for the parameters and thrown exception.- Throws:
SettingException
-
setDefault
public void setDefault(java.lang.String name, boolean value) throws SettingException
Convenience method for setting aBoolean
value; seesetDefault(String, Object)
.- Throws:
SettingException
-
setDefault
public void setDefault(java.lang.String name, int value) throws SettingException
Convenience method for setting anInteger
value; seesetDefault(String, Object)
.- Throws:
SettingException
-
setWithString
public void setWithString(java.lang.String name, java.lang.String value) throws SettingException
Same asset(String, Object)
, but uses string value that will be parsed withSettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
. Used when the value comes from a strings-only source.- Throws:
SettingException
-
setDefaultWithString
public void setDefaultWithString(java.lang.String name, java.lang.String value) throws SettingException
Same assetDefault(String, Object)
, but uses a string value that will be parsed withSettings.SettingType.parse(fmpp.setting.Settings, java.lang.String, boolean)
.- Throws:
SettingException
-
set
public void set(java.util.Map settingValues) throws SettingException
Callsset(String, Object)
for each name-value pair of theMap
. The change is atomic; if aSettingException
occurs, no setting values are changed.- Parameters:
settingValues
- Maps setting names (String
-s) to setting values (non-null
Object
-s).- Throws:
SettingException
-
setDefaults
public void setDefaults(java.util.Map settingValues) throws SettingException
- Throws:
SettingException
-
setWithStrings
public void setWithStrings(java.util.Properties props) throws SettingException
CallssetWithString(String, String)
for each name-value pair of theProperties
. The change is atomic; if aSettingException
occurs, no setting values are changed.- Throws:
SettingException
-
setDefaultsWithStrings
public void setDefaultsWithStrings(java.util.Properties props) throws SettingException
Similar tosetWithStrings(Properties)
, but callssetDefaultWithString(String, String)
instead ofsetWithString(String, String)
.- 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 withadd(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 asload
, except that it adds the settings withaddDefaults(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. The name won't be validated.- Returns:
- The value of the setting.
null
if the setting is not set.
-
remove
public java.lang.Object remove(java.lang.String name)
Removes a setting value; after thisget(String)
will returnnull
.- Returns:
- the removed value, or
null
if there was no value stored for the setting. - See Also:
set(String, Object)
-
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 newEngine
object will be internally created, and initialized based on the setting values, and then itsprocess
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 through 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 callEngine.process(...)
for multiple times within the sameexecute()
call, by overriding thedoProcessing(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
- ifEngine.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 itsgetCause()
method to get the exception that caused the termination. Note that all (so even non-checked exceptions) thrown be the engine are catched and wrapped by this exeption.
-
addProgressListener
public void addProgressListener(ProgressListener pl)
Adds a progress listener. The progress listener will be added to the internally usedEngine
object when you callexecute()
.- See Also:
clearProgressListeners()
-
clearProgressListeners
public void clearProgressListeners()
Removes all progress listeneres.- 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 usedEngine
object when you callexecute()
.- 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.- 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.- 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:
setEngineAttribute(String, Object)
-
setDontTraverseDirectories
public void setDontTraverseDirectories(boolean dontTraverseDirs)
-
getDontTraverseDirectories
public boolean getDontTraverseDirectories()
-
dump
public java.lang.String dump()
Dumps the current content of this object for debugging purposes.
-
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
Converts legacy dashed setting names to the standard format, assource-root
tosourceRoot
.- Parameters:
props
- theProperties
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 theEngine
level, using the already initializedEngine
object.By overriding this method, you can
- call
Engine.process(...)
for multiple times, so you can do multiple processing sessions with the same already initializedEngine
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); }
Modifying the
Settings
object in this method has no effect on theEngine
object (which is passed in as argument), since all settings are already applied on it. If you need to modify theEngine
object, call its methods directly.An implementation of this method may leak out the initialized
Engine
object for the caller ofexecute()
. Also, it may does not callEngine.proccess(...)
, but left it for the caller (who has the out-leakedEngine
object). These are extreme, but otherwise legitimate usages.- Parameters:
eng
- the already initializedEngine
object. You may do extra addjustments on it.sources
- the list of source files, the parameter toEngine.process(File[])
. It'snull
if the processing session usesoutputFile
setting.sourceFile
- if the session usesoutputFile
setting, then it' the 1st parameter toEngine.process(File, File)
, otherwise it is null.outputFile
- if the session usesoutputFile
setting, then it' the 2nd parameter toEngine.process(File, File)
, otherwise it is null.- Throws:
SettingException
ProcessingException
- call
-
getDashedName
public static java.lang.String getDashedName(java.lang.String name)
Converts mixed-case setting name to dashed form, like 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
-
-