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>

The attributes allowed for the Measure element are as follows:

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 the section called “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.
stored (optional, default: true) defines whether a base measure's value is stored in the database (true) or discarded (false) after an analysis.
suffix (optional, default: empty) is the label displayed after the value of the metric in the UI (currently this applies to the Indicator Tree and the Measures tab only).
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. Each supported format has additional parameters, as described below:
```
- format="NUMBER": (default)
   + pattern="Java Number Pattern"
   + decimals=""
   + roundingMode=""

- format="PERCENT":
   + decimals=""
   + roundingMode=""

- format="INTEGER":
   + roundingMode=""

- format="DATE|TIME|DATETIME":
   + pattern="Java Date Pattern"
   + dateStyle="" (only for DATE and DATETIME)
   + timeStyle="" (only for TIME and DATETIME)
```
- pattern accepts any Java DecimalFormat or SimpleDate Pattern. Refer to http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html and http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html for more information.
- 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/6/docs/api/java/math/RoundingMode.html.
- 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.

The attributes allowed for the Computation element are as follows:

targetArtefactTypes is the type of artefact targeted by this definition. For more information about artefact types, consult the section called “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 Chapter 5, Computation 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" />

Tip: 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 overriden 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 sub-type

<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" />

^[1]See the section called “Descriptions” for more information about unique identifiers.

Prev	Up	Next
Artefact Types	Home \| ToC	Rules