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