Class PropertyFactory


  • public final class PropertyFactory
    extends Object
    Provides factory methods for common property types. Note: from 7.0.0 on, this will be the only way to build property descriptors. Concrete property classes and their constructors/ builders will be gradually deprecated before 7.0.0.

    Usage

    Properties are a way to make your rule configurable by letting a user fill in some config value in their ruleset XML. As a rule developer, to declare a property on your rule, you must: You can then retrieve the value configured by the user in your rule using PropertySource.getProperty(PropertyDescriptor).

    Example

     class MyRule {
       // The property descriptor may be static, it can be shared across threads.
       private static final PropertyDescriptor<Integer> myIntProperty
         = PropertyFactory.intProperty("myIntProperty")
                          .desc("This is my property")
                          .defaultValue(3)
                          .require(inRange(0, 100))   // constraints are checked before the rule is run
                          .build();
    
       // ..
    
       public MyRule() {
         definePropertyDescriptor(myIntProperty);
       }
    
         // ... somewhere in the rule
    
         int myPropertyValue = getProperty(myIntProperty);
         // use it.
    
     }
     
    Author:
    Clément Fournier
    Since:
    6.10.0
    • Field Detail

      • DEFAULT_DELIMITER

        public static final char DEFAULT_DELIMITER
        Default delimiter for all properties. Note that in PMD 6 this was the pipe character |, while now it is 44. In PMD 6, numeric properties had a different delimiter, whereas in PMD 7, all properties have the same delimiter.
        See Also:
        Constant Field Values
    • Method Detail

      • longIntProperty

        public static PropertyBuilder.GenericPropertyBuilder<Long> longIntProperty​(String name)
        Returns a builder for a long integer property. The property descriptor will by default accept any value conforming to the format specified by Long.parseLong(String), e.g. 1234455678854.

        Note that that parser only supports decimal representations, and that neither the character L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java source.

        Acceptable values may be further refined by adding constraints. The class NumericConstraints provides some useful ready-made constraints for that purpose.

        Parameters:
        name - Name of the property to build
        Returns:
        A new builder
        See Also:
        NumericConstraints
      • regexProperty

        public static PropertyBuilder.RegexPropertyBuilder regexProperty​(String name)
        Returns a builder for a regex property. The value type of such a property is Pattern. For this use case, this type of property should be preferred over stringProperty as pattern compilation, including syntax errors, are handled transparently to the rule.
        Parameters:
        name - Name of the property to build
        Returns:
        A new builder
      • stringProperty

        public static PropertyBuilder.GenericPropertyBuilder<String> stringProperty​(String name)
        Returns a builder for a string property. The property descriptor will accept any string, and performs no expansion of escape sequences (e.g. \n in the XML will be represented as the character sequence '\' 'n' and not the line-feed character '\n'). The value of a string attribute is trimmed. This behaviour could be changed with PMD 7.0.0.
        Parameters:
        name - Name of the property to build
        Returns:
        A new builder
      • charProperty

        public static PropertyBuilder.GenericPropertyBuilder<Character> charProperty​(String name)
        Returns a builder for a character property. The property descriptor will accept any single character string. No unescaping is performed other than what the XML parser does itself. That means that Java escape sequences are not expanded: e.g. "\n", will be represented as the character sequence '\' 'n', so it's not a valid value for this type of property. On the other hand, XML character references are expanded, like &amp; ('&') or &lt; ('<').
        Parameters:
        name - Name of the property to build
        Returns:
        A new builder
      • booleanProperty

        public static PropertyBuilder.GenericPropertyBuilder<Boolean> booleanProperty​(String name)
        Returns a builder for a boolean property. The boolean is parsed from the XML using Boolean.valueOf(String), i.e. the only truthy value is the string "true", and all other string values are falsy.
        Parameters:
        name - Name of the property to build
        Returns:
        A new builder
      • enumProperty

        public static <T> PropertyBuilder.GenericPropertyBuilder<T> enumProperty​(String name,
                                                                                 Map<String,​T> nameToValue)
        Returns a builder for an enumerated property. Such a property can be defined for any type <T>, provided the possible values can be indexed by strings. This is enforced by passing a Map<String, T> at construction time, which maps labels to values. If Map.get(Object) returns null for a given label, then the value is rejected. Null values are hence prohibited.
        Type Parameters:
        T - Value type of the property
        Parameters:
        name - Name of the property to build
        nameToValue - Map of labels to values. The null key is ignored.
        Returns:
        A new builder
        Throws:
        IllegalArgumentException - If the map contains a null value or key
      • enumProperty

        public static <T extends Enum<T>> PropertyBuilder.GenericPropertyBuilder<T> enumProperty​(String name,
                                                                                                 Class<T> enumClass)
        Returns a builder for an enumerated property for the given enum class, using the toString of its enum constants as labels.
        Type Parameters:
        T - Type of the enum class
        Parameters:
        name - Property name
        enumClass - Enum class
        Returns:
        A new builder
      • enumProperty

        public static <T extends Enum<T>> PropertyBuilder.GenericPropertyBuilder<T> enumProperty​(String name,
                                                                                                 Class<T> enumClass,
                                                                                                 Function<? super T,​@NonNull String> labelMaker)
        Returns a builder for an enumerated property for the given enum class, using the given function to label its constants.
        Type Parameters:
        T - Type of the enum class
        Parameters:
        name - Property name
        enumClass - Enum class
        labelMaker - Function that labels each constant
        Returns:
        A new builder
        Throws:
        NullPointerException - If any of the arguments is null
        IllegalArgumentException - If the label maker returns null on some constant
        IllegalStateException - If the label maker maps two constants to the same label
      • enumListProperty

        public static <T> PropertyBuilder.GenericCollectionPropertyBuilder<T,​List<T>> enumListProperty​(String name,
                                                                                                             Map<String,​T> nameToValue)
        Returns a builder for a property having as value a list of <T>. The format of the individual items is the same as for enumProperty(String, Map).
        Type Parameters:
        T - Value type of the property
        Parameters:
        name - Name of the property to build
        nameToValue - Map of labels to values. The null key is ignored.
        Returns:
        A new builder
      • enumListProperty

        public static <T extends Enum<T>> PropertyBuilder.GenericCollectionPropertyBuilder<T,​List<T>> enumListProperty​(String name,
                                                                                                                             Class<T> enumClass,
                                                                                                                             Function<? super T,​String> labelMaker)
        Returns a builder for a property having as value a list of <T>. The format of the individual items is the same as for enumProperty(String, Map).
        Type Parameters:
        T - Value type of the property
        Parameters:
        name - Name of the property to build
        enumClass - Class of the values
        labelMaker - Function that associates enum constants to their label
        Returns:
        A new builder