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 import java.util.Map;
8 import java.util.Set;
9
10 /**
11 * Any entity that manages a list of properties is a {@link PropertySource}.
12 * These are e.g. Rules and Renderers.
13 * @author Brian Remedios
14 */
15 public interface PropertySource {
16
17 /**
18 * Define a new property via a PropertyDescriptor.
19 *
20 * @param propertyDescriptor The property descriptor.
21 * @throws IllegalArgumentException If there is already a property defined
22 * the same name.
23 */
24 void definePropertyDescriptor(PropertyDescriptor<?> propertyDescriptor) throws IllegalArgumentException;
25
26 /**
27 * Get the PropertyDescriptor for the given property name.
28 *
29 * @param name The name of the property.
30 * @return The PropertyDescriptor for the named property, <code>null</code>
31 * if there is no such property defined.
32 */
33 PropertyDescriptor<?> getPropertyDescriptor(String name);
34
35 /**
36 * Get the PropertyDescriptors for all defined properties. The properties
37 * are returned sorted by UI order.
38 *
39 * @return The PropertyDescriptors in UI order.
40 */
41 List<PropertyDescriptor<?>> getPropertyDescriptors();
42
43 /**
44 * Get the typed value for the given property.
45 *
46 * @param <T> The underlying type of the property descriptor.
47 * @param propertyDescriptor The property descriptor.
48 * @return The property value.
49 */
50 <T> T getProperty(PropertyDescriptor<T> propertyDescriptor);
51
52 /**
53 * Set the property value specified (will be type-checked)
54 *
55 * @param <T> The underlying type of the property descriptor.
56 * @param propertyDescriptor The property descriptor.
57 * @param value The value to set.
58 */
59 <T> void setProperty(PropertyDescriptor<T> propertyDescriptor, T value);
60
61 /**
62 * Returns all the current property values for the receiver or an immutable
63 * empty map if none are specified.
64 * @return all current property values or a empty map.
65 */
66 Map<PropertyDescriptor<?>, Object> getPropertiesByPropertyDescriptor();
67
68 /**
69 * Returns whether this Rule has the specified PropertyDescriptor.
70 *
71 * @param descriptor The PropertyDescriptor for which to check.
72 * @return boolean <code>true</code> if the descriptor is present,
73 * <code>false</code> otherwise.
74 */
75 boolean hasDescriptor(PropertyDescriptor<?> descriptor);
76
77 /**
78 * Returns whether this Rule uses default values for properties.
79 *
80 * @return boolean <code>true</code> if the properties all have default
81 * values, <code>false</code> otherwise.
82 */
83 boolean usesDefaultValues();
84
85 /**
86 * Clears out any user-specified value for the property allowing it to use
87 * the default value in the descriptor.
88 *
89 * @param desc the property to clear out
90 */
91 void useDefaultValueFor(PropertyDescriptor<?> desc);
92
93 /**
94 * Return the properties that are effectively ignored due to the
95 * configuration of the rule and values held by other properties. This can
96 * be used to disable corresponding widgets in a UI.
97 *
98 * @return the properties that are ignored
99 */
100 Set<PropertyDescriptor<?>> ignoredProperties();
101
102 /**
103 * Returns a description of why the receiver may be dysfunctional. Usually
104 * due to missing property values or some kind of conflict between values.
105 * Returns null if the receiver is ok.
106 *
107 * @return String
108 */
109 String dysfunctionReason();
110 }