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