001 /**
002 * BSD-style license; for more info see http://pmd.sourceforge.net/license.html
003 */
004 package net.sourceforge.pmd;
005
006 import java.util.List;
007 import java.util.Map;
008
009 import net.sourceforge.pmd.lang.Language;
010 import net.sourceforge.pmd.lang.LanguageVersion;
011 import net.sourceforge.pmd.lang.ast.Node;
012 import net.sourceforge.pmd.lang.rule.properties.StringProperty;
013
014 /**
015 * This is the basic Rule interface for PMD rules.
016 */
017 //FUTURE Implement Cloneable and clone()
018 public interface Rule {
019
020 /**
021 * The property descriptor to universally suppress violations with messages matching a regular expression.
022 */
023 StringProperty VIOLATION_SUPPRESS_REGEX_DESCRIPTOR = new StringProperty("violationSuppressRegex",
024 "Suppress violations with messages matching a regular expression", null, Integer.MAX_VALUE - 1);
025
026 /**
027 * Name of the property to universally suppress violations on nodes which match a given relative XPath expression.
028 */
029 StringProperty VIOLATION_SUPPRESS_XPATH_DESCRIPTOR = new StringProperty("violationSuppressXPath",
030 "Suppress violations on nodes which match a given relative XPath expression.", null, Integer.MAX_VALUE - 2);
031
032 /**
033 * Get the Language of this Rule.
034 */
035 Language getLanguage();
036
037 /**
038 * Set the Language of this Rule.
039 */
040 void setLanguage(Language language);
041
042 /**
043 * Get the minimum LanguageVersion to which this Rule applies. If this
044 * value is <code>null</code> it indicates there is no minimum bound.
045 */
046 LanguageVersion getMinimumLanguageVersion();
047
048 /**
049 * Set the minimum LanguageVersion to which this Rule applies.
050 */
051 void setMinimumLanguageVersion(LanguageVersion minimumLanguageVersion);
052
053 /**
054 * Get the maximum LanguageVersion to which this Rule applies. If this
055 * value is <code>null</code> it indicates there is no maximum bound.
056 */
057 LanguageVersion getMaximumLanguageVersion();
058
059 /**
060 * Set the maximum LanguageVersion to which this Rule applies.
061 */
062 void setMaximumLanguageVersion(LanguageVersion maximumLanguageVersion);
063
064 /**
065 * Gets whether this Rule is deprecated. A deprecated Rule is one which:
066 * <ul>
067 * <li>is scheduled for removal in a future version of PMD</li>
068 * <li>or, has been removed and replaced with a non-functioning place-holder
069 * and will be completely removed in a future version of PMD</li>
070 * <li>or, has been renamed/moved and the old name will be completely
071 * removed in a future version of PMD</li>
072 * <ul>
073 */
074 boolean isDeprecated();
075
076 /**
077 * Sets whether this Rule is deprecated.
078 */
079 void setDeprecated(boolean deprecated);
080
081 /**
082 * Get the name of this Rule.
083 */
084 String getName();
085
086 /**
087 * Set the name of this Rule.
088 */
089 void setName(String name);
090
091 /**
092 * Get the version of PMD in which this Rule was added.
093 * Return <code>null</code> if not applicable.
094 */
095 String getSince();
096
097 /**
098 * Set the version of PMD in which this Rule was added.
099 */
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 * Define a new property via a PropertyDescriptor.
178 *
179 * @param propertyDescriptor The property descriptor.
180 * @throws IllegalArgumentException If there is already a property defined the same name.
181 */
182 void definePropertyDescriptor(PropertyDescriptor<?> propertyDescriptor) throws IllegalArgumentException;
183
184 /**
185 * Get the PropertyDescriptor for the given property name.
186 *
187 * @param name The name of the property.
188 * @return The PropertyDescriptor for the named property, <code>null</code> if there is no such property defined.
189 */
190 PropertyDescriptor<?> getPropertyDescriptor(String name);
191
192 /**
193 * Get the PropertyDescriptors for all defined properties. The properties
194 * are returned sorted by UI order.
195 *
196 * @return The PropertyDescriptors in UI order.
197 */
198 List<PropertyDescriptor<?>> getPropertyDescriptors();
199
200 /**
201 * Get the typed value for the given property.
202 *
203 * @param <T> The underlying type of the property descriptor.
204 * @param propertyDescriptor The property descriptor.
205 * @return The property value.
206 */
207 <T> T getProperty(PropertyDescriptor<T> propertyDescriptor);
208
209 /**
210 * Set the property value specified (will be type-checked)
211 *
212 * @param <T> The underlying type of the property descriptor.
213 * @param propertyDescriptor The property descriptor.
214 * @param value The value to set.
215 */
216 <T> void setProperty(PropertyDescriptor<T> propertyDescriptor, T value);
217
218 /**
219 * Returns all the current property values for the receiver or an
220 * immutable empty map if none are specified.
221 */
222 Map<PropertyDescriptor<?>, Object> getPropertiesByPropertyDescriptor();
223
224 /**
225 * Returns whether the descriptor is present on the receiver.
226 *
227 * @param descriptor
228 * @return boolean
229 */
230 boolean hasDescriptor(PropertyDescriptor<?> descriptor);
231
232 /**
233 * Returns whether the rule uses the default operating parameters.
234 * @return boolean
235 */
236 boolean usesDefaultValues();
237 /**
238 * Sets whether this Rule uses Data Flow Analysis.
239 */
240 // FUTURE Use JavaBean conventions for boolean attributes
241 void setUsesDFA();
242
243 /**
244 * Gets whether this Rule uses Data Flow Analysis.
245 */
246 // FUTURE Use JavaBean conventions for boolean attributes
247 boolean usesDFA();
248
249 /**
250 * Sets whether this Rule uses Type Resolution.
251 */
252 // FUTURE Use JavaBean conventions for boolean attributes
253 void setUsesTypeResolution();
254
255 /**
256 * Gets whether this Rule uses Type Resolution.
257 */
258 // FUTURE Use JavaBean conventions for boolean attributes
259 boolean usesTypeResolution();
260
261 /**
262 * Gets whether this Rule uses the RuleChain.
263 */
264 // FUTURE Use JavaBean conventions for boolean attributes
265 boolean usesRuleChain();
266
267 /**
268 * Gets the collection of AST node names visited by the Rule on the
269 * RuleChain.
270 */
271 List<String> getRuleChainVisits();
272
273 /**
274 * Adds an AST node by class to be visited by the Rule on the RuleChain.
275 */
276 void addRuleChainVisit(Class<? extends Node> nodeClass);
277
278 /**
279 * Adds an AST node by name to be visited by the Rule on the RuleChain.
280 */
281 void addRuleChainVisit(String astNodeName);
282
283 /**
284 * Start processing. Called once, before apply() is first called.
285 */
286 void start(RuleContext ctx);
287
288 /**
289 * Apply this rule to the given collection of nodes, using the
290 * given context.
291 */
292 void apply(List<? extends Node> nodes, RuleContext ctx);
293
294 /**
295 * End processing. Called once, after apply() is last called.
296 */
297 void end(RuleContext ctx);
298 }
|