org.sonar.api.server.rule

Class RulesDefinitionXmlLoader

java.lang.Object

org.sonar.api.server.rule.RulesDefinitionXmlLoader

@ServerSide
 @ComputeEngineSide
 @SonarLintSide
public class RulesDefinitionXmlLoader
extends Object

Loads definitions of rules from a XML file.

Usage

 public class MyJsRulesDefinition implements RulesDefinition {

   private static final String PATH = "my-js-rules.xml";
   private final RulesDefinitionXmlLoader xmlLoader;

   public MyJsRulesDefinition(RulesDefinitionXmlLoader xmlLoader) {
     this.xmlLoader = xmlLoader;
   }

    @Override
   public void define(Context context) {
     try (Reader reader = new InputStreamReader(getClass().getResourceAsStream(PATH), StandardCharsets.UTF_8)) {
       NewRepository repository = context.createRepository("my_js", "js").setName("My Javascript Analyzer");
       xmlLoader.load(repository, reader);
       repository.done();
     } catch (IOException e) {
       throw new IllegalStateException(String.format("Fail to read file %s", PATH), e);
     }
   }
 }
 

XML Format

 <rules>
   <rule>
     <!-- Required key. Max length is 200 characters. -->
     <key>the-rule-key</key>

     <!-- Required name. Max length is 200 characters. -->
     <name>The purpose of the rule</name>

     <!-- Required description. No max length. -->
     <description>
       <![CDATA[The description]]>
     </description>
     <!-- Optional format of description. Supported values are HTML (default) and MARKDOWN. -->
     <descriptionFormat>HTML</descriptionFormat>

     <!-- Optional key for configuration of some rule engines -->
     <internalKey>Checker/TreeWalker/LocalVariableName</internalKey>

     <!-- Default severity when enabling the rule in a Quality profile.  -->
     <!-- Possible values are INFO, MINOR, MAJOR (default), CRITICAL, BLOCKER. -->
     <severity>BLOCKER</severity>

     <!-- Possible values are SINGLE (default) and MULTIPLE for template rules -->
     <cardinality>SINGLE</cardinality>

     <!-- Status displayed in rules console. Possible values are BETA, READY (default), DEPRECATED. -->
     <status>BETA</status>

     <!-- Type as defined by the SonarQube Quality Model. Possible values are CODE_SMELL (default), BUG and VULNERABILITY.-->
     <type>BUG</type>

     <!-- Optional tags. See org.sonar.api.server.rule.RuleTagFormat. The maximal length of all tags is 4000 characters. -->
     <tag>misra</tag>
     <tag>multi-threading</tag>

     <!-- Optional parameters -->
     <param>
       <!-- Required key. Max length is 128 characters. -->
       <key>the-param-key</key>
       <description>
         <![CDATA[the optional description, in HTML format. Max length is 4000 characters.]]>
       </description>
       <!-- Optional default value, used when enabling the rule in a Quality profile. Max length is 4000 characters. -->
       <defaultValue>42</defaultValue>
     </param>
     <param>
       <key>another-param</key>
     </param>

     <!-- Quality Model - type of debt remediation function -->
     <!-- See enum DebtRemediationFunction.Type for supported values -->
     <!-- It was previously named 'debtRemediationFunction' which is still supported but deprecated since 5.5 -->
     <!-- Since 5.5 -->
     <remediationFunction>LINEAR_OFFSET</remediationFunction>

     <!-- Quality Model - raw description of the "gap", used for some types of remediation functions. -->
     <!-- See RulesDefinition.NewRule.setGapDescription(String) -->
     <!-- It was previously named 'effortToFixDescription' which is still supported but deprecated since 5.5 -->
     <!-- Since 5.5 -->
     <gapDescription>Effort to test one uncovered condition</gapFixDescription>

     <!-- Quality Model - gap multiplier of debt remediation function. Must be defined only for some function types. -->
     <!-- See RulesDefinition.DebtRemediationFunctions -->
     <!-- It was previously named 'debtRemediationFunctionCoefficient' which is still supported but deprecated since 5.5 -->
     <!-- Since 5.5 -->
     <remediationFunctionGapMultiplier>10min</remediationFunctionGapMultiplier>

     <!-- Quality Model - base effort of debt remediation function. Must be defined only for some function types. -->
     <!-- See RulesDefinition.DebtRemediationFunctions -->
     <!-- It was previously named 'debtRemediationFunctionOffset' which is still supported but deprecated since 5.5 -->
     <!-- Since 5.5 -->
     <remediationFunctionBaseEffort>2min</remediationFunctionBaseEffort>

     <!-- Deprecated field, replaced by "internalKey" -->
     <configKey>Checker/TreeWalker/LocalVariableName</configKey>

     <!-- Deprecated field, replaced by "severity" -->
     <priority>BLOCKER</priority>

   </rule>
 </rules>
 

XML Example

 <rules>
   <rule>
     <key>S1442</key>
     <name>"alert(...)" should not be used</name>
     <description>alert(...) can be useful for debugging during development, but ...</description>
     <tag>cwe</tag>
     <tag>security</tag>
     <tag>user-experience</tag>
     <debtRemediationFunction>CONSTANT_ISSUE</debtRemediationFunction>
     <debtRemediationFunctionBaseOffset>10min</debtRemediationFunctionBaseOffset>
   </rule>

   <!-- another rules... -->
 </rules>
 

Since:

4.3

See Also:

RulesDefinition

Constructor Summary

Constructors

Constructor and Description
RulesDefinitionXmlLoader()

Method Summary

Modifier and Type	Method and Description
void	load(RulesDefinition.NewRepository repo, InputStream input, Charset charset)
void	load(RulesDefinition.NewRepository repo, InputStream input, String encoding) Loads rules by reading the XML input stream.
void	load(RulesDefinition.NewRepository repo, Reader reader) Loads rules by reading the XML input stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RulesDefinitionXmlLoader

public RulesDefinitionXmlLoader()

Method Detail

load

public void load(RulesDefinition.NewRepository repo,
                 InputStream input,
                 String encoding)

Loads rules by reading the XML input stream. The input stream is not always closed by the method, so it should be handled by the caller.

Since:

4.3

load

public void load(RulesDefinition.NewRepository repo,
                 InputStream input,
                 Charset charset)

Since:

5.1

load

public void load(RulesDefinition.NewRepository repo,
                 Reader reader)

Loads rules by reading the XML input stream. The reader is not closed by the method, so it should be handled by the caller.

Since:

4.3