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