001 package net.sourceforge.pmd;
002
003 import java.util.Map;
004
005 /**
006 * Property value descriptor that defines the use & requirements for setting
007 * property values for use within PMD and any associated GUIs. While concrete
008 * descriptor instances are static and immutable they provide validation,
009 * serialization, and default values for any specific datatypes.
010 *
011 * @author Brian Remedios
012 */
013 public interface PropertyDescriptor<T extends Object> extends Comparable<PropertyDescriptor<?>> {
014 /**
015 * The name of the property without spaces as it serves as the key into the
016 * property map.
017 *
018 * @return String
019 */
020 String name();
021
022 /**
023 * Describes the property and the role it plays within the rule it is
024 * specified for. Could be used in a tooltip.
025 *
026 * @return String
027 */
028 String description();
029
030 /**
031 * Denotes the value datatype.
032 *
033 * @return Class
034 */
035 Class<T> type();
036
037 /**
038 * Returns whether the property is multi-valued, i.e. an array of strings,
039 *
040 * As unary property rule properties will return a value of one, you must
041 * use the get/setProperty accessors when working with the actual values.
042 * When working with multi-value properties then the get/setProperties
043 * accessors must be used.
044 *
045 * @return boolean
046 */
047 boolean isMultiValue();
048
049 /**
050 * Default value to use when the user hasn't specified one or when they wish
051 * to revert to a known-good state.
052 *
053 * @return Object
054 */
055 T defaultValue();
056
057 /**
058 * Denotes whether the value is required before the rule can be executed.
059 * Has no meaning for primitive types such as booleans, ints, etc.
060 *
061 * @return boolean
062 */
063 boolean isRequired();
064
065 /**
066 * Validation function that returns a diagnostic error message for a sample
067 * property value. Returns null if the value is acceptable.
068 *
069 * @param value Object
070 * @return String
071 */
072 String errorFor(Object value);
073
074 /**
075 * Denotes the relative order the property field should occupy if we are
076 * using an auto-generated UI to display and edit property values. If the
077 * value returned has a non-zero fractional part then this is can be used to
078 * place adjacent fields on the same row. Example:
079 *
080 * name -> 0.0 description 1.0 minValue -> 2.0 maxValue -> 2.1
081 *
082 * ..would have their fields placed like:
083 *
084 * name: [ ]
085 * description: [ ]
086 * minimum: [ ] maximum: [ ]
087 *
088 * @return float
089 */
090 float uiOrder();
091
092 /**
093 * If the property is multi-valued then return the separate values after
094 * parsing the propertyString provided. If it isn't a multi-valued property
095 * then the value will be returned within an array of size[1].
096 *
097 * @param propertyString String
098 * @return Object
099 * @throws IllegalArgumentException
100 */
101 T valueFrom(String propertyString) throws IllegalArgumentException;
102
103 /**
104 * Formats the object onto a string suitable for storage within the property
105 * map.
106 *
107 * @param value Object
108 * @return String
109 */
110 String asDelimitedString(T value);
111
112 /**
113 * Returns a set of choice tuples if available, returns null if none are
114 * defined.
115 *
116 * @return Object[][]
117 */
118 Object[][] choices();
119
120 /**
121 * A convenience method that returns an error string if the rule holds onto
122 * a property value that has a problem. Returns null otherwise.
123 *
124 * @param rule Rule
125 * @return String
126 */
127 String propertyErrorFor(Rule rule);
128
129 /**
130 * Return the character being used to delimit multiple property values
131 * within a single string. You must ensure that this character does not
132 * appear within any rule property values to avoid deserialization errors.
133 *
134 * @return char
135 */
136 char multiValueDelimiter();
137
138 /**
139 * If the datatype is a String then return the preferred number of rows to
140 * allocate in the text widget, returns a value of one for all other types.
141 * Useful for multi-line XPATH editors.
142 *
143 * @return int
144 */
145 int preferredRowCount();
146
147 /**
148 * Returns a map representing all the property attributes of the receiver
149 * in string form.
150 *
151 * @return Map<String, String>
152 */
153 Map<String, String> attributeValuesById();
154 }
|