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