View Javadoc

    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 }