Class FWSimVariable<T>
- Type Parameters:
T- type of the value, matching the data type (e.g. Double for DOUBLE, Integer[] for INTARRAY)
- Direct Known Subclasses:
FWSimCalibrationVariable
Besides the value, a variable carries meta data: name (id), description, unit, data type (FWSimVariable.DATA_TYPE),
content type (FWSimVariable.CONTENT_TYPE, i.e. its role), optional minimum/maximum and default value, an optional rule
(expression evaluated to obtain the value) and, for outputs, an aggregation mode (FWSimVariable.MODE_TYPE). Values set
via the setters are checked against the limits according to the check level of the session.
Variables are usually created from the XML of a solution via createSimVariable(Element, FWSimFieldContainer)
or by SimComponents in their createVariables() method.
- Author:
- Andreas Enders
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumThe content type describes the role of a variable, e.g.static enumData types of variable values.static classFormats and parses dates either with a pattern or as number of days since 1970 (EPOCH_DAY).static enumThe mode defines how values of an output variable are aggregated if the output frequency is not daily, and how management variables are applied (RESET, SET, ITE).static enumFiner categorisation of variables thanFWSimVariable.CONTENT_TYPE, used to group variables in lists (e.g. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringUnit of variables of generic components (e.g. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedFWSimVariable(String aName, String aDescription, String aRule, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, T aValue, Number aMin, Number aMax, T aDefault, Integer[] aCount, FWSimVariable.MODE_TYPE aModeType, FWSimVarMap aVarMap, FWSimFieldContainer aSourceSimComponent) Creates a variable.protectedFWSimVariable(FWSimVariable<T>.net.simplace.sim.util.FWSimVariable.MetaData<T> aMetaData, T aValue, FWSimVarMap aVarMap) Creates a variable that shares the meta data of another variable, e.g. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddInputLink(String aFieldName) Registers a link from an output variable to this input variable.voidaddOutputLink(String aFieldName) Registers a link from this output variable to an input variable.voidaddValue(FWSimVariable<T> aVariable, FWSimFieldContainer aSource) Adds the value of another variable to the current value.voidaddValue(T aValue, FWSimFieldContainer aSource) Adds a value to the current value: numbers are summed (int variables stay int), double and int arrays are added element by element (in place).booleanadoptUnitFrom(FWSimVariable<?> aSource) Takes the unit of another variable if this unit isUNIT_SOLUTION_DEFINEDand the other one has a concrete unit (changes the shared meta data).calculateValue(FWSimVarMap aVarMap) Evaluates the rule against a var map and sets the result as value (with the checks ofsetValue(Object, FWSimVariable, FWSimFieldContainer)).voidchangeDefaultValue(T aValue) Changes the default value (the current value is not changed).check(FWSimVariable<?> aOutputVar) Checks whether an output variable can be linked to this (input) variable.clone(FWSimVarMap aVarMap) Creates a shallow copy for another var map: the new variable shares the meta data (name, limits, rule, links, ...) with this variable; only the value reference and the var map are separate.static org.jdom2.ElementcreateFormElement(FWSimVariable<?> aVariable, String aName, String aDescription, String aVisible, String aEnabled, String aContentType, String aModeType, boolean aModeNeeded, String tDataType, String tUnit, String tMax, String tMin, String tRule, String tDesc, String tDefault, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form group for editing a single variable.static org.jdom2.ElementcreateFormFields(String aName, String aDescription, String aContentTypeDefault, String aVisible, String aEnabled, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form fields for a new variable (data type DOUBLE, mode IGNORE, no other values).static org.jdom2.ElementcreateFormFields(FWSimVariable<?> aVariable, FWSimVariable.CONTENT_TYPE aComponentContentType, String aDescription, String aFrequence, String aVisible, String aEnabled, boolean aMultipleVarType) Creates the GUI form fields for editing a variable.static org.jdom2.ElementcreateMultipleFormElement(FWSimVariable<?> aVariable, String aName, String aDescription, String aVisible, String aEnabled, String aContentType, String tModeType, boolean aModeNeeded, String aFrequence, String tDataType, String tUnit, String tMax, String tMin, String tRule, String tDesc, String tDefault, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form group for one variable inside a form with several variables.static FWSimVariable<?> createOutputSimVariable(String aName, String aDesc, String aRule, FWSimVariable.DATA_TYPE aDataType, String aUnit, String aOutputFormat, Object aDefault, FWSimVariable.MODE_TYPE aModeType, FWSimFieldContainer aTarget) Creates a variable of an output definition (not a component output) with content typeout.static FWSimVariable<?> createSimVariable(String aName, String aDesc, String aRule, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, Object aValue, Number aMin, Number aMax, Object aDefault, Integer[] aCount, FWSimVariable.MODE_TYPE aModeType, FWSimVarMap aVarMap, FWSimFieldContainer aSourceSimComponent) General factory method used by all other factory methods.static FWSimVariable<?> createSimVariable(String aName, String aDesc, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, Number aMin, Number aMax, Object aDefault, FWSimFieldContainer aSourceSimComponent) Creates a variable of a SimComponent.static FWSimVariable<?> createSimVariable(org.jdom2.Element aVarElement, FWSimFieldContainer aFWSimFieldContainer) Creates a typed variable from an XML element of a solution, e.g.deepClone(FWSimVarMap aVarMap) Creates a copy for another var map with its own copy of the meta data, so that changes of the meta data (e.g.booleanTwo variables are equal if they have the same name.evaluate()Evaluates the rule against the var map of this variable without changing the value.evaluate(FWSimVarMap aVarMap) Evaluates the rule against a var map without changing the value.voidfillMetaDataFromSource(FWSimVarMap aVarMap) Completes the meta data from the variable referenced by the rule (if the rule is the name of a variable in the var map): missing description and unit, the data type (with a warning; not if a single array element is selected by!in the name or exactly onecountindex), and missing limits of numbers are taken from the source.booleanforceBooleanValue(boolean aDefault) Returns the value converted to boolean: numbers aretrueif their int value is 1, strings are parsed withStringHelper.parseBoolean(Object, boolean).Interprets a double array as list of key/value pairs{k1, v1, k2, v2, ...}and returns them as sorted map, e.g.doubleReturns the value converted to double.intReturns the value converted to int (decimals are truncated).Returns the value converted to string.getArrayValue(int aIndex) Returns one element of a double or int array.Derives the category from the content type.Integer[]getCount()getDateFormatter(String aPattern) Returns a date formatter for a pattern.Returns the formatter for output, created on first call: for dates a date formatter for the format (or the default date format), for other data types the format string itself.org.jdom2.ElementCreates a GUI form field for editing the value of this variable.getMatrixValue(int aXIndex, int aYIndex) Returns one element of a double matrix.getMax()getMin()getName()String[]getOrder()getRule()Returns the unit for display.getUnit()getValue()Returns the value.booleanhasRule()booleanisArray()booleanbooleanisDate()booleanisDouble()booleanbooleanbooleanisInt()booleanbooleanisNumber()booleanbooleanbooleanisString()booleanvoidmultiplyValue(Number aValue, FWSimFieldContainer aSource) Multiplies the current value by a factor: numbers are multiplied, double and int arrays are multiplied element by element (in place; int variables and arrays with the truncated factor).voidremoveLink(String aName) Removes a registered link.voidreset()Replaces the value with the default value, even if the default isnull.voidsetArrayValue(int aIndex, Number aValue, FWSimFieldContainer aSource) Sets one element of a double or int array.voidsetArrayValue(int aIndex, String aValue, FWSimFieldContainer aSource) Sets one element of a text array (CHARARRAY).voidsetContentType(FWSimVariable.CONTENT_TYPE aContentType) Integer[]setCount(int aCount) Ensures that the index list covers at least aCount elements: if it is shorter, it is replaced by0 ..voidvoidReplaces the value with the default value, even if the default isnull.voidvoidsetModeType(FWSimVariable.MODE_TYPE aModeType) voidRenames the variable.voidsetNull(FWSimFieldContainer aSource) Sets the value tonull.voidSets the rule calculating the value and compiles a JEXL script for it if necessary (changes the shared meta data).voidsetSource(FWSimFieldContainer aComponent) Sets the owning container, but only if none is set yet.setUnitFrom(FWSimVariable<?> aInput) Lets an output of a generic component take the unit of one of its inputs (#60), e.g.static <F> FsetValue(Object aObject, FWSimVariable<F> aSimVariable, FWSimFieldContainer aSourceComponent) Converts a value of any type to the data type of a variable and sets it.voidsetValue(FWSimVariable<T> aVariable, FWSimFieldContainer aSource) Sets the value of another variable as value of this variable.voidsetValue(T aValue, FWSimFieldContainer aSource) Sets the value.static <F> FsetValueAndDefault(Object aObject, FWSimVariable<F> aSimVariable, FWSimFieldContainer aSourceComponent) Converts a value of any type to the data type of a variable and sets it as value and as default value.voidsetVarMap(FWSimVarMap aFwSimvarMap) org.jdom2.ElementtoCalVarXML(String aCommaSeperatedList) Creates acalelement that varies this variable over a list of values, e.g.org.jdom2.ElementtoCalVarXML(String aMinVal, String aMaxVal, Integer aCount) Creates acalelement that varies this variable equidistantly between min and max, e.g.Formats this variable as HTML table row with content type, name, description, data type, unit, min, max and value (or default value), e.g.org.jdom2.ElementtoOutVarXML(String aMode) Creates anoutelement that writes this variable to an output, e.g.toString()org.jdom2.ElementtoXML()Creates the XML element of this variable as used in a solution.static StringtransformContentType(FWSimVariable.CONTENT_TYPE aContentType) Returns a readable name for a content type, e.g.static ObjecttransformDataType(String aObject, FWSimVariable.DATA_TYPE aDataType) Converts a string into the Java type of a data type.static ObjecttransformDataType(String aObject, FWSimVariable<?> aSimVariable) Converts a string into the Java type of the data type of a variable.static StringtransformDataTypeToDB(FWSimVariable.DATA_TYPE aDataType) Returns the SQL column type for a data type.static FWSimVariable.DATA_TYPEtransformDBDataType(String dataType) Returns the data type for an SQL column type (by prefix: INT, FLOAT, DOUBLE, DATE, BOOL).static FWSimVariable.DATA_TYPEtransformJavaDataType(String dataType) Returns the data type for a Java type name, e.g.static StringtransformJavaDataType(FWSimVariable.DATA_TYPE aDataType) Returns the Java type name for a data type, e.g.static FWSimVariable<?> updateFields(FWSimVariable<?> aVariable, FWObservable aObservable) Creates or updates a variable from the values of a GUI form (seecreateFormFields(FWSimVariable, CONTENT_TYPE, String, String, String, String, boolean)).voidupdateFields(org.jdom2.Element aVarElement) Updates the meta data and the value of this variable from an XML element of a solution (same format as forcreateSimVariable(Element, FWSimFieldContainer)).
-
Field Details
-
UNIT_SOLUTION_DEFINED
Unit of variables of generic components (e.g. averaging, interpolation, layer redistribution) whose unit depends on the solution (#60): an input with this unit takes the unit of the variable linked to it in the solution, an output takes the unit of the input given withsetUnitFrom(FWSimVariable). The unit check of the links ignores it.- See Also:
-
-
Constructor Details
-
FWSimVariable
protected FWSimVariable(String aName, String aDescription, String aRule, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, T aValue, Number aMin, Number aMax, T aDefault, Integer[] aCount, FWSimVariable.MODE_TYPE aModeType, FWSimVarMap aVarMap, FWSimFieldContainer aSourceSimComponent) Creates a variable. Use the factory methodscreateSimVariable(...)instead.The name may contain an index specification that selects array elements, e.g.
name|1-3,name!2orname_${INDEX|1,3}(1-based indices, parameters are replaced from the var map). The index part is removed from the name and stored as count. If a rule is given and it is more than a plain value, a JEXL script is compiled for it.- Parameters:
aName- variable name, optionally with index specificationaDescription- descriptionaRule- rule calculating the value, ornullaDataType- data typeaContentType- content typeaUnit- unitaValue- initial valueaMin- minimum, ornullaMax- maximum, ornullaDefault- default valueaCount- indices of array elements, used if the name contains no index specificationaModeType- aggregation mode, ornullaVarMap- var map the variable belongs to; provides the checker of the sessionaSourceSimComponent- container declaring the variable
-
FWSimVariable
protected FWSimVariable(FWSimVariable<T>.net.simplace.sim.util.FWSimVariable.MetaData<T> aMetaData, T aValue, FWSimVarMap aVarMap) Creates a variable that shares the meta data of another variable, e.g. for copies in another var map.- Parameters:
aMetaData- meta data to share (not copied)aValue- value of the new variableaVarMap- var map the new variable belongs to
-
-
Method Details
-
createSimVariable
public static FWSimVariable<?> createSimVariable(org.jdom2.Element aVarElement, FWSimFieldContainer aFWSimFieldContainer) Creates a typed variable from an XML element of a solution, e.g.<var id="vLUE" datatype="DOUBLE" unit="g/MJ" min="0" max="5" default="3">3.2</var>. The element name is the content type; the attributesid,datatype,unit,description,rule(forcal:target),min,max,default,mode,count,formatandoptionare evaluated. The value is the element text,valuechildren (for arrays) or the default. If the data type is missing or the value does not match it, an error is logged and the data type is derived from the value.- Parameters:
aVarElement- XML element describing the variableaFWSimFieldContainer- container (e.g. component) the variable belongs to; may benull- Returns:
- the new variable
-
createSimVariable
public static FWSimVariable<?> createSimVariable(String aName, String aDesc, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, Number aMin, Number aMax, Object aDefault, FWSimFieldContainer aSourceSimComponent) Creates a variable of a SimComponent. The default value is also used as initial value. Typically called increateVariables()of a component.- Parameters:
aName- name (id) of the variableaDesc- descriptionaDataType- data typeaContentType- content type, e.g.input,state,rateaUnit- unit, e.g.kg/haaMin- minimum allowed value, ornullaMax- maximum allowed value, ornullaDefault- default and initial value, ornullaSourceSimComponent- the component the variable belongs to- Returns:
- the new variable
-
createOutputSimVariable
public static FWSimVariable<?> createOutputSimVariable(String aName, String aDesc, String aRule, FWSimVariable.DATA_TYPE aDataType, String aUnit, String aOutputFormat, Object aDefault, FWSimVariable.MODE_TYPE aModeType, FWSimFieldContainer aTarget) Creates a variable of an output definition (not a component output) with content typeout. Its value is calculated from the rule.- Parameters:
aName- name (id) of the variableaDesc- descriptionaRule- rule calculating the value, usually the name of the variable to writeaDataType- data typeaUnit- unitaOutputFormat- output format, e.g. a number or date patternaDefault- default value, ornullaModeType- aggregation mode if the output frequency is not dailyaTarget- the output the variable belongs to- Returns:
- the new variable
-
createSimVariable
public static FWSimVariable<?> createSimVariable(String aName, String aDesc, String aRule, FWSimVariable.DATA_TYPE aDataType, FWSimVariable.CONTENT_TYPE aContentType, String aUnit, Object aValue, Number aMin, Number aMax, Object aDefault, Integer[] aCount, FWSimVariable.MODE_TYPE aModeType, FWSimVarMap aVarMap, FWSimFieldContainer aSourceSimComponent) General factory method used by all other factory methods. Creates a variable whose generic type matches the data type. If the source is a component (not a solution), its name is prepended to the variable name (Component.variable).- Parameters:
aName- variable name; may contain an index specification (seeFWSimVariable(String, String, String, DATA_TYPE, CONTENT_TYPE, String, Object, Number, Number, Object, Integer[], MODE_TYPE, FWSimVarMap, FWSimFieldContainer))aDesc- descriptionaRule- rule calculating the value, ornullaDataType- data typeaContentType- content type (input, output, etc.)aUnit- unitaValue- initial value (internal use, not for initializing)aMin- minimum, ornullaMax- maximum, ornullaDefault- default value, used when initializing constants or inputsaCount- indices of array elements used by this variable, ornullaModeType- aggregation mode, ornullaVarMap- var map the variable belongs to (internal use, not for initializing)aSourceSimComponent- container (e.g. SimComponent) declaring the variable- Returns:
- the new variable
- Throws:
RuntimeException- if the value or default does not match the data type
-
fillMetaDataFromSource
Completes the meta data from the variable referenced by the rule (if the rule is the name of a variable in the var map): missing description and unit, the data type (with a warning; not if a single array element is selected by!in the name or exactly onecountindex), and missing limits of numbers are taken from the source. Variables whose source is a resource are marked as measured data.- Parameters:
aVarMap- var map containing the source variable
-
isNumber
public boolean isNumber()- Returns:
trueif the variable holds numbers (int or double, also arrays)
-
hasRule
public boolean hasRule()- Returns:
trueif the value is calculated by a rule
-
isDouble
public boolean isDouble()- Returns:
trueif the variable is a double, a double array or a double matrix
-
isInt
public boolean isInt()- Returns:
trueif the variable is an int or an int array
-
isBoolean
public boolean isBoolean()- Returns:
trueif the variable is a boolean
-
isString
public boolean isString()- Returns:
trueif the variable is a text (CHAR, CHARARRAY or FILE)
-
isDate
public boolean isDate()- Returns:
trueif the variable is a date (not a date array)
-
isArray
public boolean isArray()- Returns:
trueif the variable is an array or matrix (double, int or text; not DATEARRAY)
-
isOutputContent
public boolean isOutputContent()- Returns:
trueif the variable is not an input variable (seeisInputContent())
-
isInputContent
public boolean isInputContent()- Returns:
trueif the content type isinput,constantorprivat
-
isMeasData
public boolean isMeasData()- Returns:
trueif the value comes from measured data, i.e. its source is a resource
-
getDescription
- Returns:
- the description of this variable
-
getOrder
- Returns:
- the order of this variable (used for sorting)
-
getDataType
- Returns:
- the data type
-
getContentType
- Returns:
- the content type
-
getCategory
Derives the category from the content type. Variables of typevar,dynorsysare categorised assysif they are internal variables of the var map, otherwise asvar.- Returns:
- the category of this variable
-
getModeType
- Returns:
- the aggregation mode, or
null
-
getMax
- Returns:
- the maximum allowed value (for dates: milliseconds since 1970), or
null
-
getMin
- Returns:
- the minimum allowed value (for dates: milliseconds since 1970), or
null
-
getValue
Returns the value. This is the standard way to read a variable.- Returns:
- the value
-
getArrayValue
Returns one element of a double or int array.- Parameters:
aIndex- zero-based index of the element- Returns:
- the element, or
nullif the variable is not a double or int array
-
getMatrixValue
Returns one element of a double matrix.- Parameters:
aXIndex- zero-based row indexaYIndex- zero-based column index- Returns:
- the element, or
nullif the variable is not a DOUBLEMATRIX
-
forceDoubleMapValue
Interprets a double array as list of key/value pairs{k1, v1, k2, v2, ...}and returns them as sorted map, e.g. for lookup tables.- Returns:
- a map sorted by key
- Throws:
SimFieldTypeException- if the value is not a double array
-
forceBooleanValue
public boolean forceBooleanValue(boolean aDefault) Returns the value converted to boolean: numbers aretrueif their int value is 1, strings are parsed withStringHelper.parseBoolean(Object, boolean).Do not use this method for BOOLEAN variables - use
getValue()instead.- Parameters:
aDefault- value returned if the conversion fails- Returns:
- the converted value, or aDefault
-
forceDoubleValue
public double forceDoubleValue()Returns the value converted to double.Do not use this method for DOUBLE variables - use
getValue()instead.- Returns:
- the value as double, or NaN if it is not a number (a warning is logged)
-
forceIntValue
public int forceIntValue()Returns the value converted to int (decimals are truncated).Do not use this method for INT variables - use
getValue()instead.- Returns:
- the value as int, or 0 if it is not a number (a warning is logged)
-
forceStringValue
Returns the value converted to string. Double and int arrays are formatted as{v1,v2,...}.Do not use this method for CHAR variables - use
getValue()instead.- Returns:
- the value as string (
"null"fornull)
-
setDefaultValue
public void setDefaultValue()Replaces the value with the default value, even if the default isnull. Not allowed for constants and inputs (an error is logged and the value is kept). -
reset
public void reset()Replaces the value with the default value, even if the default isnull. UnlikesetDefaultValue(), this works for all content types. -
setVarMap
- Parameters:
aFwSimvarMap- the var map this variable belongs to
-
setModeType
- Parameters:
aModeType- the new aggregation mode (changes the shared meta data)
-
setRule
Sets the rule calculating the value and compiles a JEXL script for it if necessary (changes the shared meta data).- Parameters:
aRule- the new rule
-
setName
Renames the variable. Only used by generators.- Parameters:
aNewName- the new name
-
changeDefaultValue
Changes the default value (the current value is not changed).- Parameters:
aValue- the new default value
-
setNull
Sets the value tonull. Depending on the check level of the session, the write access of the source is checked first (owner of the variable, write protection of the content type); if the check fails, the value is not changed.- Parameters:
aSource- component that wants to change the value, for checking purposes- Throws:
SimLinkInvalidException- if the write access is not allowed and the check level is STRICT
-
setValue
Sets the value. This is the standard way to write a variable.Depending on the check level of the session (
FWCheckHelper):- numbers are checked against min and max (LAZY: warning, INTENSE: value is limited, STRICT: exception),
- the write access of the source is checked (owner of the variable, write protection of the content type); if the check fails, the value is not changed.
- Parameters:
aValue- the value to setaSource- component that wants to set the value, for checking purposes- Throws:
SimValueOutOfRangeException- if the value exceeds min or max and the check level is STRICTSimLinkInvalidException- if the write access is not allowed and the check level is STRICT
-
setValue
public void setValue(FWSimVariable<T> aVariable, FWSimFieldContainer aSource) throws SimValueOutOfRangeException, SimLinkInvalidException Sets the value of another variable as value of this variable.- Parameters:
aVariable- variable whose value is takenaSource- component that wants to set the value, for checking purposes- Throws:
SimValueOutOfRangeException- if the value exceeds min or max and the check level is STRICTSimLinkInvalidException- if the write access is not allowed and the check level is STRICT- See Also:
-
addValue
Adds a value to the current value: numbers are summed (int variables stay int), double and int arrays are added element by element (in place). For other data types the value is replaced by aValue. For numbers the sum is checked against min and max like insetValue(Object, FWSimFieldContainer). The write access of the source is not checked.- Parameters:
aValue- the value to addaSource- component that changes the value (currently not used)- Throws:
SimValueOutOfRangeException- if the sum exceeds min or max and the check level is STRICT
-
addValue
public void addValue(FWSimVariable<T> aVariable, FWSimFieldContainer aSource) throws SimValueOutOfRangeException Adds the value of another variable to the current value.- Parameters:
aVariable- variable whose value is addedaSource- component that changes the value (currently not used)- Throws:
SimValueOutOfRangeException- if the checked value exceeds min or max and the check level is STRICT- See Also:
-
multiplyValue
public void multiplyValue(Number aValue, FWSimFieldContainer aSource) throws SimValueOutOfRangeException Multiplies the current value by a factor: numbers are multiplied, double and int arrays are multiplied element by element (in place; int variables and arrays with the truncated factor). For other data types the value is replaced by the factor. For numbers the product is checked against min and max like insetValue(Object, FWSimFieldContainer). The write access of the source is not checked.- Parameters:
aValue- the factoraSource- component that changes the value (currently not used)- Throws:
SimValueOutOfRangeException- if the product exceeds min or max and the check level is STRICT
-
setArrayValue
public void setArrayValue(int aIndex, Number aValue, FWSimFieldContainer aSource) throws SimValueOutOfRangeException, SimFieldTypeException Sets one element of a double or int array. The value is checked against min and max; the write access of the source is not checked. If the type of the value does not match the array (Double/Integer), nothing is set.- Parameters:
aIndex- zero-based index of the elementaValue- the value to setaSource- component that sets the value (currently not used)- Throws:
SimValueOutOfRangeException- if the value exceeds min or max and the check level is STRICTSimFieldTypeException- if the variable is not an array
-
setArrayValue
public void setArrayValue(int aIndex, String aValue, FWSimFieldContainer aSource) throws SimValueOutOfRangeException, SimFieldTypeException Sets one element of a text array (CHARARRAY). The write access of the source is not checked.- Parameters:
aIndex- zero-based index of the elementaValue- the value to setaSource- component that sets the value (currently not used)- Throws:
SimValueOutOfRangeException- declared but not thrownSimFieldTypeException- if the variable is not an array
-
getName
- Returns:
- the full name, including the component name for component variables (e.g.
Component.variable)
-
getInternalName
- Returns:
- the name without the component name, i.e. the part after the first dot
-
getUnit
- Returns:
- the unit
-
isUnitSolutionDefined
public boolean isUnitSolutionDefined()- Returns:
trueif the unit isUNIT_SOLUTION_DEFINED, i.e. not yet taken from the solution
-
setUnitFrom
Lets an output of a generic component take the unit of one of its inputs (#60), e.g. the average ofiValuehas the unit ofiValue. The unit is set toUNIT_SOLUTION_DEFINEDand replaced by the unit of the input once the input is linked in the solution. Call it increateVariables()after both variables were created.- Parameters:
aInput- the input of the same component (usually with unitUNIT_SOLUTION_DEFINED)- Returns:
- this variable
-
getUnitSource
- Returns:
- the input whose unit this output takes (see
setUnitFrom(FWSimVariable)), ornull
-
adoptUnitFrom
Takes the unit of another variable if this unit isUNIT_SOLUTION_DEFINEDand the other one has a concrete unit (changes the shared meta data). Used when the links of a component are established.- Parameters:
aSource- the linked source variable (or, for outputs, the input given withsetUnitFrom(FWSimVariable))- Returns:
trueif the unit was taken
-
getFormat
- Returns:
- the format
-
getFormatter
Returns the formatter for output, created on first call: for dates a date formatter for the format (or the default date format), for other data types the format string itself.- Returns:
- the formatter, or
nullif no format is defined and the variable is not a date
-
getStringUnit
Returns the unit for display. Units given as ontology URI (http://...) are resolved to their symbol;UNIT_SOLUTION_DEFINEDis shown asdefined by solution.- Returns:
- the unit symbol, or
-if no unit is defined
-
getDefault
- Returns:
- the default
-
getRule
- Returns:
- the rule calculating the value, or
null
-
calculateValue
Evaluates the rule against a var map and sets the result as value (with the checks ofsetValue(Object, FWSimVariable, FWSimFieldContainer)). A rule that is a plain variable name is resolved directly; other rules are evaluated as JEXL script. Without a rule the value is not changed.- Parameters:
aVarMap- var map providing the variables used in the rule- Returns:
- the (new) value
-
evaluate
Evaluates the rule against a var map without changing the value.- Parameters:
aVarMap- var map providing the variables used in the rule- Returns:
- the result of the rule, or the current value if there is no rule
-
evaluate
Evaluates the rule against the var map of this variable without changing the value.- Returns:
- the result of the rule, or the current value if there is no rule
- See Also:
-
toString
-
getStringValue
- Returns:
- the value as string; arrays are formatted as
[v1, v2, ...], a text array with one element as that element
-
toShortString
- Returns:
- the part of the name after the last dot
-
toDebugString
- Returns:
- long debugging string value with all content of the variable
-
toXML
public org.jdom2.Element toXML()Creates the XML element of this variable as used in a solution. The element name is the content type. The value is written as text only forvar/dynvariables (and the rule formgm), otherwise the default value is written as attribute.- Returns:
- the XML element
- See Also:
-
toCalVarXML
Creates acalelement that varies this variable equidistantly between min and max, e.g.<cal id="AirTemperatureSumMaturity" datatype="DOUBLE" target="vAirTemperatureSumMaturity"> <input id="min" datatype="DOUBLE">1000</input> <input id="max" datatype="DOUBLE">2000</input> <input id="count" datatype="INT">21</input> </cal>
The id is the field name without the leadingv(other names get the prefixs).- Parameters:
aMinVal- minimum valueaMaxVal- maximum valueaCount- number of values- Returns:
- the
calelement
-
toCalVarXML
Creates acalelement that varies this variable over a list of values, e.g.<cal id="CropName" datatype="CHAR" target="vCropName"> <input id="values" datatype="CHARARRAY">{wheat,maize}</input> </cal>The id is the field name without the leadingv(other names get the prefixs).- Parameters:
aCommaSeperatedList- comma separated values- Returns:
- the
calelement
-
toOutVarXML
Creates anoutelement that writes this variable to an output, e.g.<out id="AirTemperatureSumMaturity" datatype="DOUBLE" mode="FIRST" rule="vAirTemperatureSumMaturity" />. The id is the field name without the leadingvand without dots.- Parameters:
aMode- aggregation mode, ornull- Returns:
- the
outelement
-
getFieldName
- Returns:
- the name without the name of the owning container;
var,dynandsysvariables are returned unchanged
-
getOptions
- Returns:
- the allowed values from the
optionattribute, ornull
-
getCount
- Returns:
- the zero-based indices of the array elements used by this variable, or
null
-
setCount
Ensures that the index list covers at least aCount elements: if it is shorter, it is replaced by0 .. aCount-1.- Parameters:
aCount- number of array elements- Returns:
- the index list
-
setCount
- Parameters:
aArray- zero-based indices of the array elements used by this variable
-
setFormat
- Parameters:
aFormat- output format, e.g. a number or date pattern
-
setValueAndDefault
public static <F> F setValueAndDefault(Object aObject, FWSimVariable<F> aSimVariable, FWSimFieldContainer aSourceComponent) throws SimValueOutOfRangeException, SimLinkInvalidException Converts a value of any type to the data type of a variable and sets it as value and as default value.- Type Parameters:
F- value type of the variable- Parameters:
aObject- value to set (e.g. a string or a number)aSimVariable- variable to setaSourceComponent- component that wants to set the value, for checking purposes- Returns:
- the value as set, with the correct type
- Throws:
SimValueOutOfRangeException- if the value exceeds min or max and the check level is STRICTSimLinkInvalidException- if the write access is not allowed and the check level is STRICT- See Also:
-
setValue
public static <F> F setValue(Object aObject, FWSimVariable<F> aSimVariable, FWSimFieldContainer aSourceComponent) throws SimValueOutOfRangeException, SimLinkInvalidException Converts a value of any type to the data type of a variable and sets it. Strings are parsed (e.g.{1,2,3}for arrays), numbers are converted between int and double, primitive arrays are boxed. For arrays the count is adjusted to the array length.- Type Parameters:
F- value type of the variable- Parameters:
aObject- value to set (e.g. a string or a number);nullsetsnullaSimVariable- variable to setaSourceComponent- component that wants to set the value, for checking purposes- Returns:
- the value as set, with the correct type
- Throws:
SimValueOutOfRangeException- if the value exceeds min or max and the check level is STRICTSimLinkInvalidException- if the write access is not allowed and the check level is STRICTNumberFormatException- if a string cannot be parsed- See Also:
-
transformDataType
public static Object transformDataType(String aObject, FWSimVariable.DATA_TYPE aDataType) throws NumberFormatException Converts a string into the Java type of a data type. Dates consisting of digits only are interpreted as days since 1970. If possible, usesetValue(Object, FWSimVariable, FWSimFieldContainer)instead.- Parameters:
aObject- string to convertaDataType- target data type- Returns:
- the converted value, or
nullfornull, empty strings and"null" - Throws:
NumberFormatException- if the string cannot be parsed
-
transformDataType
public static Object transformDataType(String aObject, FWSimVariable<?> aSimVariable) throws NumberFormatException Converts a string into the Java type of the data type of a variable. For dates, the format of the variable is used if defined. If possible, usesetValue(Object, FWSimVariable, FWSimFieldContainer)instead.- Parameters:
aObject- string to convertaSimVariable- variable providing data type and format- Returns:
- the converted value, or
nullfornull, empty strings and"null" - Throws:
NumberFormatException- if the string cannot be parsed- See Also:
-
transformDataTypeToDB
Returns the SQL column type for a data type. Arrays are stored as text.- Parameters:
aDataType- the data type- Returns:
- the SQL column type, e.g.
DOUBLE PRECISIONorVARCHAR(250)
-
transformDBDataType
Returns the data type for an SQL column type (by prefix: INT, FLOAT, DOUBLE, DATE, BOOL).- Parameters:
dataType- SQL column type- Returns:
- the data type; CHAR for unknown or empty types
-
transformJavaDataType
Returns the Java type name for a data type, e.g. for code generation.- Parameters:
aDataType- the data type- Returns:
- the Java type name, e.g.
Double[];Datefor DATE,Stringfor all other types
-
transformJavaDataType
Returns the data type for a Java type name, e.g.Integer→ INT,int[]→ INTARRAY.- Parameters:
dataType- Java type name- Returns:
- the data type; CHAR for unknown or empty type names
-
transformContentType
Returns a readable name for a content type, e.g.ConstantorResource.- Parameters:
aContentType- the content type- Returns:
- the readable name; an empty string for content types without name
-
getPrefix
- Returns:
- the naming convention prefix for the content type of this variable (e.g.
cfor constants,sfor states); an empty string if there is none
-
addPrefix
-
check
Checks whether an output variable can be linked to this (input) variable. Currently only the units are compared.- Parameters:
aOutputVar- the output variable to link- Returns:
- an error description, or
nullif no problem was found
-
getSource
- Returns:
- the container (e.g. SimComponent) that owns this variable
-
getVarMap
- Returns:
- the var map this variable belongs to
-
setSource
Sets the owning container, but only if none is set yet. Use with care - should not be used by default.- Parameters:
aComponent- the owning container
-
addOutputLink
Registers a link from this output variable to an input variable.- Parameters:
aFieldName- name of the linked input variable- Throws:
SimLinkInvalidException- if this variable is not an output variable
-
addInputLink
Registers a link from an output variable to this input variable.- Parameters:
aFieldName- name of the linked output variable- Throws:
SimLinkInvalidException- if this variable is not an input variable
-
removeLink
Removes a registered link.- Parameters:
aName- name of the linked variable
-
isInputLinked
- Returns:
trueif this input variable is linked to an output variable- Throws:
SimLinkInvalidException- if this variable is not an input variable
-
isOutputLinked
public boolean isOutputLinked()- Returns:
trueif this is an output variable linked to at least one input variable
-
getRuleComplexity
- Returns:
- the complexity of the rule (e.g. VALUE for a plain variable name), which decides how it is evaluated
-
clone
Creates a shallow copy for another var map: the new variable shares the meta data (name, limits, rule, links, ...) with this variable; only the value reference and the var map are separate.- Parameters:
aVarMap- var map of the copy- Returns:
- the copy
- See Also:
-
deepClone
Creates a copy for another var map with its own copy of the meta data, so that changes of the meta data (e.g. rule, name) do not affect this variable. The value itself is not copied (arrays are shared).- Parameters:
aVarMap- var map of the copy- Returns:
- the copy
-
setContentType
- Parameters:
aContentType- the new content type (changes the shared meta data)
-
createFormFields
public static org.jdom2.Element createFormFields(FWSimVariable<?> aVariable, FWSimVariable.CONTENT_TYPE aComponentContentType, String aDescription, String aFrequence, String aVisible, String aEnabled, boolean aMultipleVarType) Creates the GUI form fields for editing a variable.- Parameters:
aVariable- the variable to editaComponentContentType- content type of the owning container; decides which fields are shown and editableaDescription- description of the form groupaFrequence- frequency of the owning container (only used for the multiple variable form)aVisible- visibility of the group ("true"/"false")aEnabled- whether the fields are editable ("true"/"false")aMultipleVarType- iftrue, the form for several variables in one form is created- Returns:
- the form group element
- See Also:
-
createFormFields
public static org.jdom2.Element createFormFields(String aName, String aDescription, String aContentTypeDefault, String aVisible, String aEnabled, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form fields for a new variable (data type DOUBLE, mode IGNORE, no other values).- Parameters:
aName- name of the new variableaDescription- description of the form groupaContentTypeDefault- preselected content typeaVisible- visibility of the group ("true"/"false")aEnabled- whether the fields are editable ("true"/"false")aComponentContentType- content type of the owning container- Returns:
- the form group element
-
createMultipleFormElement
public static org.jdom2.Element createMultipleFormElement(FWSimVariable<?> aVariable, String aName, String aDescription, String aVisible, String aEnabled, String aContentType, String tModeType, boolean aModeNeeded, String aFrequence, String tDataType, String tUnit, String tMax, String tMin, String tRule, String tDesc, String tDefault, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form group for one variable inside a form with several variables. Field ids are prefixed withSimVariable.<name>..- Parameters:
aVariable- the variable, ornullfor a new oneaName- name of the variableaDescription- not usedaVisible- visibility of the groupaEnabled- whether the fields are editableaContentType- content type (preselected)tModeType- aggregation mode (preselected)aModeNeeded- iftrue, a mode field is shown (for yearly, monthly or complex frequency)aFrequence- not used (the frequency is referenced via the form expression)tDataType- data type (preselected)tUnit- unittMax- maximumtMin- minimumtRule- ruletDesc- description of the variabletDefault- default valueaComponentContentType- content type of the owning container; decides which fields are shown and editable- Returns:
- the form group element
-
createFormElement
public static org.jdom2.Element createFormElement(FWSimVariable<?> aVariable, String aName, String aDescription, String aVisible, String aEnabled, String aContentType, String aModeType, boolean aModeNeeded, String tDataType, String tUnit, String tMax, String tMin, String tRule, String tDesc, String tDefault, FWSimVariable.CONTENT_TYPE aComponentContentType) Creates the GUI form group for editing a single variable. Field ids are prefixed withSimVariable..- Parameters:
aVariable- the variable, ornullfor a new one (then name and data type are editable)aName- name of the variableaDescription- description of the form groupaVisible- visibility of the groupaEnabled- whether the fields are editableaContentType- content type (preselected)aModeType- aggregation mode (preselected)aModeNeeded- iftrue, a mode field is showntDataType- data type (preselected)tUnit- unittMax- maximumtMin- minimumtRule- ruletDesc- description of the variabletDefault- default valueaComponentContentType- content type of the owning container; decides which fields are shown and editable- Returns:
- the form group element
-
updateFields
public void updateFields(org.jdom2.Element aVarElement) Updates the meta data and the value of this variable from an XML element of a solution (same format as forcreateSimVariable(Element, FWSimFieldContainer)). The data type is not changed; if the value does not match it, an error is logged and the data type is derived from the value.- Parameters:
aVarElement- XML element describing the variable
-
updateFields
public static FWSimVariable<?> updateFields(FWSimVariable<?> aVariable, FWObservable aObservable) throws SimLinkInvalidException, SimValueOutOfRangeException Creates or updates a variable from the values of a GUI form (seecreateFormFields(FWSimVariable, CONTENT_TYPE, String, String, String, String, boolean)). Both form layouts are supported: single variable (SimVariable.*) and multiple variables (SimVariable.<name>.*).- Parameters:
aVariable- the variable to update, ornullto create a new one from the form valuesaObservable- the form values- Returns:
- the created or updated variable
- Throws:
SimLinkInvalidException- if the write access is not allowed and the check level is STRICTSimValueOutOfRangeException- if the default value exceeds min or max and the check level is STRICT
-
getFormComponentXML
public org.jdom2.Element getFormComponentXML()Creates a GUI form field for editing the value of this variable. The field type depends on the data type (e.g. double field with limits, date field, choice field for CHAR variables with options). The value must not benull.- Returns:
- the form field element
-
getDateFormatter
Returns a date formatter for a pattern. A new formatter is created on every call; the formatter of the variable is created once and kept in its meta data, so only the GUI and XML output call this repeatedly. (A never assigned cache field was removed: one cached formatter would ignore the pattern.)- Parameters:
aPattern- date pattern (seeDateTimeFormatter) orEPOCH_DAY;nullfor the default patterndd.MM.yyyy- Returns:
- the date formatter
-
equals
Two variables are equal if they have the same name.Note:
Object.hashCode()is deliberately NOT overridden (identity): variables are used as keys of hash maps in which variables of the same name from different simulations must stay separate (e.g. chart datasets per simulation); a name based hash code would merge them. -
toHTMLTablestring
Formats this variable as HTML table row with content type, name, description, data type, unit, min, max and value (or default value), e.g. for documentation pages.- Returns:
- the HTML table row
-