diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index 6974987f9d..dc0aab759f 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -96,6 +96,12 @@ by a corresponding method on `PropertyFactory`: * {% jdoc props::BooleanProperty %} is replaced by {% jdoc !c!:PF#booleanProperty(java.lang.String) %} * Its multi-valued counterpart, {% jdoc props::BooleanMultiProperty %}, is not replaced, because it doesn't have a use case. + * {% jdoc props::CharacterProperty %} is replaced by {% jdoc !c!:PF#charProperty(java.lang.String) %} + * {% jdoc props::CharacterMultiProperty %} is replaced by {% jdoc !c!:PF#charListProperty(java.lang.String) %} + + * {% jdoc props::LongProperty %} is replaced by {% jdoc !c!:PF#longIntProperty(java.lang.String) %} + * {% jdoc props::LongMultiProperty %} is replaced by {% jdoc !c!:PF#longIntListProperty(java.lang.String) %} + * {% jdoc props::MethodProperty %}, {% jdoc props::FileProperty %}, {% jdoc props::TypeProperty %} and their multi-valued counterparts are discontinued for lack of a use-case, and have no planned replacement in 7.0.0 for now. diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterMultiProperty.java b/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterMultiProperty.java index e94c3840e8..db45c30273 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterMultiProperty.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterMultiProperty.java @@ -19,7 +19,10 @@ import net.sourceforge.pmd.properties.builders.PropertyDescriptorBuilderConversi * * @author Brian Remedios * @version Refactored June 2017 (6.0.0) + * @deprecated Use a {@code PropertyDescriptor>}. A builder is available from {@link PropertyFactory#charListProperty(String)}. + * This class will be removed in 7.0.0. */ +@Deprecated public final class CharacterMultiProperty extends AbstractMultiValueProperty { @@ -33,7 +36,9 @@ public final class CharacterMultiProperty extends AbstractMultiValueProperty defaultValues, float theUIOrder, char delimiter) { this(theName, theDescription, defaultValues, theUIOrder, delimiter, false); } @@ -104,11 +111,19 @@ public final class CharacterMultiProperty extends AbstractMultiValueProperty { private CharacterMultiPBuilder(String name) { super(name); diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterProperty.java b/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterProperty.java index ba90f2b3f3..5cb8752b5d 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterProperty.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/properties/CharacterProperty.java @@ -15,7 +15,10 @@ import net.sourceforge.pmd.properties.builders.SingleValuePropertyBuilder; * * @author Brian Remedios * @version Refactored June 2017 (6.0.0) + * @deprecated Use a {@code PropertyDescriptor}. A builder is available from {@link PropertyFactory#charProperty(String)}. + * This class will be removed in 7.0.0. */ +@Deprecated public final class CharacterProperty extends AbstractSingleValueProperty { /** @@ -27,8 +30,9 @@ public final class CharacterProperty extends AbstractSingleValueProperty { private CharacterPBuilder(String name) { super(name); diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongMultiProperty.java b/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongMultiProperty.java index eb07bf17bc..3634c506b9 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongMultiProperty.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongMultiProperty.java @@ -16,7 +16,11 @@ import net.sourceforge.pmd.properties.builders.PropertyDescriptorBuilderConversi * * @author Brian Remedios * @version Refactored June 2017 (6.0.0) + * + * @deprecated Use a {@code PropertyDescriptor>} instead. A builder is available from {@link PropertyFactory#longIntListProperty(String)}. + * This class will be removed in 7.0.0. */ +@Deprecated public final class LongMultiProperty extends AbstractMultiNumericProperty { @@ -31,7 +35,9 @@ public final class LongMultiProperty extends AbstractMultiNumericProperty * @param theUIOrder UI order * * @throws IllegalArgumentException if {@literal min > max} or one of the defaults is not between the bounds + * @deprecated Use {@link PropertyFactory#longIntListProperty(String)} */ + @Deprecated public LongMultiProperty(String theName, String theDescription, Long min, Long max, Long[] defaultValues, float theUIOrder) { this(theName, theDescription, min, max, Arrays.asList(defaultValues), theUIOrder, false); @@ -56,7 +62,9 @@ public final class LongMultiProperty extends AbstractMultiNumericProperty * @param theUIOrder UI order * * @throws IllegalArgumentException if {@literal min > max} or one of the defaults is not between the bounds + * @deprecated Use {@link PropertyFactory#longIntListProperty(String)} */ + @Deprecated public LongMultiProperty(String theName, String theDescription, Long min, Long max, List defaultValues, float theUIOrder) { this(theName, theDescription, min, max, defaultValues, theUIOrder, false); @@ -85,11 +93,15 @@ public final class LongMultiProperty extends AbstractMultiNumericProperty } + /** @deprecated Use {@link PropertyFactory#longIntListProperty(String)} */ + @Deprecated public static LongMultiPBuilder named(String name) { return new LongMultiPBuilder(name); } + /** @deprecated Use {@link PropertyFactory#longIntListProperty(String)} */ + @Deprecated public static final class LongMultiPBuilder extends MultiNumericPropertyBuilder { diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongProperty.java b/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongProperty.java index 020dc50f3e..e420a3b739 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongProperty.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/properties/LongProperty.java @@ -14,7 +14,11 @@ import net.sourceforge.pmd.properties.builders.SingleNumericPropertyBuilder; * @author Brian Remedios * @author Clément Fournier * @version Refactored June 2017 (6.0.0) + * + * @deprecated Use a {@code PropertyDescriptor} instead. A builder is available from {@link PropertyFactory#longIntProperty(String)}. + * This class will be removed in 7.0.0. */ +@Deprecated public final class LongProperty extends AbstractNumericProperty { @@ -30,8 +34,9 @@ public final class LongProperty extends AbstractNumericProperty { * @param theUIOrder UI order * * @throws IllegalArgumentException if {@literal min > max} or one of the defaults is not between the bounds - * @deprecated will be removed in 7.0.0 + * @deprecated Use {@link PropertyFactory#longIntProperty(String)} */ + @Deprecated public LongProperty(String theName, String theDescription, String minStr, String maxStr, String defaultStr, float theUIOrder) { this(theName, theDescription, Long.valueOf(minStr), Long.valueOf(maxStr), @@ -57,7 +62,9 @@ public final class LongProperty extends AbstractNumericProperty { * @param theUIOrder UI order * * @throws IllegalArgumentException if {@literal min > max} or one of the defaults is not between the bounds + * @deprecated Use {@link PropertyFactory#longIntProperty(String)} */ + @Deprecated public LongProperty(String theName, String theDescription, Long min, Long max, Long theDefault, float theUIOrder) { this(theName, theDescription, min, max, theDefault, theUIOrder, false); } @@ -85,11 +92,15 @@ public final class LongProperty extends AbstractNumericProperty { } + /** @deprecated Use {@link PropertyFactory#longIntProperty(String)} */ + @Deprecated public static LongPBuilder named(String name) { return new LongPBuilder(name); } + /** @deprecated Use {@link PropertyFactory#longIntProperty(String)} */ + @Deprecated public static final class LongPBuilder extends SingleNumericPropertyBuilder { private LongPBuilder(String name) { super(name); diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/properties/PropertyFactory.java b/pmd-core/src/main/java/net/sourceforge/pmd/properties/PropertyFactory.java index edcfe2949e..3de0c57225 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/properties/PropertyFactory.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/properties/PropertyFactory.java @@ -46,7 +46,7 @@ import net.sourceforge.pmd.properties.constraints.PropertyConstraint; * 
  * class MyRule {
  *   // The property descriptor may be static, it can be shared across threads.
- *   private static final {@link PropertyDescriptor}<Integer> myIntProperty
+ *   private static final {@link PropertyDescriptor}<Integer> myIntProperty
  *     = PropertyFactory.{@linkplain #intProperty(String) intProperty}("myIntProperty")
  *                      .{@linkplain PropertyBuilder#desc(String) desc}("This is my property")
  *                      .{@linkplain PropertyBuilder#defaultValue(Object) defaultValue}(3)
@@ -83,7 +83,10 @@ public final class PropertyFactory {
      * Returns a builder for an integer property. The property descriptor
      * will by default accept any value conforming to the format specified
      * by {@link Integer#parseInt(String)}, e.g. {@code 1234} or {@code -123}.
-     * Acceptable values may be further refined by {@linkplain PropertyBuilder#require(PropertyConstraint) adding constraints}.
+     *
+     * 
Note that that parser only supports decimal representations.
+     *
+     * 
Acceptable values may be further refined by {@linkplain PropertyBuilder#require(PropertyConstraint) adding constraints}.
      * The class {@link NumericConstraints} provides some useful ready-made constraints
      * for that purpose.
      *
@@ -111,6 +114,43 @@ public final class PropertyFactory {
     }
 
 
+    /**
+     * Returns a builder for a long integer property. The property descriptor
+     * will by default accept any value conforming to the format specified
+     * by {@link Long#parseLong(String)}, e.g. {@code 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 {@linkplain PropertyBuilder#require(PropertyConstraint) adding constraints}.
+     * The class {@link NumericConstraints} provides some useful ready-made constraints
+     * for that purpose.
+     *
+     * @param name Name of the property to build
+     *
+     * @return A new builder
+     *
+     * @see NumericConstraints
+     */
+    public static GenericPropertyBuilder longIntProperty(String name) {
+        return new GenericPropertyBuilder<>(name, ValueParserConstants.LONG_PARSER, Long.class);
+    }
+
+
+    /**
+     * Returns a builder for a property having as value a list of long integers. The
+     * format of the individual items is the same as for {@linkplain #longIntProperty(String)} longIntProperty}.
+     *
+     * @param name Name of the property to build
+     *
+     * @return A new builder
+     */
+    public static GenericCollectionPropertyBuilder> longIntListProperty(String name) {
+        return longIntProperty(name).toList().delim(MultiValuePropertyDescriptor.DEFAULT_NUMERIC_DELIMITER);
+    }
+
+
     /**
      * Returns a builder for a double property. The property descriptor
      * will by default accept any value conforming to the format specified
@@ -166,8 +206,8 @@ public final class PropertyFactory {
      * Returns a builder for a string property. The property descriptor
      * will accept any string, and performs no expansion of escape
      * sequences (e.g. {@code \n} in the XML will be represented as the
-     * character sequence '\' 'n' and not the line-feed character '\n'). This
-     * behaviour could be changed with PMD 7.0.0.
+     * character sequence '\' 'n' and not the line-feed character '\n').
+     * This behaviour could be changed with PMD 7.0.0.
      *
      * @param name Name of the property to build
      *
@@ -191,6 +231,37 @@ public final class PropertyFactory {
     }
 
 
+    /**
+     * 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 {@literal &} ('&') or {@literal <} ('<').
+     *
+     * @param name Name of the property to build
+     *
+     * @return A new builder
+     */
+    public static GenericPropertyBuilder charProperty(String name) {
+        return new GenericPropertyBuilder<>(name, ValueParserConstants.CHARACTER_PARSER, Character.class);
+    }
+
+
+    /**
+     * Returns a builder for a property having as value a list of characters. The
+     * format of the individual items is the same as for {@linkplain #charProperty(String) charProperty}.
+     *
+     * @param name Name of the property to build
+     *
+     * @return A new builder
+     */
+    public static GenericCollectionPropertyBuilder> charListProperty(String name) {
+        return charProperty(name).toList();
+    }
+
+
     /**
      * Returns a builder for a boolean property. The boolean is parsed from
      * the XML using {@link Boolean#valueOf(String)}, i.e. the only truthy
diff --git a/pmd-core/src/test/java/net/sourceforge/pmd/properties/CharacterPropertyTest.java b/pmd-core/src/test/java/net/sourceforge/pmd/properties/CharacterPropertyTest.java
index 06c2ff574c..d0a50c7e7b 100644
--- a/pmd-core/src/test/java/net/sourceforge/pmd/properties/CharacterPropertyTest.java
+++ b/pmd-core/src/test/java/net/sourceforge/pmd/properties/CharacterPropertyTest.java
@@ -15,6 +15,7 @@ import org.junit.Test;
  *
  * @author Brian Remedios
  */
+@Deprecated
 public class CharacterPropertyTest extends AbstractPropertyDescriptorTester {
 
     private static final char DELIMITER = '|';
diff --git a/pmd-core/src/test/java/net/sourceforge/pmd/properties/LongPropertyTest.java b/pmd-core/src/test/java/net/sourceforge/pmd/properties/LongPropertyTest.java
index a35ce908db..878ec3f4c8 100644
--- a/pmd-core/src/test/java/net/sourceforge/pmd/properties/LongPropertyTest.java
+++ b/pmd-core/src/test/java/net/sourceforge/pmd/properties/LongPropertyTest.java
@@ -10,6 +10,7 @@ import java.util.List;
 /**
  * @author Clément Fournier
  */
+@Deprecated
 public class LongPropertyTest extends AbstractNumericPropertyDescriptorTester {
 
     private static final long MIN = 10L;