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. Any alphanumerical value is accepted for this attribute as long as it is at least two characters and starts with a letter.
targetArtefactTypes (optional) defines the types of artifacts this measure applies to. For more information about artifact types, consult Artifact Types.

storedIf (optional, default: -) defines whether a derived or base measure’s value is stored in the database or discarded if the condition result is equal or higher than one. For instance, values are stored only if there is at least a ticket in the project.

<Measure targetArtefactTypes="FILE" measureId="TESTS_POINTS" defaultValue="-1" storedIf="APP(HAS_TICKETS)" />

It is possible to use the storedIf attribute in a Measure element for base (non computed) measures, see the example above. However, keep in mind that the "Apply changes" and/or "Reapply model" functions can be disturbed if the stored values do not correspond to those in the analysis model.

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: 0) 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 artifact is relaxed of excluded. Note that only one measure per artifact 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:
  pattern, tag::format[] accepts any Java DecimalFormat. Refer to http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html for more information. end::format[] tag::counting[] the regular expression pattern used to perform the match with. end::counting[]
  
  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:
  pattern, tag::format[] accepts any Java DecimalFormat. Refer to http://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html for more information. end::format[] tag::counting[] the regular expression pattern used to perform the match with. end::counting[]
  
  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 (mandatory) defines the types of artifacts this computation applies to. For more information about artifact types, consult Artifact Types.
stored (optional, default: true) defines whether a derived measure’s value is stored in the database (true) or discarded (false) after an analysis.

storedIf (optional, default: -) defines whether a derived or base measure’s value is stored in the database or discarded if the condition result is equal or higher than one.

<Package storedIf="APP(HAS_TESTS)">
    <Measure measureId="TESTS_OK" defaultValue="-1">
       <Computation targetArtefactTypes="FOLDER" result="COUNT TEST FROM TREE WHERE STATUS=OK" />
       <Computation targetArtefactTypes="APPLICATION" storedIf="1" result="COUNT TEST FROM TREE WHERE STATUS=OK" />
    </Measure>
</Package>

storedIf attribute works in a recursive manner, from Computation element to the highest level parent. For the artifact type "FOLDER" storedIf is checked at Computation level, then at Measure and finally at Package level. While for the "APPLICATION" artifact, the check stops at Computation level, since the attribute is present there. In both cases the measure is stored.

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 artifact 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>