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