View Javadoc

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 }