Package org.kiwiproject.validation

Annotation Type FieldRange

  • @Documented
@Constraint(validatedBy=FieldRangeValidator.class)
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(FieldRanges.class)
public @interface FieldRange
    The annotated type must have two fields that define a valid range, i.e. in the simplest configuration startField() must come before endField(). You can have multiple FieldRange annotations on a type, either as standalone annotations or inside a FieldRanges annotation.

    The main restriction imposed by this annotation is that startField() and endField() must be Comparable. It is also assumed that they are defined to both have the same type, e.g. both are Integer or Instant. No guarantees are made if they are different types, and most likely unpredictable results and/or exceptions will occur.

    Note also that direct field access using reflection is used to obtain the start and end values as currently implemented.

    By default null values are not allowed, and the range check is exclusive, meaning start cannot equal end. You can change the default behavior using the various options.

    In addition to ensuring that the start and end fields define a valid range, you can also constrain them to minimum and/or maximum values.

    This validator's type support depends on whether minimum and maximum values are specified as part of the configuration. If minimum and/or maximum are specified, then the supported types are the same as those supported by Range since the minimum/maximum values must be converted from strings into the type of object that the start and end fields are. If there are no minimum or maximum values defined, then any type that implements Comparable is supported.

    Finally, assuming there are no minimum or maximum values specified and that the type being validated contains only a time component, e.g. LocalTime, then there is an edge case between 12:00 AM (00:00) and 1:00 AM (01:00) that may result in unexpected validation failures. For example, if the first time in the range is 11:56 PM (23:56) and the second is 12:15 AM (00:15), then without a date to indicate whether the times cross a midnight boundary, this range will be considered as invalid. The reason is simply that within a single day (again because there is no date component to indicate otherwise), 12:15 AM always comes before 23:56 PM.

    • Element Detail

      • startField

        String startField
        Returns:
        the name of the field that defines the range start

      • endField

        String endField
        Returns:
        the name of the field that defines the range end

      • message

        String message
        Default:
        "{org.kiwiproject.validation.FieldRange.between.message}"

      • groups

        Class<?>[] groups
        Default:
        {}

      • payload

        Class<? extends javax.validation.Payload>[] payload
        Default:
        {}

      • endFieldLabel

        String endFieldLabel
        Returns:
        the label to use in error messages instead of the end field
        Implementation Note:
        There is no equivalent for start field since the errors are attached to the start field, such that the message is defined relative to the start field. For example, the property path in a constraint violation is startField and will have the associated message "must occur before [endField|endFieldLabel]".
        Default:
        ""

      • allowStartToEqualEnd

        boolean allowStartToEqualEnd
        Returns:
        true if the start and end can be the same value; the default is false
        Default:
        false

      • allowNullStart

        boolean allowNullStart
        If true, the range only includes the end field. This is mainly useful when used with a max value.
        Returns:
        true to define a range that only considers the end field
        Default:
        false

      • allowNullEnd

        boolean allowNullEnd
        If true, the range only includes the start field. This is mainly useful when used with a min value.
        Returns:
        true to define a range that only considers the start field
        Default:
        false

      • min

        String min
        Returns:
        the minimum value allowed for the start of the range
        Default:
        ""

      • minLabel

        String minLabel
        Returns:
        the label to be used in error messages in place of the minimum value, e.g. "ten" instead of 10
        Default:
        ""

      • max

        String max
        Returns:
        the minimum value allowed for the end of the range
        Default:
        ""

      • maxLabel

        String maxLabel
        Returns:
        the label to be used in error messages in place of the maximum value, e.g. "ten" instead of 10
        Default:
        ""