Class FWSimVarMap
java.lang.Object
net.simplace.sim.util.FWSimVarMap
- All Implemented Interfaces:
org.apache.commons.jexl3.JexlContext
The variable map of a simulation: holds all
FWSimVariables of a simulation, keyed by name, together with the
system variables (current date, year, day of year, project and simulation id, spin-up settings, ...).
The var map is also the context in which rules are evaluated (JexlContext), and provides methods to replace
parameter tokens like ${name} in strings. Values are read via getValue or the
force...Value methods, which convert values of other data types.
When variables are linked, units, data types and content types can be checked; when values are set, data type, source and limits are checked according to the check level of the session.
- Author:
- Andreas Enders
-
Nested Class Summary
Nested classes/interfaces inherited from interface org.apache.commons.jexl3.JexlContext
org.apache.commons.jexl3.JexlContext.AnnotationProcessor, org.apache.commons.jexl3.JexlContext.CancellationHandle, org.apache.commons.jexl3.JexlContext.ClassNameResolver, org.apache.commons.jexl3.JexlContext.ModuleProcessor, org.apache.commons.jexl3.JexlContext.NamespaceFunctor, org.apache.commons.jexl3.JexlContext.NamespaceResolver, org.apache.commons.jexl3.JexlContext.OptionsHandle, org.apache.commons.jexl3.JexlContext.PragmaProcessor, org.apache.commons.jexl3.JexlContext.ThreadLocal -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic Comparator<FWSimVariable<?>> Compares variables by namestatic final Stringsignifying the string used as id for the current date in the VarMapstatic final Stringsignifying the string used as id for the current day of monthstatic final Stringsignifying the string used as id for the current day of yearstatic final Stringsignifying the string used as id for the current month in the VarMapstatic final Stringsignifying the string used as id for the current year in the VarMapstatic final DateTimeFormatterDefault date formatdd.MM.yyyystatic final Stringid of the variable holding the end date of the simulationstatic final Stringid of the variable holding the current project idstatic final Stringid of the variable holding the iteration number of the projectstatic final Stringprojectlines that are read from project filestatic final Stringid of the variable holding the id of the current sessionstatic final Stringid of the variable holding the current simulation idstatic final Stringid of the variable holding the name of the current simulationstatic final Stringid of the variable holding the number of the current simulationstatic final Stringid of the variable holding the selected simulations of the current iterationstatic final Stringsignifying whether the simulation is in the spin-up period (true) or not (false); can be written as output column of outputs withspinup="true", whose spin-up lines may repeat the dates of the runstatic final Stringsignifying the integer number of spin up days in the VarMapstatic final Stringsignifying whether date has to be reset after spinupstatic final Stringsignifying whether date was reset after spinupstatic final Stringid of the variable holding the start date of the simulationstatic final Stringsignifying whether threads are synchronized within one project (true) or not (false)static final Stringthe rule for the data synchronized within one project if FREQUENCE is COMPLEX -
Constructor Summary
ConstructorsConstructorDescriptionCreates an empty var map with system variables only, e.g.FWSimVarMap(HashMap<String, FWSimVariable<?>> aParameterMap) Creates a var map without session, e.g.FWSimVarMap(HashMap<String, FWSimVariable<?>> aFormInputParameterMap, FWSimModel aModel, String aProjectID, FWSimSession aCurrentSession) Creates the var map of a simulation and adds the system variables. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddLink(String aKey, FWSimVariable<?> aVar, boolean performChecks) Links a variable (usually a component input) to another variable: the source variable is registered under the key of the target, so both names refer to the same variable.voidaddVariable(String aKey, FWSimVariable<?> aFWSimVariable, boolean isLink) Adds a variable to the var map (replacing a variable with the same key).voidLets the output manager of the session calculate the statistics outputs for this var map.booleancheckInternal(FWSimVariable<?> aFwSimVariable) Checks that a system variable is the instance managed by this var map (for the id and name variables).clone(FWSimSession aSession) Copies the var map for another session.Creates a reduced copy for the simulation control: only project variables (var,dyn) and system variables are copied (without the date parts and spin-up variables); links are not copied.booleanObject[]filterData(HashMap<String, FWSimVariable<?>> aFilterMap) Returns the values of the variables whose names are the keys of a map.Object[]filterData(Set<String> aKeySet) Returns the values of the given variables (rules are evaluated, seegetValue(String)).booleanforceBooleanValue(String aParamKey) Returns a value converted to boolean.forceDateValue(String aParamKey) Returns a value converted to a date.Double[]forceDoubleArrayValue(String aString) Returns a value as double array.forceDoubleMapValue(String aKey) Returns a value as sorted map.forceDoubleValue(String aKey) Returns a value converted to Double.Integer[]forceIntegerArrayValue(String aString) Returns a value as integer array.forceIntegerValue(String aKey) Returns a value converted to Integer (decimals are truncated).Generates the simulation id from project iteration, project id, simulation name and number, and stores it.JEXL context: returns the value of a variable.intintintintReturns the id of the current simulation.getSimVariable(String aKey) Returns the variable registered under a key.getStringValue(String aKey) Returns the value of a variable; for variables with a rule, the rule is evaluated.Returns the value of a variable.getValueToDatabaseString(String aSourceKey) Formats the value of a variable as SQL literal: dates as'yyyy-MM-dd', numbers unquoted, arrays as{v1,v2,...}, other values quoted (quotes in the value are not escaped).getVariables(FWSimFieldContainer aContainer) Returns all variables owned by a container, grouped by content type.getVariables(FWSimVariable.CONTENT_TYPE aContentType, boolean aIsSorted) Returns all variables of a content type (each variable once, even if it is registered under several names).HashMap<String, FWSimVariable<?>> booleanJEXL context: checks whether a variable exists.booleanhasSimVariable(String aRule) Checks whether a variable exists.voidSets the current date at the start of a simulation and starts the spin-up count down if spin-up days are set.voidinitValue(String aKey, FWSimVariable<?> aFWSimVariable) Adds a variable to the var map.static booleanisInternal(String aVarName) booleanbooleanbooleanisVariableAvailable(String aKey) booleanvoidputAllVariables(Map<String, FWSimVariable<?>> aVarMap) Adds several variables to the var map (replacing variables with the same key).voidremoveLink(String aName, FWSimVariable<?> aFwSimVariable) Removes a link: the link name is removed from the variable currently registered under aName, and aFwSimVariable is registered under this name instead.voidremoveVariable(String aElement) Removes a variable from the var map.replaceParamTokens(String aString, Object aDefault) Replaces parameter tokens like${name}in a string with the values of the variables of this var map.voidreset()Resets the variables of the simulation control containers (e.g.voidJEXL context: sets the value of a variable (converted to its data type, with the owner as source).voidsetCurrentDate(LocalDateTime aCurrentDate) Sets the current model date.voidsetCurrentSession(FWSimSession aFwSimSession) Sets the current session and its id.voidsetProjectID(String aProjectID) Sets the project id and clears the simulation id, so that it is generated again.voidsetSessionID(String aSessionID) voidMarks the simulation as ended.voidsetSimulationName(String aSimulationName) Sets the simulation name and clears the simulation id, so that it is generated again.voidsetSimulationNumber(Integer aSimulationNumber) Sets the simulation number and clears the simulation id, so that it is generated again.voidsetValue(String aKey, Object aValue, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, FWSimFieldContainer aSourceComponent) Sets the value of a variable.voidsetWaiting(boolean shouldWait) Suspends the calling thread on this var map (wait()) or wakes up a waiting thread (notify()).String[][]toArray()toString()Returns a text with simulation id, current date and one line per entry of the var map (for debugging).voidCalled at the start of each time step: during spin-up the count down is decreased; at the end of the spin-up (or when the end date is reached during spin-up) the date is reset to the start date if configured.voidWrites the current model date to the system variables (date, year, day of year, month, day of month) and the spin-up state, without changing the spin-up count down.
-
Field Details
-
CURRENT_DATE
signifying the string used as id for the current date in the VarMap- See Also:
-
CURRENT_YEAR
signifying the string used as id for the current year in the VarMap- See Also:
-
CURRENT_DAY
signifying the string used as id for the current day of month- See Also:
-
CURRENT_MONTH
signifying the string used as id for the current month in the VarMap- See Also:
-
CURRENT_DOY
signifying the string used as id for the current day of year- See Also:
-
PROJECT_ID
-
PROJECT_ITERATION
id of the variable holding the iteration number of the project- See Also:
-
SIMULATION_ID
id of the variable holding the current simulation id- See Also:
-
SIMULATION_NAME
id of the variable holding the name of the current simulation- See Also:
-
SIMULATION_NUMBER
id of the variable holding the number of the current simulation- See Also:
-
SESSION_ID
id of the variable holding the id of the current session- See Also:
-
SPINUP_DAYS
signifying the integer number of spin up days in the VarMap- See Also:
-
SPINUP_DO_RESET
signifying whether date has to be reset after spinup- See Also:
-
SPINUP_RESET
-
SPINUP_ACTIVE
signifying whether the simulation is in the spin-up period (true) or not (false); can be written as output column of outputs withspinup="true", whose spin-up lines may repeat the dates of the run- See Also:
-
SYNCHRONIZE_FREQUENCE
signifying whether threads are synchronized within one project (true) or not (false)- See Also:
-
SYNCHRONIZE_RULE
the rule for the data synchronized within one project if FREQUENCE is COMPLEX- See Also:
-
PROJECT_LINES
-
SIMULATIONS_SELECTED
id of the variable holding the selected simulations of the current iteration- See Also:
-
END_DATE
id of the variable holding the end date of the simulation- See Also:
-
START_DATE
id of the variable holding the start date of the simulation- See Also:
-
DATE_FORMAT
Default date formatdd.MM.yyyy -
COMPARATOR
Compares variables by name
-
-
Constructor Details
-
FWSimVarMap
public FWSimVarMap(HashMap<String, FWSimVariable<?>> aFormInputParameterMap, FWSimModel aModel, String aProjectID, FWSimSession aCurrentSession) Creates the var map of a simulation and adds the system variables.- Parameters:
aFormInputParameterMap- the variables of the simulation, keyed by name; used directly, not copiedaModel- the model (simulation) the var map belongs toaProjectID- id of the current projectaCurrentSession- the current session
-
FWSimVarMap
Creates a var map without session, e.g. for tests or for writing the simulations of a project file. Project id, simulation name and number are taken from the given variables if present (defaults:TestProject,TestSimulation); the values of other given system variables (e.g. start and end date) are kept.- Parameters:
aParameterMap- the variables, keyed by name; used directly, not copied
-
FWSimVarMap
public FWSimVarMap()Creates an empty var map with system variables only, e.g. for generating documentation.
-
-
Method Details
-
setWaiting
Suspends the calling thread on this var map (wait()) or wakes up a waiting thread (notify()). The caller must hold the monitor of this object.- Parameters:
shouldWait-trueto wait,falseto wake up a waiting thread- Throws:
InterruptedException- if the waiting thread is interrupted
-
getVarMap
- Returns:
- the underlying map of all variables, keyed by name
-
getStringValue
-
forceIntegerValue
-
forceDoubleValue
-
forceBooleanValue
Returns a value converted to boolean. Use this only if the variable is not a BOOLEAN variable; otherwise usegetValue().- Parameters:
aParamKey- name of the variable- Returns:
- the converted value (see
StringHelper.parseBoolean(Object)),falseif not convertible
-
forceDateValue
Returns a value converted to a date. Use this only if the variable is not a DATE variable; otherwise usegetValue().- Parameters:
aParamKey- name of the variable- Returns:
- the converted date (see
StringHelper.parseDate(Object, LocalDateTime)), ornullif not convertible
-
forceDoubleArrayValue
Returns a value as double array. If the variable is no double array, the single variables<name>.0,<name>.1, ... are collected into an array. Use this only if the variable is not a DOUBLEARRAY variable; otherwise usegetValue().- Parameters:
aString- name of the variable; the variable must exist- Returns:
- the array, or
nullif it cannot be determined
-
forceDoubleMapValue
Returns a value as sorted map. A double array is interpreted as key/value pairs{k1, v1, k2, v2, ...}(seeFWSimHelper.ArrayToMap(Double[])).- Parameters:
aKey- name of the variable; the variable must exist- Returns:
- the map, or
nullif it cannot be determined - See Also:
-
forceIntegerArrayValue
Returns a value as integer array. If the variable is no integer array, the single variables<name>.0,<name>.1, ... are collected into an array. Use this only if the variable is not an INTARRAY variable; otherwise usegetValue().- Parameters:
aString- name of the variable; the variable must exist- Returns:
- the array, or
nullif it cannot be determined
-
replaceParamTokens
Replaces parameter tokens like${name}in a string with the values of the variables of this var map.- Parameters:
aString- string containing parameter tokensaDefault- value returned if the string cannot be resolved- Returns:
- the string with replaced tokens
- See Also:
-
getValue
-
getValue
Returns the value of a variable. For variables whose rule is more than a plain variable name (except management variables), the rule is evaluated and its result returned.- Parameters:
aKey- name of the variableaDefault- value returned if the variable does not exist or has no value- Returns:
- the value, or aDefault
-
setValue
public void setValue(String aKey, Object aValue, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, FWSimFieldContainer aSourceComponent) throws SimValueOutOfRangeException Sets the value of a variable. Strings are converted to the data type of the variable. The value is only set if it differs from the current value; checks are done as inFWSimVariable.setValue(Object, FWSimFieldContainer). If the variable does not exist, it is created with the given data and content type and a warning is logged.- Parameters:
aKey- name of the variableaValue- the value;nullclears the valueaDataType- data type used if the variable has to be createdaContentType- content type used if the variable has to be createdaSourceComponent- component that sets the value, for checking purposes- Throws:
SimValueOutOfRangeException- (runtime exception) if the value exceeds min or max and the check level is STRICTRuntimeException- if the value does not match the data type of the variable
-
initValue
Adds a variable to the var map. If it has no value, it is reset to its default value. If aKey differs from the variable name, the variable is registered under both names (the second as link).- Parameters:
aKey- key to register the variable underaFWSimVariable- the variable
-
addVariable
Adds a variable to the var map (replacing a variable with the same key). A warning is logged if the key differs from the variable name and the variable is not added as link.- Parameters:
aKey- key to register the variable underaFWSimVariable- the variableisLink-trueif the key is an additional name (link) for the variable
-
getProjectID
- Returns:
- the id of the current project
-
getSimulationID
Returns the id of the current simulation. If it is not set yet, it is generated.- Returns:
- the simulation id
- See Also:
-
generateSimulationID
Generates the simulation id from project iteration, project id, simulation name and number, and stores it.- Returns:
- the generated simulation id
- See Also:
-
setSimulationName
Sets the simulation name and clears the simulation id, so that it is generated again.- Parameters:
aSimulationName- the new simulation name
-
getSimulationName
- Returns:
- simulation name
-
getSimulationNumber
- Returns:
- the simulation number
-
getIteration
- Returns:
- the iteration number of the project
-
getCurrentSession
- Returns:
- the current session
-
isSynchronized
public boolean isSynchronized()- Returns:
trueif the simulations of a project are synchronized (synchronize frequency other than NON)
-
getSynchronizedFrequence
- Returns:
- the frequency in which the simulations of a project are synchronized, NON if not synchronized
-
getSynchronizeRule
- Returns:
- the rule for synchronisation (used with frequency COMPLEX), or
nullif not synchronized
-
isWaiting
public boolean isWaiting()- Returns:
trueif a thread is waiting on this var map (seesetWaiting(boolean))
-
getCurrentDateString
- Returns:
- the current model date formatted as
dd.MM.yyyy, ornullif not set
-
getStartDate
- Returns:
- the start date of the simulation
-
getEndDate
- Returns:
- the end date of the simulation
-
calculateStatistics
public void calculateStatistics()Lets the output manager of the session calculate the statistics outputs for this var map. -
setProjectID
Sets the project id and clears the simulation id, so that it is generated again.- Parameters:
aProjectID- the new project id
-
setSessionID
- Parameters:
aSessionID- id of the current session
-
setSimulationNumber
Sets the simulation number and clears the simulation id, so that it is generated again.- Parameters:
aSimulationNumber- the new simulation number
-
setCurrentSession
Sets the current session and its id.- Parameters:
aFwSimSession- the current session
-
removeVariable
Removes a variable from the var map. Use with care - the variable might still be needed.- Parameters:
aElement- name of the variable
-
filterData
Returns the values of the variables whose names are the keys of a map.- Parameters:
aFilterMap- map whose keys are the variable names- Returns:
- the values in the iteration order of the keys
- See Also:
-
filterData
Returns the values of the given variables (rules are evaluated, seegetValue(String)).- Parameters:
aKeySet- names of the variables- Returns:
- the values in the iteration order of the set;
nullfor unknown variables
-
putAllVariables
Adds several variables to the var map (replacing variables with the same key). If checks are enabled, a warning is logged for keys of system variables.- Parameters:
aVarMap- the variables to add, keyed by name
-
isVariableAvailable
- Parameters:
aKey- name of the variable- Returns:
trueif the variable exists and has a non-empty value (seeStringHelper.isEmpty(Object))
-
isSpinupPeriode
public boolean isSpinupPeriode()- Returns:
trueif the simulation is in the spin-up period
-
doSpinupReset
public boolean doSpinupReset()- Returns:
trueif the date has just been reset to the start date after (or during) the spin-up
-
toString
-
toArray
- Returns:
- a table with a header row and one row per entry sorted by key: key, variable name, value as string
-
addLink
public void addLink(String aKey, FWSimVariable<?> aVar, boolean performChecks) throws SimLinkInvalidException Links a variable (usually a component input) to another variable: the source variable is registered under the key of the target, so both names refer to the same variable. Variables of typevarwith a rule are not linked if the target does not exist.- Parameters:
aKey- name of the target (e.g. the input variable)aVar- the source variable (e.g. an output of another component)performChecks- iftrue, it is checked that both variables exist and have the same data type- Throws:
SimLinkInvalidException- if a check fails
-
removeLink
Removes a link: the link name is removed from the variable currently registered under aName, and aFwSimVariable is registered under this name instead.- Parameters:
aName- name of the linked targetaFwSimVariable- the variable to register under the name from now on
-
initializeCurrentDate
Sets the current date at the start of a simulation and starts the spin-up count down if spin-up days are set.- Parameters:
aDate- the first model date
-
updateCurrentDate
public void updateCurrentDate()Called at the start of each time step: during spin-up the count down is decreased; at the end of the spin-up (or when the end date is reached during spin-up) the date is reset to the start date if configured. Then the current model date is written to the system variables (seewriteCurrentDateVariables()). Withspinupdays= n, the first n steps are the spin-up. -
writeCurrentDateVariables
public void writeCurrentDateVariables()Writes the current model date to the system variables (date, year, day of year, month, day of month) and the spin-up state, without changing the spin-up count down. Used when a simulation is created: before (#623 finding),updateCurrentDate()was called there, which already counted one spin-up day, sospinupdays= n gave only n-1 spin-up steps. -
getCurrentDate
- Returns:
- the current model date
-
setCurrentDate
Sets the current model date. The system variables are only updated byupdateCurrentDate().- Parameters:
aCurrentDate- the current model date
-
getCurrentDOY
public int getCurrentDOY()- Returns:
- current DayOfYear
-
getCurrentYear
public int getCurrentYear()- Returns:
- current Year
-
getCurrentDayOfMonth
public int getCurrentDayOfMonth()- Returns:
- current Day of Month
-
getCurrentMonth
public int getCurrentMonth()- Returns:
- current Month
-
hasSimulationEnded
- Returns:
trueif the simulation has ended
-
setSimulationEnd
public void setSimulationEnd()Marks the simulation as ended. -
clone
Copies the var map for another session. Every variable is copied withFWSimVariable.clone(FWSimVarMap)(new variable object, shared meta data) and links are rebuilt to the copies.- Parameters:
aSession- session of the copy- Returns:
- the copy
-
cloneToControlMap
Creates a reduced copy for the simulation control: only project variables (var,dyn) and system variables are copied (without the date parts and spin-up variables); links are not copied.- Returns:
- the reduced copy
-
getSimLinks
-
reset
public void reset()Resets the variables of the simulation control containers (e.g. generators) to their default values. Other variables are not changed. -
hasSimVariable
Checks whether a variable exists. In rules, dots in names are written as double underscores; they are converted back before the lookup.- Parameters:
aRule- name of the variable, possibly with__instead of dots- Returns:
trueif a variable with this name exists
-
getSimVariable
Returns the variable registered under a key. For links this is the linked source variable, whose name may differ from the key. Keys with an index or parameter specification (!,${) are resolved to the base name if necessary.- Parameters:
aKey- name or link name of the variable- Returns:
- the variable
- Throws:
SimFieldMissingException- if no variable is registered under the key
-
getValueToDatabaseString
Formats the value of a variable as SQL literal: dates as'yyyy-MM-dd', numbers unquoted, arrays as{v1,v2,...}, other values quoted (quotes in the value are not escaped).- Parameters:
aSourceKey- name of the variable- Returns:
- the SQL literal
- Throws:
SimFieldMissingException- if the variable does not exist
-
getVariables
public Collection<FWSimVariable<?>> getVariables(FWSimVariable.CONTENT_TYPE aContentType, boolean aIsSorted) Returns all variables of a content type (each variable once, even if it is registered under several names).- Parameters:
aContentType- the content typeaIsSorted- iftrue, the list is sorted by name- Returns:
- the variables
-
getVariables
public MultiHashMap<FWSimVariable.CONTENT_TYPE, FWSimVariable<?>> getVariables(FWSimFieldContainer aContainer) Returns all variables owned by a container, grouped by content type. Variables registered under several names (links) appear several times.- Parameters:
aContainer- the owning container- Returns:
- map from content type to the variables
-
has
JEXL context: checks whether a variable exists. Double underscores in the name stand for dots. Found variables are cached for faster access.- Specified by:
hasin interfaceorg.apache.commons.jexl3.JexlContext- See Also:
-
get
-
set
JEXL context: sets the value of a variable (converted to its data type, with the owner as source). Double underscores in the name stand for dots. A warning is logged if the variable does not exist.- Specified by:
setin interfaceorg.apache.commons.jexl3.JexlContext- See Also:
-
printJexlMap
- Returns:
- the cache of variables used in rule evaluation, formatted as text (for debugging)
-
isInternal
- Parameters:
aVarName- name of a variable- Returns:
trueif the name is the name of a system variable (e.g. CURRENT.DATE, projectid)
-
checkInternal
Checks that a system variable is the instance managed by this var map (for the id and name variables). A warning is logged if another instance with the same name is found.- Parameters:
aFwSimVariable- the variable to check- Returns:
falseif the variable is a system variable but not the managed instance, otherwisetrue
-