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 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 }