Class FWSimVariable<T>

java.lang.Object
net.simplace.sim.util.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

public class FWSimVariable<T> extends Object
A typed simulation variable. Every value that is exchanged in a SIMPLACE simulation - component inputs, states, rates and outputs, resource values, system values like the current date, management actions or parameters of a solution - is held in a FWSimVariable.

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
  • Field Details

    • UNIT_SOLUTION_DEFINED

      public static final String 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 with setUnitFrom(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 methods createSimVariable(...) instead.

      The name may contain an index specification that selects array elements, e.g. name|1-3, name!2 or name_${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 specification
      aDescription - description
      aRule - rule calculating the value, or null
      aDataType - data type
      aContentType - content type
      aUnit - unit
      aValue - initial value
      aMin - minimum, or null
      aMax - maximum, or null
      aDefault - default value
      aCount - indices of array elements, used if the name contains no index specification
      aModeType - aggregation mode, or null
      aVarMap - var map the variable belongs to; provides the checker of the session
      aSourceSimComponent - 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 variable
      aVarMap - 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 attributes id, datatype, unit, description, rule (for cal: target), min, max, default, mode, count, format and option are evaluated. The value is the element text, value children (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 variable
      aFWSimFieldContainer - container (e.g. component) the variable belongs to; may be null
      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 in createVariables() of a component.
      Parameters:
      aName - name (id) of the variable
      aDesc - description
      aDataType - data type
      aContentType - content type, e.g. input, state, rate
      aUnit - unit, e.g. kg/ha
      aMin - minimum allowed value, or null
      aMax - maximum allowed value, or null
      aDefault - default and initial value, or null
      aSourceSimComponent - 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 type out. Its value is calculated from the rule.
      Parameters:
      aName - name (id) of the variable
      aDesc - description
      aRule - rule calculating the value, usually the name of the variable to write
      aDataType - data type
      aUnit - unit
      aOutputFormat - output format, e.g. a number or date pattern
      aDefault - default value, or null
      aModeType - aggregation mode if the output frequency is not daily
      aTarget - 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 (see FWSimVariable(String, String, String, DATA_TYPE, CONTENT_TYPE, String, Object, Number, Number, Object, Integer[], MODE_TYPE, FWSimVarMap, FWSimFieldContainer))
      aDesc - description
      aRule - rule calculating the value, or null
      aDataType - data type
      aContentType - content type (input, output, etc.)
      aUnit - unit
      aValue - initial value (internal use, not for initializing)
      aMin - minimum, or null
      aMax - maximum, or null
      aDefault - default value, used when initializing constants or inputs
      aCount - indices of array elements used by this variable, or null
      aModeType - aggregation mode, or null
      aVarMap - 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

      public void fillMetaDataFromSource(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 one count index), 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:
      true if the variable holds numbers (int or double, also arrays)
    • hasRule

      public boolean hasRule()
      Returns:
      true if the value is calculated by a rule
    • isDouble

      public boolean isDouble()
      Returns:
      true if the variable is a double, a double array or a double matrix
    • isInt

      public boolean isInt()
      Returns:
      true if the variable is an int or an int array
    • isBoolean

      public boolean isBoolean()
      Returns:
      true if the variable is a boolean
    • isString

      public boolean isString()
      Returns:
      true if the variable is a text (CHAR, CHARARRAY or FILE)
    • isDate

      public boolean isDate()
      Returns:
      true if the variable is a date (not a date array)
    • isArray

      public boolean isArray()
      Returns:
      true if the variable is an array or matrix (double, int or text; not DATEARRAY)
    • isOutputContent

      public boolean isOutputContent()
      Returns:
      true if the variable is not an input variable (see isInputContent())
    • isInputContent

      public boolean isInputContent()
      Returns:
      true if the content type is input, constant or privat
    • isMeasData

      public boolean isMeasData()
      Returns:
      true if the value comes from measured data, i.e. its source is a resource
    • getDescription

      public String getDescription()
      Returns:
      the description of this variable
    • getOrder

      public String getOrder()
      Returns:
      the order of this variable (used for sorting)
    • getDataType

      public FWSimVariable.DATA_TYPE getDataType()
      Returns:
      the data type
    • getContentType

      public FWSimVariable.CONTENT_TYPE getContentType()
      Returns:
      the content type
    • getCategory

      public FWSimVariable.VARIABLE_CATEGORY getCategory()
      Derives the category from the content type. Variables of type var, dyn or sys are categorised as sys if they are internal variables of the var map, otherwise as var.
      Returns:
      the category of this variable
    • getModeType

      public FWSimVariable.MODE_TYPE getModeType()
      Returns:
      the aggregation mode, or null
    • getMax

      public Number getMax()
      Returns:
      the maximum allowed value (for dates: milliseconds since 1970), or null
    • getMin

      public Number getMin()
      Returns:
      the minimum allowed value (for dates: milliseconds since 1970), or null
    • getValue

      public T getValue()
      Returns the value. This is the standard way to read a variable.
      Returns:
      the value
    • getArrayValue

      public Number getArrayValue(int aIndex)
      Returns one element of a double or int array.
      Parameters:
      aIndex - zero-based index of the element
      Returns:
      the element, or null if the variable is not a double or int array
    • getMatrixValue

      public Double getMatrixValue(int aXIndex, int aYIndex)
      Returns one element of a double matrix.
      Parameters:
      aXIndex - zero-based row index
      aYIndex - zero-based column index
      Returns:
      the element, or null if the variable is not a DOUBLEMATRIX
    • forceDoubleMapValue

      public TreeMap<Double,Double> forceDoubleMapValue() throws SimFieldTypeException
      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 are true if their int value is 1, strings are parsed with StringHelper.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

      public String 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" for null)
    • setDefaultValue

      public void setDefaultValue()
      Replaces the value with the default value, even if the default is null. 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 is null. Unlike setDefaultValue(), this works for all content types.
    • setVarMap

      public void setVarMap(FWSimVarMap aFwSimvarMap)
      Parameters:
      aFwSimvarMap - the var map this variable belongs to
    • setModeType

      public void setModeType(FWSimVariable.MODE_TYPE aModeType)
      Parameters:
      aModeType - the new aggregation mode (changes the shared meta data)
    • setRule

      public void setRule(String aRule)
      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

      public void setName(String aNewName)
      Renames the variable. Only used by generators.
      Parameters:
      aNewName - the new name
    • changeDefaultValue

      public void changeDefaultValue(T aValue)
      Changes the default value (the current value is not changed).
      Parameters:
      aValue - the new default value
    • setNull

      public void setNull(FWSimFieldContainer aSource)
      Sets the value to null. 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

      public void setValue(T aValue, FWSimFieldContainer aSource)
      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 set
      aSource - component that wants to set the value, for checking purposes
      Throws:
      SimValueOutOfRangeException - if the value exceeds min or max and the check level is STRICT
      SimLinkInvalidException - 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 taken
      aSource - component that wants to set the value, for checking purposes
      Throws:
      SimValueOutOfRangeException - if the value exceeds min or max and the check level is STRICT
      SimLinkInvalidException - if the write access is not allowed and the check level is STRICT
      See Also:
    • addValue

      public void addValue(T aValue, FWSimFieldContainer aSource) throws SimValueOutOfRangeException
      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 in setValue(Object, FWSimFieldContainer). The write access of the source is not checked.
      Parameters:
      aValue - the value to add
      aSource - 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 added
      aSource - 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 in setValue(Object, FWSimFieldContainer). The write access of the source is not checked.
      Parameters:
      aValue - the factor
      aSource - 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 element
      aValue - the value to set
      aSource - component that sets the value (currently not used)
      Throws:
      SimValueOutOfRangeException - if the value exceeds min or max and the check level is STRICT
      SimFieldTypeException - 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 element
      aValue - the value to set
      aSource - component that sets the value (currently not used)
      Throws:
      SimValueOutOfRangeException - declared but not thrown
      SimFieldTypeException - if the variable is not an array
    • getName

      public String getName()
      Returns:
      the full name, including the component name for component variables (e.g. Component.variable)
    • getInternalName

      public String getInternalName()
      Returns:
      the name without the component name, i.e. the part after the first dot
    • getUnit

      public String getUnit()
      Returns:
      the unit
    • isUnitSolutionDefined

      public boolean isUnitSolutionDefined()
      Returns:
      true if the unit is UNIT_SOLUTION_DEFINED, i.e. not yet taken from the solution
    • setUnitFrom

      public FWSimVariable<T> setUnitFrom(FWSimVariable<?> aInput)
      Lets an output of a generic component take the unit of one of its inputs (#60), e.g. the average of iValue has the unit of iValue. The unit is set to UNIT_SOLUTION_DEFINED and replaced by the unit of the input once the input is linked in the solution. Call it in createVariables() after both variables were created.
      Parameters:
      aInput - the input of the same component (usually with unit UNIT_SOLUTION_DEFINED)
      Returns:
      this variable
    • getUnitSource

      public FWSimVariable<?> getUnitSource()
      Returns:
      the input whose unit this output takes (see setUnitFrom(FWSimVariable)), or null
    • adoptUnitFrom

      public boolean adoptUnitFrom(FWSimVariable<?> aSource)
      Takes the unit of another variable if this unit is UNIT_SOLUTION_DEFINED and 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 with setUnitFrom(FWSimVariable))
      Returns:
      true if the unit was taken
    • getFormat

      public String getFormat()
      Returns:
      the format
    • getFormatter

      public Object 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 null if no format is defined and the variable is not a date
    • getStringUnit

      public String getStringUnit()
      Returns the unit for display. Units given as ontology URI (http://...) are resolved to their symbol; UNIT_SOLUTION_DEFINED is shown as defined by solution.
      Returns:
      the unit symbol, or - if no unit is defined
    • getDefault

      public T getDefault()
      Returns:
      the default
    • getRule

      public String getRule()
      Returns:
      the rule calculating the value, or null
    • calculateValue

      public Object calculateValue(FWSimVarMap aVarMap)
      Evaluates the rule against a var map and sets the result as value (with the checks of setValue(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

      public Object evaluate(FWSimVarMap aVarMap)
      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

      public Object 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

      public String toString()
      Overrides:
      toString in class Object
      See Also:
    • getStringValue

      public String getStringValue()
      Returns:
      the value as string; arrays are formatted as [v1, v2, ...], a text array with one element as that element
    • toShortString

      public String toShortString()
      Returns:
      the part of the name after the last dot
    • toDebugString

      public String 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 for var/dyn variables (and the rule for mgm), otherwise the default value is written as attribute.
      Returns:
      the XML element
      See Also:
    • toCalVarXML

      public org.jdom2.Element toCalVarXML(String aMinVal, String aMaxVal, Integer aCount)
      Creates a cal element 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 leading v (other names get the prefix s).
      Parameters:
      aMinVal - minimum value
      aMaxVal - maximum value
      aCount - number of values
      Returns:
      the cal element
    • toCalVarXML

      public org.jdom2.Element toCalVarXML(String aCommaSeperatedList)
      Creates a cal element 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 leading v (other names get the prefix s).
      Parameters:
      aCommaSeperatedList - comma separated values
      Returns:
      the cal element
    • toOutVarXML

      public org.jdom2.Element toOutVarXML(String aMode)
      Creates an out element 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 leading v and without dots.
      Parameters:
      aMode - aggregation mode, or null
      Returns:
      the out element
    • getFieldName

      public String getFieldName()
      Returns:
      the name without the name of the owning container; var, dyn and sys variables are returned unchanged
    • getOptions

      public String[] getOptions()
      Returns:
      the allowed values from the option attribute, or null
    • getCount

      public Integer[] getCount()
      Returns:
      the zero-based indices of the array elements used by this variable, or null
    • setCount

      public Integer[] setCount(int aCount)
      Ensures that the index list covers at least aCount elements: if it is shorter, it is replaced by 0 .. aCount-1.
      Parameters:
      aCount - number of array elements
      Returns:
      the index list
    • setCount

      public void setCount(Integer[] aArray)
      Parameters:
      aArray - zero-based indices of the array elements used by this variable
    • setFormat

      public void setFormat(String aFormat)
      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 set
      aSourceComponent - 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 STRICT
      SimLinkInvalidException - 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); null sets null
      aSimVariable - variable to set
      aSourceComponent - 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 STRICT
      SimLinkInvalidException - if the write access is not allowed and the check level is STRICT
      NumberFormatException - 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, use setValue(Object, FWSimVariable, FWSimFieldContainer) instead.
      Parameters:
      aObject - string to convert
      aDataType - target data type
      Returns:
      the converted value, or null for null, 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, use setValue(Object, FWSimVariable, FWSimFieldContainer) instead.
      Parameters:
      aObject - string to convert
      aSimVariable - variable providing data type and format
      Returns:
      the converted value, or null for null, empty strings and "null"
      Throws:
      NumberFormatException - if the string cannot be parsed
      See Also:
    • transformDataTypeToDB

      public static String transformDataTypeToDB(FWSimVariable.DATA_TYPE aDataType)
      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 PRECISION or VARCHAR(250)
    • transformDBDataType

      public static FWSimVariable.DATA_TYPE transformDBDataType(String dataType)
      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

      public static String transformJavaDataType(FWSimVariable.DATA_TYPE aDataType)
      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[]; Date for DATE, String for all other types
    • transformJavaDataType

      public static FWSimVariable.DATA_TYPE transformJavaDataType(String dataType)
      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

      public static String transformContentType(FWSimVariable.CONTENT_TYPE aContentType)
      Returns a readable name for a content type, e.g. Constant or Resource.
      Parameters:
      aContentType - the content type
      Returns:
      the readable name; an empty string for content types without name
    • getPrefix

      public String getPrefix()
      Returns:
      the naming convention prefix for the content type of this variable (e.g. c for constants, s for states); an empty string if there is none
    • addPrefix

      public String addPrefix(String aFieldName)
      Parameters:
      aFieldName - field name without prefix
      Returns:
      the field name with the prefix of this variable's content type
      See Also:
    • check

      public String check(FWSimVariable<?> aOutputVar)
      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 null if no problem was found
    • getSource

      public FWSimFieldContainer getSource()
      Returns:
      the container (e.g. SimComponent) that owns this variable
    • getVarMap

      public FWSimVarMap getVarMap()
      Returns:
      the var map this variable belongs to
    • setSource

      public void setSource(FWSimFieldContainer aComponent)
      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

      public void addOutputLink(String aFieldName) throws SimLinkInvalidException
      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

      public void addInputLink(String aFieldName) throws SimLinkInvalidException
      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

      public void removeLink(String aName)
      Removes a registered link.
      Parameters:
      aName - name of the linked variable
    • isInputLinked

      public boolean isInputLinked() throws SimLinkInvalidException
      Returns:
      true if this input variable is linked to an output variable
      Throws:
      SimLinkInvalidException - if this variable is not an input variable
    • isOutputLinked

      public boolean isOutputLinked()
      Returns:
      true if this is an output variable linked to at least one input variable
    • getRuleComplexity

      public JexlRuleScript.COMPLEXITY getRuleComplexity()
      Returns:
      the complexity of the rule (e.g. VALUE for a plain variable name), which decides how it is evaluated
    • clone

      public FWSimVariable<T> 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.
      Parameters:
      aVarMap - var map of the copy
      Returns:
      the copy
      See Also:
    • deepClone

      public FWSimVariable<T> 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. 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

      public void setContentType(FWSimVariable.CONTENT_TYPE aContentType)
      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 edit
      aComponentContentType - content type of the owning container; decides which fields are shown and editable
      aDescription - description of the form group
      aFrequence - 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 - if true, 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 variable
      aDescription - description of the form group
      aContentTypeDefault - preselected content type
      aVisible - 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 with SimVariable.<name>..
      Parameters:
      aVariable - the variable, or null for a new one
      aName - name of the variable
      aDescription - not used
      aVisible - visibility of the group
      aEnabled - whether the fields are editable
      aContentType - content type (preselected)
      tModeType - aggregation mode (preselected)
      aModeNeeded - if true, 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 - unit
      tMax - maximum
      tMin - minimum
      tRule - rule
      tDesc - description of the variable
      tDefault - default value
      aComponentContentType - 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 with SimVariable..
      Parameters:
      aVariable - the variable, or null for a new one (then name and data type are editable)
      aName - name of the variable
      aDescription - description of the form group
      aVisible - visibility of the group
      aEnabled - whether the fields are editable
      aContentType - content type (preselected)
      aModeType - aggregation mode (preselected)
      aModeNeeded - if true, a mode field is shown
      tDataType - data type (preselected)
      tUnit - unit
      tMax - maximum
      tMin - minimum
      tRule - rule
      tDesc - description of the variable
      tDefault - default value
      aComponentContentType - 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 for createSimVariable(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 (see createFormFields(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, or null to create a new one from the form values
      aObservable - the form values
      Returns:
      the created or updated variable
      Throws:
      SimLinkInvalidException - if the write access is not allowed and the check level is STRICT
      SimValueOutOfRangeException - 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 be null.
      Returns:
      the form field element
    • getDateFormatter

      public FWSimVariable.DateFormatter getDateFormatter(String aPattern)
      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 (see DateTimeFormatter) or EPOCH_DAY; null for the default pattern dd.MM.yyyy
      Returns:
      the date formatter
    • equals

      public boolean equals(Object aObj)
      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.

      Overrides:
      equals in class Object
    • toHTMLTablestring

      public String 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