View Javadoc

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 }