View Javadoc

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