Measures

The Measure element defines the semantics of a single measure. From a technical standpoint, a measure is merely a mapping between the information provided by the Data Provider and known Squore elements.

Base Measures only define the measure name and identifier, whereas Derived Measures define how they are computed from other measures. A Measure without computation is a base measure. The following two examples show how the SLOC (Source Lines Of Code) base measure and the COMR (Comment Rate) derived measure are defined:

<Measure measureId="SLOC" targetArtefactTypes="APPLICATION;FILE" defaultValue="1" />
<Measure measureId="COMR" defaultValue="0">
	<Computation stored="true" targetArtefactTypes="APPLICATION;FOLDER;FILE;FUNCTION;CLASS;PROGRAM" result="(CLOC+MLOC)*100/(SLOC+CLOC)" />
</Measure>

Supported attributes for Measure element

  • measureId (mandatory) is the unique identifier of the measure, as used in the properties files[1]. Any alphanumerical value is accepted for this attribute as long as it is at least two characters and starts with a letter.

  • targetArtefactTypes is the type of artefact targeted by the measure. For more information about artefact types, consult Artefact Types.

  • excludingTypes allows refining targetArtefactTypes to exclude certain types that may have been included via an alias.

    You can for example specify that a metric exists for all JAVA types except for JAVA_INTERFACE with the following syntax:

    <Measure measureId="TEST_COVERAGE" defaultValue="-1">
	<Computation targetArtefactTypes="PACKAGES;JAVA" excludingTypes="JAVA_INTERFACE" result="IF(IS_DP_OK(JACOCO),TST_COV,-1)" />
</Measure>

  • defaultValue (optional, default: not set) sets the default value to be used if no value is found for this metric.

  • usedForRelaxation (optional, default: false) indicates that the measure is used in this model to indicate whether an artefact is relaxed of excluded. Note that only one measure per artefact type in your model can use this attribute.

  • suffix (optional, default: empty) is the label displayed after the value of the metric in the UI

  • dataBounds (optional, default: none) allows specifying which range of values should be considered valid for this measure (currently this applies to the Indicator Tree and the Measures tab only).

  • invalidValue (optional, default: -) is the text that should be displayed when an invalid value is set for the measure (currently this applies to the Indicator Tree and the Measures tab only).

  • noValue (optional, default: ?) is the text displayed when no value exists for this metric in the database (currently this applies to the Indicator Tree and the Measures tab only).

  • format (optional, default: NUMBER) is the format used to display the value of the measure in the UI. Accepted values are:

    • NUMBER which accepts the following additional parameters when defined:

      • decimals (optional, default: 0) is the number of decimals places to be used for displaying values.

      • roundingMode (optional, default: HALF_EVEN) defines the behaviour used for rounding the numerical values displayed. The supported values are:

        • CEILING to round towards positive infinity.

        • DOWN to round towards zero.

        • FLOOR to round towards negative infinity.

        • HALF_DOWN to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round down.

        • HALF_EVEN to round towards the "nearest neighbour" unless both neighbours are equidistant, in which case, round towards the even neighbour.

        • HALF_UP to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round up.

        • UP to round away from zero.

        For more examples of rounding mode, consult http://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html

    • PERCENT which accepts the following additional parameters when defined:

      • decimals (optional, default: 0) is the number of decimals places to be used for displaying values.

      • roundingMode (optional, default: HALF_EVEN) defines the behaviour used for rounding the numerical values displayed. The supported values are:

        • CEILING to round towards positive infinity.

        • DOWN to round towards zero.

        • FLOOR to round towards negative infinity.

        • HALF_DOWN to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round down.

        • HALF_EVEN to round towards the "nearest neighbour" unless both neighbours are equidistant, in which case, round towards the even neighbour.

        • HALF_UP to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round up.

        • UP to round away from zero.

        For more examples of rounding mode, consult http://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html

    • ENUM which requires the following additional parameter when defined:

      • enumId (mandatory) to define the ID of the enumeration (Enumerations).

    • BOOLEAN

    • MAN_DAYS

    • MAN_HOURS

    • MAN_MINUTES

    • MAN_SECONDS

    • MAN_MILLISECONDS

    • DAYS

    • HOURS

    • MINUTES

    • SECONDS

    • MILLISECONDS

    • INTEGER which accepts the following additional parameter when defined:

      • roundingMode (optional, default: HALF_EVEN) defines the behaviour used for rounding the numerical values displayed. The supported values are:

        • CEILING to round towards positive infinity.

        • DOWN to round towards zero.

        • FLOOR to round towards negative infinity.

        • HALF_DOWN to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round down.

        • HALF_EVEN to round towards the "nearest neighbour" unless both neighbours are equidistant, in which case, round towards the even neighbour.

        • HALF_UP to round towards "nearest neighbour" unless both neighbours are equidistant, in which case round up.

        • UP to round away from zero.

        For more examples of rounding mode, consult http://docs.oracle.com/javase/8/docs/api/java/math/RoundingMode.html

    • DATE | TIME | DATETIME which accepts the following additional parameters when defined:

      • dateStyle (optional, default: DEFAULT) : the date formatting style, used when the displayType is one of DATE or DATETIME.

        • SHORT is completely numeric, such as 12.13.52 or 3:30pm.

        • MEDIUM is longer, such as Jan 12, 1952.

        • DEFAULT is MEDIUM.

        • LONG is longer, such as January 12, 1952 or 3:30:32pm.

        • FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.

      • timeStyle (optional, default: DEFAULT): the time formatting style, used when the displayType is one of DATETIME or TIME. See above for available styles.

Supported attributes for Computation element

  • targetArtefactTypes is the type of artefact targeted by this definition. For more information about artefact types, consult Artefact Types.

  • stored (optional, default: true) defines whether a derived measure’s value is stored in the database (true) or discarded (false) after an analysis.

  • result specifies how the measure is computed from other metrics values. Identifiers used in the result are measureIds, and the syntax is described in Expressions Syntax.

The measure defined is then used with its identifier, prefixed with B. for base measures, or prefixed with D. for derived measures. The following example shows the use of a derived measure for a computation:

<Computation targetArtefactTypes="APPLICATION;FOLDER;FILE;CLASS;FUNCTION" result="(D.MET_OKR+D.RULE_OKR)/2" />

Inheritance

Analysis models support inheritance and overriding of metrics according to the following rules:

  • If a metric is defined twice for a type, the first definition takes priority for this artefact type. An INFO message is displayed in the Validator to inform you that a definition is overridden by another one.

  • A metric definition for a specific type overrides a metric definition for a more generic type (typically an alias).

As a result, the following definitions are allowed in your Bundle.xml:

  • Specifying a different computation for one subtype

    <ArtefactType id="MODULES" heirs="FUNCTION" />
<ArtefactType id="FUNCTION" heirs="C_MODULES;PHP_MODULES;JAVA_MODULES" />
<Measure measureId="VG" defaultValue="1">
	<Computation targetArtefactTypes="MODULES" result="CCN+TERN+OREL+ANTH+CABL-(CASE+DEF)" />
	<Computation targetArtefactTypes="PHP_MODULES" result="CCN+TERN+OREL+ANTH" />
</Measure>

  • Overriding a computation imported from another file by specifying it before the file import

    <?xml version="1.0" encoding="UTF-8"?>
<Bundle xmlns:xi="http://www.w3.org/2001/XInclude">
(...)
	<Measure measureId="COMR" defaultValue="0">
		<Computation targetArtefactTypes="CODE" result="IF(ELOC+CLOC=0,-1,(CLOC+MLOC)/(ELOC+CLOC))" />
	</Measure>
	<xi:include href="../../Shared/basic_definitions/comr.xml" />
</Bundle>
1. See for more information about unique identifiers.