org.sonar.api.server.rule

Class RulesDefinitionXmlLoader

java.lang.Object

org.sonar.api.server.rule.RulesDefinitionXmlLoader

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>

     <!-- Optional tags. See org.sonar.api.server.rule.RuleTagFormat. The maximal length of all tags is 4000 characters. -->
     <tag>style</tag>
     <tag>security</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>

     <!-- SQALE debt - key of sub-characteristic -->
     <!-- See RulesDefinition.SubCharacteristics for core supported values.
     Any other values can be used. If sub-characteristic does not exist at runtime in the SQALE model,
     then the rule is created without any sub-characteristic. -->
     <!-- Since 5.3 -->
     <debtSubCharacteristic>MODULARITY</debtSubCharacteristic>

     <!-- SQALE debt - type of debt remediation function -->
     <!-- See enum DebtRemediationFunction.Type for supported values -->
     <!-- Since 5.3 -->
     <debtRemediationFunction>LINEAR_OFFSET</debtRemediationFunction>

     <!-- SQALE debt - raw description of the "effort to fix", used for some types of remediation functions. -->
     <!-- See RulesDefinition.NewRule.setEffortToFixDescription(String) -->
     <!-- Since 5.3 -->
     <effortToFixDescription>Effort to test one uncovered condition</effortToFixDescription>

     <!-- SQALE debt - coefficient of debt remediation function. Must be defined only for some function types. -->
     <!-- See RulesDefinition.DebtRemediationFunctions -->
     <!-- Since 5.3 -->
     <debtRemediationFunctionCoefficient>10min</debtRemediationFunctionCoefficient>

     <!-- SQALE debt - offset of debt remediation function. Must be defined only for some function types. -->
     <!-- See RulesDefinition.DebtRemediationFunctions -->
     <!-- Since 5.3 -->
     <debtRemediationFunctionOffset>2min</debtRemediationFunctionOffset>

     <!-- 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>
     <debtSubCharacteristic>SECURITY_FEATURES</debtSubCharacteristic>
     <debtRemediationFunction>CONSTANT_ISSUE</debtRemediationFunction>
     <debtRemediationFunctionOffset>10min</debtRemediationFunctionOffset>
   </rule>

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

Since:

4.3

See Also:

RulesDefinition

Constructor Summary

Constructors

Constructor and Description
RulesDefinitionXmlLoader()

Method Summary

Methods

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