Sonar Integration

Description and Documentation


hello2morrow provides an integration between Sonargraph and the quality management umbrella tool "Sonar". The similarity of the names is just a random incident. This integration allows to transfer analysis data from Sonargraph to Sonar automatically and to display these data in the Sonar dashboard and detailed pages. The integration is based on a Sonar plugin.

Usage and Installation

If you plan to use Sonar with ANT, please have a look at the updated documentation of Sonargraph (version 7.1.10 or higher). You will find the documentation in the doc subdirectory of the Sonargraph installation.

  1. You need a license to use the Sonargraph-Sonar plugin. You can either use our free Sonar plugin license or a regular Sonargraph-Build (either Sonargraph-ArchitectBuild or Sonargraph-QualityBuild) license. If you want to obtain a free Sonar plugin license, you first need to log in and then follow this link to request a license key. If you don't have an account here please register first. The license will be sent to you by email. Make sure to check your spam filter if you do not receive a license file a few minutes after you requested it.
    The regular Sonargraph-ArchitectBuild or Sonargraph-QualityBuild license is a commercial product and can be purchased on this website.
  2. Download the plugin jar file and copy it into the extensions/plugins directory of your Sonar installation. The plugin requires version 1.11 of Sonar or higher (check compatibility matrix at the download page). Please note that you will need the plugin version 3.0.2 or higher for Sonargraph 7.1.3 or higher.
  3. Add the hello2morrow Maven repository to the repository list in your Maven setting.xml file:
  4. Restart your Sonar server.
  5. Store the file with the license key (either the special Sonargraph-Sonar plugin license or the one which additionally enables Sonargraph-Build) on your build server so that it can be accessed by the build process. If you have an activation code you can skip this step.
  6. The Sonar (Codehaus) goal should be executed after the entire build activities have been completed. The Sonargraph-Sonar integration requires to execute two goals in a sequence. The first example is for Sonargraph-Architect:
      mvn -Dsonargraph.prepareForSonar=true
        -Dsonargraph.license=<license-path> (or -Dsonargraph.activationCode=<activation code>)
      mvn sonar:sonar
    For Sonargraph-Quality you would use:
      mvn -Dsonargraph.prepareForSonar=true
        -Dsonargraph.license=<license-path> (or -Dsonargraph.activationCode=<activation code>)
      mvn sonar:sonar
    As a result, you should now at least see the Sonargraph structure section in the Sonar (Codehaus) dashboard. If you are using a regular Sonargraph-Build license you should also see the Sonargraph architecture section in the Sonar (Codehaus) dashboard. If you get "Cannot open" errors during the build, you can safely ignore them, if they are associated with a module with pom packaging.
  7. If you are using Sonar 2.4 or higher you have to explicitely switch on the Sonargraph dashboard elements in the Sonar dashboard. Dashboard elements can now be switched on or off individually.

  8. The following steps are only relevant for users with a regular Sonargraph-Build license:

  9. You should update your Sonar quality profiles to include and activate the Sonargraph-specific Sonar rules provided by the Sonargraph-Sonar plugin. There are three separate Sonargraph-specific Sonar rules for architecture violations, open tasks and threshold violations.
  10. The Sonargraph-Sonar integration makes use of your existing Sonargraph architecture definition to detect and add all architecture violations, threshold violations and open tasks to the Sonar dashboard. The Sonargraph architecture definition is defined in Sonargraph-Architect and then stored in the Sonargraph system file. The easiest way to make use of this architecture definition is to place the Sonargraph system file next to the POM file and name it ${artifactId}.Sonargraph. So if for example the artifact id in your POM file is "MyApp" then the Sonargraph system file should be named "MyApp.Sonargraph".
  11. In case of a multi-module maven project you must create an initial architecture definition by importing the Maven POM file into Sonargraph with the "new system" wizard. This step is described in detail in chapter "Creating a new System" of the Sonargraph user manual. It will create Sonargraph build units for your Maven modules and connect them according to the dependency structure in your POM files. If you decide to import transitive dependencies, it will also create an allowed dependency from module A to C, if there is one from A to B and another from B to C.
  12. If you don't want to import the information from your Maven POM files you must follow a naming convention for the mapping from Maven modules to Sonargraph build units. It is recommended to use the arfifactId to name the corresponding Sonargraph build unit. If this is not unique you can use 'groupId:artifactId' as the build unit's name. Due to the design of Sonar (Codehaus) you must have a one to one mapping between Maven modules and Sonargraph build units. There must be one Sonargraph build unit for each Maven module containing Java code, otherwise you will get build errors.
  13. The Maven and Sonar (Codehaus) paradigm is that each Maven plugin is a software artifact which could be compiled, tested and verified for quality issues on itself. From the Maven point of view there exists no global view. Sonargraph analyzes a whole system and checks its architecture as it is defined in a .Sonargraph file to find architecture violations, metric threshold violations, and furthermore it performs quality analysis. If only a part of the system defined in the .Sonargraph file is analyzed certain architectural and structural problems cannot be detected. For this reason Sonargraph needs a global view. To address this the Maven execution is split into two commands as given in item 6 above. This will make sure that the Sonargraph maven plugin is executed and creates a report with a global view before the Sonargraph-Sonar plugin runs and extracts the information from that report for the sub-projects.

Dashboxes of Sonargraph-Sonar Integration

The Sonargraph-Sonar plugin creates up to three different dashboxes in the Sonar (Codehaus) dashboard. One of them is only available if you are using a regular Sonargraph-Build license. And two of them will only show up, if the metrics to be reported are not zero.

Structure Dashbox


This dashbox displays some key metrics provided from Sonargraph which are about the overall coupling, the level of package cyclicity and the size of your software system. These metrics are:

Relative Package Cyclicity
This number gives you an indication, how cyclic your project is on the package level. It depends on the total number of cyclic coupled packages in the system and how they are distributed to package cycle groups. Few but large package cycles induce a higher 'relative package cyclicity' than a bigger amount of smaller package cycles. This number is calculated by dividing the square root of package cyclicity by the number of packages in your application. The package cyclicity itself is the sum of the square of the number of elements over all package cycle groups. The value is marked as a warning, if the underlying package cyclicity is 25 or more. It is marked as an error, if the underlying package cyclicity is 50 or more. Cyclic package dependencies are considered to have a very negative impact on the maintainability, testability and comprehensibility of your code. The level of cyclic package dependencies is a good indicator for the level of structural erosion in your project. Use Sonargraph's cyclic dependency break up analyzer to break up your package cycles with the least possible effort.
Biggest Cycle Group Size
A package cycle group consists of at least two packages where each member can be reached from each other member by following one or more dependencies. This metric displays the size of the biggest cycle group and is flagged as a warning if its value is 4 or more. Values of 8 or more are flagged as errors.
Cyclic Packages
Total number of packages involved in cyclic package dependencies. The value in the brackets displays the relative number of cyclic packages.
Type Dependencies to Cut and References to Remove
The metric "type dependencies to cut" tells you how many type dependencies you need to cut to break up all package cycles. The metric "number of references to remove" tells you how many lines in the program code would be affected by the change.
ACD (Average Component Dependency - John Lakos)
Measures the overall coupling. The metric tells you on how many Java files a randomly picked Java file depends upon directly or indirectly (including itself). It is always a good idea to try to keep this value under 50. If the value grows you can decrease it by reducing the number of outgoing dependencies for classes directly or indirectly used by many other classes. Another good method is to insulate layers and subsystem by using interfaces. The warning and error levels for this metric are derived from NCCD (see below).
NCCD (Normalized Cumulative Component Dependency - John Lakos)
Normalized version of ACD, that is independent of your project size. It compares the coupling of your project with the coupling of a balanced binary tree with the same number of nodes. Values of 6.5 or higher are flagged as warning, 10.0 or higher is considered as an error.
Highest ACD and Highest NCCD
ACD and NCCD cannot be aggregated. So on project level, the highest ACD respectively NCCD metric value of all contained components is displayed.
Byte Code Instructions
This size metric counts the number of byte code instructions for your entire software system. It is more reliable than lines of code, because it is completely independent from the way you format your code. It is also relevant if you should plan to purchase a commercial license of Sonargraph, because the license pricing is coupled to the size of your project.

Structural Debt Dashbox


This dashbox will only show up, if your project contains either cyclic package dependencies or architecture violations or threshold warnings or open tasks.

Structural Debt Index
The metric 'structural debt index' measures the overall structural erosion of your project using heuristics. The higher the value, the more erosion you have. Moreover this metric should be roughly proportional to the effort needed to clean up your project. With the free license only cyclic package dependencies go into this metric. The commercial license adds all architecture violations, threshold violations and open tasks. The Sonargraph manual describes in detail, how this metric is calculated.
Cost of Structural Debt
Assuming that every point of structural debt index equals roughly between 5 and 10 minutes of work, this metric can give you a rough estimation of the clean up effort needed to bring the level of erosion back to zero. In the global Sonar configuration you can configure the amount that is necessary to remove one point. The default value is 11 per point.
For small projects this effort is probably over estimated, but for bigger projects one can assume that this effort estimation is quite optimistic, so that you should consider the calculated effort as a best-case estimation. Therefore it is always a good idea to break up cyclic dependencies as early as possible while the cycle groups are still small.

You can also configure the currency displayed for the cost of your structural debt by changing the settings for the Sonargraph-Sonar plugin in the global Sonar configuration. The default currency is USD.
Open Tasks
This metric shows the number of open restructuring tasks assigned in Sonargraph-Architect together with the number of code lines affected by open tasks.

Architecture Dashbox


This dashbox is only available, if you are using a regular Sonargraph-Build license.

Architecture Violations
Shows the number of locations (i.e. lines) which contain code with architecture violations.
Violating Type Dependencies
Shows the number of dependencies between classes, which are not allowed and so causing an architecture violation.
Violating Types
Shows the total number of types (classes) with outgoing architecture violations together with the relative number of violating types.
Unassigned Types
Shows the total number of types in your software system, which are not assigned to any architectural artifact in the Sonargraph architecture definition, followed by the relative number of unassigned types. Unassigned types are not considered in the architecture check. They occur when either your Sonargraph architecture definition is not complete or package naming conventions are not followed in a consistent way.
Ignored Violations
Shows the number of ignored violating type dependencies, i.e. existing architecture violations which have been set by the Sonargraph-Architect user to the status "to be ignored". Ignored violations are not counted in the architecture violation metrics above.
Shows the total number of all warnings.
Cycle Groups (warnings)
Shows the total number of cycle group warnings. Note that the drilldown for this metric only displays packages contained in a cycle group. Every detected cycle group creates one warning.
Duplicate Code Blocks (warnings)
Shows the total number of duplicate code block warnings. Every detected duplicate code block (copy&paste problem) creates one warning.
Threshold Violations (warnings)
Shows the total number of threshold warnings. Every metric value, which exceeds a metric threshold defined in Sonargraph-Architect, creates one warning.
Workspace Warnings
Shows the total number of workspace warnings. Every detected problem in the project's workspace (like for example identical class files at several locations) creates one warning.
Ignored Warnings
Shows the total number of ignored warnings, i.e. existing warnings which have been set by the Sonargraph-Architect user to the status "to be ignored". Ignored warnings are not counted in the warning metrics above.

Violation Drilldown

The drilldown feature is only available, if you are using a regular Sonargraph-Build license. Drilldown to the code level is possible for all architecture violations, metric threshold violations and open tasks. You can control the priority of violations when you activate the associated Sonargraph rule. All Sonargraph rule violations are kept under the maintainability category.

Known Limitations

Drilldown is not supported for other Sonargraph metrics, because Sonargraph-Build accumulates metric values at the project level. You can always get drilldown details for these metrics by using Sonargraph-Quality.

A violation drilldown to the source code level is not possible for generated sources. Sonar currently does not store generated sources in the database. But it is usually a good idea to ignore those problems or to filter out generated code.