Measures can be saved from two extensions : Sensors and Decorators. A common problem is to know which one to use during analysis of a project.
A Sensor is a "job" that is going to be invoked during analysis of a project. The sensor are in charge of collecting metrics. This can be done in multiple ways such as invoking a maven plugin, parsing a flat file, connecting to a web server...
For example the Cobertura Sensor invokes the Codehaus Cobertura MOJO. Then the generated XML file is parsed and used to save the first-level of measures on resources (project, package or class).
The object used to save measures is org.sonar.api.batch.SensorContext. It only inserts measures. It can not get another plugins measures. Example :
Decorator are fired when all sensors have run. They're generally used either to consolidate measures at higher levels or to calculate advanced metrics. Examples :
- A Sensor only inserts the number of lines of code at classes level. A Decorator is used to sum up lines at packages, modules and project levels. Class Foo has 200 lines, class Bar has 300 lines, so the project has 500 lines.
- A decorator calculates the Rules Compliance Index on every resource of the project, by combining the weighted violations and the lines of code.
Decorators can load (SELECT) and save (INSERT) measures. When processing a resource, only its children measures are available. That's why Decorators process resources in a tree way : classes, packages then project.
Currently the following extension points are available :
- Language : This extension is mandatory as soon as you want to cover a new language like Groovy, COBOL, Ruby...
- Metrics : a metric defines a type of measure. It can be quantitative (lines of code, number of rule violations) or qualitative (code coverage, complexity by class, rules compliance). As a rule, a metric is used to store a number but it can also be used to store a text field with list of key/value pairs, an XML or even binary document. The Metrics extension point allows to define your own list of Metric.
- Rules Repository : defines a list of coding rules to publish into the global rules referential. It can also define profiles of active rules, like Sonar Way or Sun Checks. It's read when the server starts to register the rules into the Sonar DB.
- Maven Collector : This extension point must be used as soon as you want to analyze sources or make requests on other systems for instance in order to feed Sonar. A Maven Collector can declare a dependency on a MavenHandler in order to configure and launch an existing Maven plugin. Sonar leverages several open source maven plugins to analyze Java sources. For example Sonar embarks JavaNcss, Surefire and Cobertura maven plugins to calculate size statistics and execute unit tests.
- Sensor : a sensor is a job that is going to be called during analysis and that should be used to feed metrics at the lowest level. A sensor has access to the complete tree of resources.
- Decorator : a decorator is going to be called on every resource of every level of the resources tree. The call is contextual, i.e, it is only possible to access the resource and its children. Decorators should be used to calculate advanced metrics or consolidate metrics at higher level
- Page, implemented as a GWT component, it allows to define a new web page and add an entry point in the left Sonar sidebar.
- Resource Viewer, implemented as a GWT component, it allows to add a new tab to the source viewer along with "Violations", "Sources", "Coverage", etc.
- Widget, This extensions allows to add a new HTML component inside the project dashboard.