As part of Structure101 it is possible to check for changes in the key structural measures prior to publishing, and if the key measures are found to be increasing, an exception can be raised to break the build and hence abort the publish to the repository.
The check-key-measures operation is used when you wish to ensure your key structural measures do not increase over time.
The default behaviour simply checks if the key measure value has increased, logs a message if it has and fails the build if the corresponding fail-on-xxxx argument is true.
Alternatively, the operation can check for new items in the measures and/or existing items that have got worse. This behaviour is enabled by setting to true the arguments failOnNew and failOnGotWorse respectively.
The failOnNew behaviour checks for new fat or tangled items. So even when more items were fixed than added, hence the total count has reduced, this setting will report failure because of the new fat or tangled items.
The failOnGotWorse behaviour checks for an increase in an existing fat or tangled items measure. For example, a fat class has too many dependencies between its class members. The default threshold value is 120. Any class with more inter-dependencies will be counted as fat. Once in the list, a fat class can get worse with the addition of more inter-dependencies.
Example XML file to perform the operation:
<?xml version="1.0" encoding="UTF-8"?>
<headless version="1.0">
<operations>
<operation type="check-key-measures">
<argument name="output-file" value="const(THIS_FILE)/target/structure101report/key-measures.xml"/>
<argument name="output-file-for-snapshot" value="const(THIS_FILE)/target/structure101report/snapshot-key-measures.xml"/>
<argument name="baseline" value="1.0.0"/>
<argument name="fail-on-architecture-violations" value="true"/>
<argument name="fail-on-feedback-dependencies" value="false"/>
<argument name="fail-on-spec-violation-dependencies" value="true"/>
<argument name="fail-on-spec-item-violations" value="true"/>
<argument name="fail-on-total-problem-dependencies" value="false"/>
<argument name="fail-on-biggest-class-tangle" value="false"/>
<argument name="fail-on-tangled-package" value="false"/>
<argument name="fail-on-fat-package" value="false"/>
<argument name="fail-on-fat-class" value="false"/>
<argument name="fail-on-fat-method" value="false"/>
<argument name="identifier-on-increase" value="Structure101 Key Measure increased"/>
<argument name="failOnNew" value="true"/>
<argument name="failOnGotWorse" value="true"/>
<argument name="detailed" value="true"/>
</operation>
</operations>
<arguments>
<argument name="local-project" value="C:\Documents and Settings\user\project.java.hsp">
<override attribute="classpath" value="C:\classes-to-parse"/>
</argument>
<argument name="repository" value="C:\repository"/>
<argument name="project" value="project"/>
</arguments>
</headless>
Available arguments include:
| Argument | Required | Description |
|---|---|---|
| repository | yes | The path to the Structure101 Studio repository root directory, e.g. c:/repository, /home/usr/x/repository, or, if remote, http://<servernameorip><:portno>/s101cpp/data. |
| project | yes | The name of the project in the repository to compare against. |
| local-project | yes | See project-spec. |
| useProjectFileSpec | no | If set to true then the structure spec in the specified project file is used instead of the repository structure spec. Default value is true. |
| useProjectFileDiagrams | no | If set to true then diagrams in the specified project file are used instead of repository diagrams. Default value is true. |
| output-file | no | File to which violations to key measures are written in XML format. This argument can be a relative or absolute path. |
| output-file-for-snapshot | no | File to which the key measures of the baseline snapshot are written in XML format. This argument can be a relative or absolute path. |
| baseline | no | If baseline is entered, then the snapshot with that label will be used to determine which Key Measures have changed. If not entered, then the baseline defaults to the latest good snapshot. |
| fail-on-tangled-package | no | When set to true, a runtime exception will be thrown if the number of tangled packages increases. Default value is true. |
| fail-on-fat-package | no | When set to true, a runtime exception will be thrown if the number of fat packages increases. Default value is true. |
| fail-on-fat-class | no | When set to true, a runtime exception will be thrown if the number of fat classes increases. Default value is true. |
| fail-on-fat-method | no | When set to true, a runtime exception will be thrown if the number of fat methods increases. Default value is true. |
| fail-on-biggest-class-tangle | no | When set to true, a runtime exception will be thrown if the number of classes in the biggest class tangle increases. Default value is true. |
| fail-on-architecture-violations | no | When set to true, a runtime exception will be thrown if the number of violations to the defined architecture increases. Default value is true. |
| fail-on-feedback-dependencies | no | When set to true, a runtime exception will be thrown if the number of feedback dependencies increases. Default value is true. |
| fail-on-spec-violation-dependencies | no | When set to true, a runtime exception will be thrown if the number of dependencies violating the structure spec increases. Default value is true. |
| fail-on-spec-item-violations | no | When set to true, a runtime exception will be thrown if the number of items violating the spec (i.e. items in the model that are not covered by the spec - 'red' cells) increases. Default value is true. |
| fail-on-total-problem-dependencies | no | When set to true, a runtime exception will be thrown if the number of problem dependencies (total feedback + spec violations) increases. Default value is true. |
| failOnNew | no | When set to true, new fat or tangled items are logged and the build is failed if the corresponding fail-on-xxxx argument is true. Default value is false.. |
| failOnGotWorse | no | When set to true, any increases in the measure of existing fat or tangled items are logged and the build is failed if the corresponding fail-on-xxxx argument is true. Default value is false. |
| detailed | no | When set to true then the list of elemental issues for each check that fails will be logged. Default value is false. |
Note: For all 'fail-on' arguments, the default value is true. If a 'fail-on' argument is not specified and the corresponding value increases a runtime exception will be thrown to break your build.
Important: Requires a valid license file in the current directory with a build license, or the -licensedirectory parameter to be set.