1 package net.sourceforge.pmd;
2
3 import java.util.Map;
4
5 /**
6 * Property value descriptor that defines the use & requirements for setting
7 * property values for use within PMD and any associated GUIs. While concrete
8 * descriptor instances are static and immutable they provide validation,
9 * serialization, and default values for any specific datatypes.
10 *
11 * @author Brian Remedios
12 * @param <T>
13 */
14 public interface PropertyDescriptor<T extends Object> extends Comparable<PropertyDescriptor<?>> {
15 /**
16 * The name of the property without spaces as it serves as the key into the
17 * property map.
18 *
19 * @return String
20 */
21 String name();
22
23 /**
24 * Describes the property and the role it plays within the rule it is
25 * specified for. Could be used in a tooltip.
26 *
27 * @return String
28 */
29 String description();
30
31 /**
32 * Denotes the value datatype.
33 *
34 * @return Class
35 */
36 Class<T> type();
37
38 /**
39 * Returns whether the property is multi-valued, i.e. an array of strings,
40 *
41 * As unary property rule properties will return a value of one, you must
42 * use the get/setProperty accessors when working with the actual values.
43 * When working with multi-value properties then the get/setProperties
44 * accessors must be used.
45 *
46 * @return boolean
47 */
48 boolean isMultiValue();
49
50 /**
51 * Default value to use when the user hasn't specified one or when they wish
52 * to revert to a known-good state.
53 *
54 * @return Object
55 */
56 T defaultValue();
57
58 /**
59 * Denotes whether the value is required before the rule can be executed.
60 * Has no meaning for primitive types such as booleans, ints, etc.
61 *
62 * @return boolean
63 */
64 boolean isRequired();
65
66 /**
67 * Validation function that returns a diagnostic error message for a sample
68 * property value. Returns null if the value is acceptable.
69 *
70 * @param value Object
71 * @return String
72 */
73 String errorFor(Object value);
74
75 /**
76 * Denotes the relative order the property field should occupy if we are
77 * using an auto-generated UI to display and edit property values. If the
78 * value returned has a non-zero fractional part then this is can be used to
79 * place adjacent fields on the same row. Example:
80 *
81 * name -> 0.0 description 1.0 minValue -> 2.0 maxValue -> 2.1
82 *
83 * ..would have their fields placed like:
84 *
85 * name: [ ]
86 * description: [ ]
87 * minimum: [ ] maximum: [ ]
88 *
89 * @return float
90 */
91 float uiOrder();
92
93 /**
94 * If the property is multi-valued then return the separate values after
95 * parsing the propertyString provided. If it isn't a multi-valued property
96 * then the value will be returned within an array of size[1].
97 *
98 * @param propertyString String
99 * @return Object
100 * @throws IllegalArgumentException
101 */
102 T valueFrom(String propertyString) throws IllegalArgumentException;
103
104 /**
105 * Formats the object onto a string suitable for storage within the property
106 * map.
107 *
108 * @param value Object
109 * @return String
110 */
111 String asDelimitedString(T value);
112
113 /**
114 * Returns a set of choice tuples if available, returns null if none are
115 * defined.
116 *
117 * @return Object[][]
118 */
119 Object[][] choices();
120
121 /**
122 * A convenience method that returns an error string if the rule holds onto
123 * a property value that has a problem. Returns null otherwise.
124 *
125 * @param rule Rule
126 * @return String
127 */
128 String propertyErrorFor(Rule rule);
129
130 /**
131 * Return the character being used to delimit multiple property values
132 * within a single string. You must ensure that this character does not
133 * appear within any rule property values to avoid deserialization errors.
134 *
135 * @return char
136 */
137 char multiValueDelimiter();
138
139 /**
140 * If the datatype is a String then return the preferred number of rows to
141 * allocate in the text widget, returns a value of one for all other types.
142 * Useful for multi-line XPATH editors.
143 *
144 * @return int
145 */
146 int preferredRowCount();
147
148 /**
149 * Returns a map representing all the property attributes of the receiver
150 * in string form.
151 *
152 * @return Map<String, String>
153 */
154 Map<String, String> attributeValuesById();
155 }