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 }