Latest News

January 18, 2010

SonarJ Integrates with Codehaus Sonar

Sonar SonarJ Plugin 1.0 Released Today

September 15, 2009

Upcoming Events

Mon, May 03 2010

Fri, May 07 2010

Sonar Integration

Overview

hello2morrow provides a plugin for the quality management umbrella tool "Sonar". The similarity of the names is just a random incident.

Usage and Installation

You need a license to use the plugin. You can either use our free Sonar plugin license or a commercial SonarJ-Report license. If you want to use obtain a free 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.
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.

Add the hello2morrow Maven repository to the repository list in your Maven setting.xml file:

  <profile>
    <id>sonarj</id>
    <activation>
      <activeByDefault>true</activeByDefault>
    </activation>
    <pluginRepositories>
      <pluginRepository>
        <id>hello2morrow.maven.repository</id>
        <url>http://maven.hello2morrow.com/repository</url>
      </pluginRepository>
    </pluginRepositories>
  </profile>

Restart your Sonar server.
Store the file with the license key on your build server and enter the absolute path into the Sonar configuration (Configuration/Settings/SonarJ). You need to have Sonar administration rights to be able to do that. You can also configure the path to the license in the pom file if you have more than one build server. A pom configuration will override the Sonar configuration. Please check the documentation of our Maven plugin for details.
If you own a commercial SonarJ report license you should update your quality profiles to include and activate the rules provided by the SonarJ plugin. There are three separate SonarJ rules for architecture violations, open tasks and threshold violations.
If you own a SonarJ report license the plugin can use your existing architecture description to add all architecture violations, threshold violations and open tasks to the Sonar dashboard. The easiest way to make the plugin use your architecture description file is to place it next to the pom file and name it ${artifactId}.sonarj. So if the artifact id in your pom file is "MyApp" then the SonarJ file should be named "MyApp.sonarj".
If you have a commercial license and your project is a multi-module project you must follow these create an initial architecture decsription using the SonarJ Maven plugin:
mvn com.hello2morrow.sonar:maven-sonarj-plugin:5.1.1:generate-description
The genarator will create SonarJ projects for your Maven modules and connect them according to the dependency structure in your pom files. You can always rerun the generator if the module strcuture of your project changes. But please keep in mind that the generator will never delete obsolete projects. That has to be done manually.
For single module project or projects using our free license you can now execute mvn sonar:sonar on your project and then navigate to the project page in Sonar. You should now at least see the SonarJ structure dashbox in the project dashboard. If you are using a commercial license you should also see the SonarJ architecture dashbox.
For multi-module projects in the context of a commercial SonarJ license you should execute:
mvn com.hello2morrow.sonar:maven-sonarj-plugin:5.1.1:sonarj sonar:sonar
This command will make sure that the SonarJ maven plugin is executed before the Sonar plugin is running.

Plugin Dashboxes

The plugin creates up to four different dashboxes. Two of them are only available if you are using a commercial reporting 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 about the overall coupling, the level of package cyclicity and the size of your project.

Relative Cyclicity: This number gives you an idea, how cyclic your project is on the package level. It is calculated by dividing the square root of package cyclicity (see below) by the number of packages in your application. The value is marked as a warning, if the overall package cyclicity is 25 or more. It is marked as an error, if the 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 SonarJ's cyclic dependency break up analyzer to break up your package cycles with the least possible effort. For smaller project you can use our free Community Edition to do that.
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.
Package Cyclicity: This number is calculated by adding up the square values of all cycle group sizes. Values of 25 or more are flagged as warning, values of 50 or more are flagged as errors.
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 Cummulative 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.
Byte Code Instructions: This project size metric counts the number of byte code instructions for your project. 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 buy a commercial license of SonarJ, because the license pricing is coupled to the size of your project. Projects with up to 50'000 byte code instructions can use our free Community license.

Structural Debt Dashbox

This dashbox will only show up, if your project contains cyclic package dependencies. Using an heuristical algorithm SonarJ estimates the effort needed to break up all cyclic dependencies. 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 code would be affected by the change.

The effort is then calculated by assuming, that you need one hour per type dependency to figure out, how to remove it and then an extra 6 minutes per code reference. Furthermore I am assuming 8 hours per developer day. The hourly cost rate can be configured in the Sonar Configuration for the SonarJ plugin. The default value is $70 per hour.

For small projects this effort is probably over estimated, but for bigger projects I would 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.

Architecture Dashbox

This dashbox is only available, if you are using the commercial SonarJ report license.

Architecture Violations: Number of code lines with outgoing achitecture violations.
Cyclic Architectural Elements: Number of architectural artifacts (layers, vertical slices, subsystems etc.) involved in cyclic dependencies.
Violating Types: Number of types with outgoing architecture violations.
Open Tasks: Number of assigned open tasks.
Open Task Markers: Number of code lines affected by open tasks.

Architecture Consistency Dashbox

This dashbox is only available for the commercial SonarJ report license and will only show up, if there are consistency problems in your architecture definition.

Unassigned Types: Number of project types not assigned to any architetural artifact. Unassigned types occur when either your architecture definition is not complete or package naming conventions are not followed in a consistent way.
Consistency Warnings: The number of problems under the Summary/Architecture Consistency tab in SonarJ. Typical examples for a consistency problems are superfluous dependencues or a pattern assignment conflicts.
Parsing Problems: The project build is not consistent. These problems can be found under the Summary/Warnings tab in SonarJ and have the problem category "Workspace".

Violation Drilldown (Commercial License)

Drilldown is available to the code level for all architecture violations, metric threshold violations and open tasks. You can control the priority of violations when you activate the associated SonarJ rule. All SonarJ rule violations are kept under the maintainability category.

Known Limitations

Drilldown is not supported for most metrics, because SonarJ-Report accumulates metric values at the project level. You can always get drilldown details by using SonarJ.

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.