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 }