001: package net.sourceforge.pmd;
002:
003: /**
004: * Property value descriptor that defines the use & requirements for setting
005: * property values for use within PMD and any associated GUIs.
006: *
007: * @author Brian Remedios
008: * @version $Revision$
009: */
010: public interface PropertyDescriptor extends
011: Comparable<PropertyDescriptor> {
012:
013: PropertyDescriptor[] emptyPropertySet = new PropertyDescriptor[0];
014:
015: /**
016: * The name of the property without spaces as it serves
017: * as the key into the property map.
018: *
019: * @return String
020: */
021: String name();
022:
023: /**
024: * Describes the property and the role it plays within the
025: * rule it is specified for. Could be used in a tooltip.
026: *
027: * @return String
028: */
029: String description();
030:
031: /**
032: * Denotes the value datatype.
033: * @return Class
034: */
035: Class<?> type();
036:
037: /**
038: * If the property is multi-valued, i.e. an array of strings, then this
039: * returns the maximum number permitted. Unary property rule properties
040: * normally return a value of one.
041: *
042: * @return int
043: */
044: int maxValueCount();
045:
046: /**
047: * Default value to use when the user hasn't specified one or when they wish
048: * to revert to a known-good state.
049: *
050: * @return Object
051: */
052: Object defaultValue();
053:
054: /**
055: * Denotes whether the value is required before the rule can be executed.
056: * Has no meaning for primitive types such as booleans, ints, etc.
057: *
058: * @return boolean
059: */
060: boolean isRequired();
061:
062: /**
063: * Validation function that returns a diagnostic error message for a sample
064: * property value. Returns null if the value is acceptable.
065: *
066: * @param value Object
067: * @return String
068: */
069: String errorFor(Object value);
070:
071: /**
072: * Denotes the relative order the property field should occupy if we are using
073: * an auto-generated UI to display and edit values. If the value returned has
074: * a non-zero fractional part then this is can be used to place adjacent fields
075: * on the same row. Example:
076: *
077: * name -> 0.0
078: * description 1.0
079: * minValue -> 2.0
080: * 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
095: * property 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: Object valueFrom(String propertyString)
102: throws IllegalArgumentException;
103:
104: /**
105: * Formats the object onto a string suitable for storage within the property map.
106: * @param value Object
107: * @return String
108: */
109: String asDelimitedString(Object value);
110:
111: /**
112: * Returns a set of choice tuples of available, returns null if none present.
113: * @return Object[]
114: */
115: Object[][] choices();
116:
117: /**
118: * A convenience method that returns an error string if the rule holds onto a
119: * property value that has a problem. Returns null otherwise.
120: *
121: * @param rule Rule
122: * @return String
123: */
124: String propertyErrorFor(Rule rule);
125:
126: /**
127: * Return the character being used to delimit multiple property values within
128: * a single string. You must ensure that this character does not appear within
129: * any rule property values to avoid deserialization errors.
130: *
131: * @return char
132: */
133: char multiValueDelimiter();
134:
135: /**
136: * If the datatype is a String then return the preferred number of rows to
137: * allocate in the text widget, returns a value of one for all other types.
138: * Useful for multi-line XPATH editors.
139: *
140: * @return int
141: */
142: int preferredRowCount();
143: }
|