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.List;
7   import java.util.Map;
8   import java.util.Set;
9   
10  /**
11   * Any entity that manages a list of properties is a {@link PropertySource}.
12   * These are e.g. Rules and Renderers.
13   * @author Brian Remedios
14   */
15  public interface PropertySource {
16  
17      /**
18       * Define a new property via a PropertyDescriptor.
19       * 
20       * @param propertyDescriptor The property descriptor.
21       * @throws IllegalArgumentException If there is already a property defined
22       *             the same name.
23       */
24      void definePropertyDescriptor(PropertyDescriptor<?> propertyDescriptor) throws IllegalArgumentException;
25  
26      /**
27       * Get the PropertyDescriptor for the given property name.
28       * 
29       * @param name The name of the property.
30       * @return The PropertyDescriptor for the named property, <code>null</code>
31       *         if there is no such property defined.
32       */
33      PropertyDescriptor<?> getPropertyDescriptor(String name);
34  
35      /**
36       * Get the PropertyDescriptors for all defined properties. The properties
37       * are returned sorted by UI order.
38       * 
39       * @return The PropertyDescriptors in UI order.
40       */
41      List<PropertyDescriptor<?>> getPropertyDescriptors();
42  
43      /**
44       * Get the typed value for the given property.
45       * 
46       * @param <T> The underlying type of the property descriptor.
47       * @param propertyDescriptor The property descriptor.
48       * @return The property value.
49       */
50      <T> T getProperty(PropertyDescriptor<T> propertyDescriptor);
51  
52      /**
53       * Set the property value specified (will be type-checked)
54       * 
55       * @param <T> The underlying type of the property descriptor.
56       * @param propertyDescriptor The property descriptor.
57       * @param value The value to set.
58       */
59      <T> void setProperty(PropertyDescriptor<T> propertyDescriptor, T value);
60  
61      /**
62       * Returns all the current property values for the receiver or an immutable
63       * empty map if none are specified.
64       * @return all current property values or a empty map.
65       */
66      Map<PropertyDescriptor<?>, Object> getPropertiesByPropertyDescriptor();
67  
68      /**
69       * Returns whether this Rule has the specified PropertyDescriptor.
70       * 
71       * @param descriptor The PropertyDescriptor for which to check.
72       * @return boolean <code>true</code> if the descriptor is present,
73       *         <code>false</code> otherwise.
74       */
75      boolean hasDescriptor(PropertyDescriptor<?> descriptor);
76  
77      /**
78       * Returns whether this Rule uses default values for properties.
79       * 
80       * @return boolean <code>true</code> if the properties all have default
81       *         values, <code>false</code> otherwise.
82       */
83      boolean usesDefaultValues();
84  
85      /**
86       * Clears out any user-specified value for the property allowing it to use
87       * the default value in the descriptor.
88       * 
89       * @param desc the property to clear out
90       */
91      void useDefaultValueFor(PropertyDescriptor<?> desc);
92  
93      /**
94       * Return the properties that are effectively ignored due to the
95       * configuration of the rule and values held by other properties. This can
96       * be used to disable corresponding widgets in a UI.
97       * 
98       * @return the properties that are ignored
99       */
100     Set<PropertyDescriptor<?>> ignoredProperties();
101 
102     /**
103      * Returns a description of why the receiver may be dysfunctional. Usually
104      * due to missing property values or some kind of conflict between values.
105      * Returns null if the receiver is ok.
106      * 
107      * @return String
108      */
109     String dysfunctionReason();
110 }