1 /** 2 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html 3 */ 4 package net.sourceforge.pmd; 5 6 import java.util.List; 7 8 import net.sourceforge.pmd.lang.Language; 9 import net.sourceforge.pmd.lang.LanguageVersion; 10 import net.sourceforge.pmd.lang.ParserOptions; 11 import net.sourceforge.pmd.lang.ast.Node; 12 import net.sourceforge.pmd.lang.rule.properties.StringProperty; 13 14 /** 15 * This is the basic Rule interface for PMD rules. 16 * 17 * <p><strong>Thread safety:</strong> 18 * PMD will create one instance of a rule per thread. The instances are 19 * not shared across different threads. However, a single rule instance is 20 * reused for analyzing multiple files. 21 * </p> 22 */ 23 // FUTURE Implement Cloneable and clone() 24 public interface Rule extends PropertySource { 25 26 /** 27 * The property descriptor to universally suppress violations with messages 28 * matching a regular expression. 29 */ 30 StringProperty VIOLATION_SUPPRESS_REGEX_DESCRIPTOR = new StringProperty("violationSuppressRegex", 31 "Suppress violations with messages matching a regular expression", null, Integer.MAX_VALUE - 1); 32 33 /** 34 * Name of the property to universally suppress violations on nodes which 35 * match a given relative XPath expression. 36 */ 37 StringProperty VIOLATION_SUPPRESS_XPATH_DESCRIPTOR = new StringProperty("violationSuppressXPath", 38 "Suppress violations on nodes which match a given relative XPath expression.", null, Integer.MAX_VALUE - 2); 39 40 /** 41 * Get the Language of this Rule. 42 * 43 * @return the language 44 */ 45 Language getLanguage(); 46 47 /** 48 * Set the Language of this Rule. 49 * 50 * @param language the language 51 */ 52 void setLanguage(Language language); 53 54 /** 55 * Get the minimum LanguageVersion to which this Rule applies. If this value 56 * is <code>null</code> it indicates there is no minimum bound. 57 * 58 * @return the minimum language version 59 */ 60 LanguageVersion getMinimumLanguageVersion(); 61 62 /** 63 * Set the minimum LanguageVersion to which this Rule applies. 64 * 65 * @param minimumLanguageVersion the minimum language version 66 */ 67 void setMinimumLanguageVersion(LanguageVersion minimumLanguageVersion); 68 69 /** 70 * Get the maximum LanguageVersion to which this Rule applies. If this value 71 * is <code>null</code> it indicates there is no maximum bound. 72 * 73 * @return the maximum language version 74 */ 75 LanguageVersion getMaximumLanguageVersion(); 76 77 /** 78 * Set the maximum LanguageVersion to which this Rule applies. 79 * 80 * @param maximumLanguageVersion the maximum language version 81 */ 82 void setMaximumLanguageVersion(LanguageVersion maximumLanguageVersion); 83 84 /** 85 * Gets whether this Rule is deprecated. A deprecated Rule is one which: 86 * <ul> 87 * <li>is scheduled for removal in a future version of PMD</li> 88 * <li>or, has been removed and replaced with a non-functioning place-holder 89 * and will be completely removed in a future version of PMD</li> 90 * <li>or, has been renamed/moved and the old name will be completely 91 * removed in a future version of PMD</li> 92 * </ul> 93 * 94 * @return <code>true</code> if this rule is deprecated 95 */ 96 boolean isDeprecated(); 97 98 /** 99 * Sets whether this Rule is deprecated. 100 * 101 * @param deprecated whether this rule is deprecated 102 */ 103 void setDeprecated(boolean deprecated); 104 105 /** 106 * Get the name of this Rule. 107 * 108 * @return the name 109 */ 110 String getName(); 111 112 /** 113 * Set the name of this Rule. 114 * 115 * @param name the name 116 */ 117 void setName(String name); 118 119 /** 120 * Get the version of PMD in which this Rule was added. Return 121 * <code>null</code> if not applicable. 122 * 123 * @return version of PMD since when this rule was added 124 */ 125 String getSince(); 126 127 /** 128 * Set the version of PMD in which this Rule was added. 129 * 130 * @param since the version of PMD since when this rule was added 131 */ 132 void setSince(String since); 133 134 /** 135 * Get the implementation class of this Rule. 136 * 137 * @return the implementation class name of this rule. 138 */ 139 String getRuleClass(); 140 141 /** 142 * Set the class of this Rule. 143 * 144 * @param ruleClass the class name of this rule. 145 */ 146 void setRuleClass(String ruleClass); 147 148 /** 149 * Get the name of the RuleSet containing this Rule. 150 * 151 * @return the name of th ruleset containing this rule. 152 * @see RuleSet 153 */ 154 String getRuleSetName(); 155 156 /** 157 * Set the name of the RuleSet containing this Rule. 158 * 159 * @param name the name of the ruleset containing this rule. 160 * @see RuleSet 161 */ 162 void setRuleSetName(String name); 163 164 /** 165 * Get the message to show when this Rule identifies a violation. 166 * 167 * @return the message to show for a violation. 168 */ 169 String getMessage(); 170 171 /** 172 * Set the message to show when this Rule identifies a violation. 173 * 174 * @param message the message to show for a violation. 175 */ 176 void setMessage(String message); 177 178 /** 179 * Get the description of this Rule. 180 * 181 * @return the description 182 */ 183 String getDescription(); 184 185 /** 186 * Set the description of this Rule. 187 * 188 * @param description the description 189 */ 190 void setDescription(String description); 191 192 /** 193 * Get the list of examples for this Rule. 194 * 195 * @return the list of examples for this rule. 196 */ 197 List<String> getExamples(); 198 199 /** 200 * Add a single example for this Rule. 201 * 202 * @param example a single example to add 203 */ 204 void addExample(String example); 205 206 /** 207 * Get a URL for external information about this Rule. 208 * 209 * @return the URL for external information about this rule. 210 */ 211 String getExternalInfoUrl(); 212 213 /** 214 * Set a URL for external information about this Rule. 215 * 216 * @param externalInfoUrl the URL for external information about this rule. 217 */ 218 void setExternalInfoUrl(String externalInfoUrl); 219 220 /** 221 * Get the priority of this Rule. 222 * 223 * @return the priority 224 */ 225 RulePriority getPriority(); 226 227 /** 228 * Set the priority of this Rule. 229 * 230 * @param priority the priority 231 */ 232 void setPriority(RulePriority priority); 233 234 /** 235 * Get the parser options for this Rule. Parser options are used to 236 * configure the {@link net.sourceforge.pmd.lang.Parser} to create an AST in the form the Rule is 237 * expecting. Because ParserOptions are mutable, a Rule should return a new 238 * instance on each call. 239 * 240 * @return the parser options 241 */ 242 ParserOptions getParserOptions(); 243 244 /** 245 * Sets whether this Rule uses Data Flow Analysis. 246 */ 247 // FUTURE Use JavaBean conventions for boolean attributes 248 void setUsesDFA(); 249 250 /** 251 * Gets whether this Rule uses Data Flow Analysis. 252 * 253 * @return <code>true</code> if Data Flow Analysis is used. 254 */ 255 // FUTURE Use JavaBean conventions for boolean attributes 256 boolean usesDFA(); 257 258 /** 259 * Sets whether this Rule uses Type Resolution. 260 */ 261 // FUTURE Use JavaBean conventions for boolean attributes 262 void setUsesTypeResolution(); 263 264 /** 265 * Gets whether this Rule uses Type Resolution. 266 * 267 * @return <code>true</code> if Type Resolution is used. 268 */ 269 // FUTURE Use JavaBean conventions for boolean attributes 270 boolean usesTypeResolution(); 271 272 /** 273 * Gets whether this Rule uses the RuleChain. 274 * 275 * @return <code>true</code> if RuleChain is used. 276 */ 277 // FUTURE Use JavaBean conventions for boolean attributes 278 boolean usesRuleChain(); 279 280 /** 281 * Gets the collection of AST node names visited by the Rule on the 282 * RuleChain. 283 * 284 * @return the list of AST node names 285 */ 286 List<String> getRuleChainVisits(); 287 288 /** 289 * Adds an AST node by class to be visited by the Rule on the RuleChain. 290 * 291 * @param nodeClass the AST node to add to the RuleChain visit list 292 */ 293 void addRuleChainVisit(Class<? extends Node> nodeClass); 294 295 /** 296 * Adds an AST node by name to be visited by the Rule on the RuleChain. 297 * 298 * @param astNodeName the AST node to add to the RuleChain visit list as 299 * string 300 */ 301 void addRuleChainVisit(String astNodeName); 302 303 /** 304 * Start processing. Called once, before apply() is first called. 305 * 306 * @param ctx the rule context 307 */ 308 void start(RuleContext ctx); 309 310 /** 311 * Apply this rule to the given collection of nodes, using the given 312 * context. 313 * 314 * @param nodes the nodes 315 * @param ctx the rule context 316 */ 317 void apply(List<? extends Node> nodes, RuleContext ctx); 318 319 /** 320 * End processing. Called once, after apply() is last called. 321 * 322 * @param ctx the rule context 323 */ 324 void end(RuleContext ctx); 325 }