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 }