JCL
JCL analysis is available starting in Enterprise Edition and supported by SonarQube for Eclipse when running in Connected Mode.
Language-specific properties
You can discover and update JCL-specific analysis parameters in Administration > Configuration > General Settings > Languages > JCL
Source code extraction
To analyze your source code with SonarQube Server, you first need to extract it onto a filesystem. You can use your own tool or an open-source tool; SonarSource does not provide any connectors or source code extraction tools.
JCL source format
Depending on your extraction process, your JCL source files may include extra characters beyond the 72nd columns, and include the 8 additional characters up to column 80, or even go beyond that column.
When that happens, the parser will:
- consider everything up to the 71st column as valid JCL code,
- look at the character in the 72nd column, to determine whether a continuation is present or not,
- consider everything beyond the 72nd column as an inline comment, even when the text goes beyond the 80th column.
Adding custom rules to SonarQube Server
Overview
To get started you can download a sample plugin or browse and clone it from GitHub. The sample is a fully working prototype plugin, that can be built and run in SonarQube Server.
The JCL analyzer parses the source code, creates an Abstract Syntax Tree (AST), and then walks through the entire tree. A coding rule can subscribe to be notified every time a node of a certain type is visited.
As soon as the coding rule is notified, it can navigate the tree around the node (up and down) and raise issues if necessary.
Prerequisites
The following tools and artifacts are required for the following steps.
- JDK 17
- Maven
- sonar-jcl-plugin 1.2+
Setup
Writing new JCL coding rules requires the following steps:
- Create a Maven project containing a new standard SonarQube Server plugin.
- Derive a custom plugin class from the plugin class.
- Define the rules via a repository of custom rules for the plugin.
- Implement the rules, writing as many custom rules as needed.
- Test the rules using the provided test kit.
- Add the rules to your instance of SonarQube Server by generating the jar file (for SonarQube Server) and deploying it.
Each step is described in detail in the sections down below.
Step 1: Create the Maven project
You should first create a Maven project to host the JCL custom plugin.
Re-using the pom.xml from the custom rules JCL example is a good start.
The following dependencies need to be defined in the pom.xml
:
sonar-plugin-api
to get access to the SonarQube Server APIs.sonar-jcl-plugin
to use the APIs of the JCL plugin.
The plugin should also:
- have testing dependencies, such as
junit
- reference the
sonar-packaging-maven-plugin
, to be able to pack the plugin into a format compatible with SonarQube Server, with the following configurationsonarlintSupported
set totrue
, so that custom rules defined in this plugin will be visible in SonarQube for IDErequiredPlugins
set tojcl:${version.jclPlugin}
, to establish the requirement of the base JCL pluginrequiredForLanguages
set tojcl
, to establish the link between JCL files and this plugin
Step 2: Derive a custom plugin class from the plugin class
The entry point of the custom plugin is a class that implements org.sonar.api.Plugin
and lists the SonarQube Server extensions required by the plugin.
This list should contain the rules definition created in the next step.
An example of such a class is provided by the MyJclCustomPlugin.java file in the custom rules JCL example.
Step 3: Define the rules
One class in the Maven project should extend com.sonarsource.jcl.api.CustomRulesDefinition
, in order to provide information about the custom rules that you’ll implement in the next step.
A complete example of such a class is provided by the MyJclCustomRulesDefinition.java file in the custom rules JCL example.
It should list the classes of the custom rules.
It should use the SonarQube Server API to define the metadata of these rules, such as name, HTML description, default impact, the Clean Code Attribute, and optional tags.
The class should be registered as an extension in the Plugin defined in the previous step.
Step 4: Implement the rules
You’ll need to implement every rule defined in the repository.
The MyCustomRule.java file from the custom rules JCL example provides a template of a simple JCL rule.
Each rule needs to be defined in a class which:
- implements
com.sonarsource.jcl.api.checks.JclCheck
- has an
org.sonar.check.Rule
annotation to define the key of the rule - is added to the repository registered in the
Plugin
class
Step 5: Test the rules
The example project contains an example test class and the associated JCL file.
It's possible to write unit tests for custom rules using com.sonarsource.jcl.checks.testkit.JclVerifier
. This utility class executes a custom rule against a given JCL test file.
The JCL test file should contain comments denoting lines where issues should be expected.
If the line ends with a "Noncompliant"
inline comment field, JclVerifier
expects an issue on that line, with any message.
If the line ends with a "Noncompliant {{the message}}"
inline comment field, JclVerifier
expects an issue on that line and checks that the issue message is "the message"
.
However, the recommended way of asserting a long message is to write the comment on a dedicated comment statement (i.e. starting with "//*"
). That will help prevent issues with comment continuations when long messages need to be asserted and the 72nd character of the line is not whitespace.
Notation is also provided to assert issue location, as well as secondary locations and messages.
You can refer to this page for more comprehensive examples of assertions, in the context of a C-like language.
Step 6: Add the rules to SonarQube Server
Once the coding rules have been implemented and tested, you need to perform the following steps.
- Build the Maven project by running
mvn install
from the project directory. This will generate a SonarQube Server plugin jar file in the target directory. - Add your newly created jar into the
$SONARQUBE_HOME/extensions/plugins
directory. - Restart your instance of SonarQube Server.
If you now look at the JCL quality profiles, you will find the new coding rules defined in the previous step. Don’t forget to activate it. Run an analysis on a repository of JCL files, and you should find that issues are reported on those files.
More advanced features are documented in the API Javadoc.
Related pages
Was this page helpful?