Creating Range-Constrained Numeric Annotations

Java annotations provide a powerful mechanism for embedding metadata within source code. They enable developers to specify constraints and behaviors without altering the core logic of aplications.

To enforce that numeric values remain at or above zero, we can create a custom annotation combined with runtime validation.

Defining the Constraint Annotation

A custom annotation interface is declared using the @interface keyword. For our use case, we define an annotation that specifies a minimum acceptable value:

public @interface NonNegative {
    int minValue() default 0;
}

This creates a NonNegative annotation with a configurable threshold, defaulting to zero.

Applying the Annotation

Once defined, the annotation can be applied to class fields requiring validation:

class ValueContainer {
    @NonNegative
    private int amount;
    
    public int getAmount() {
        return amount;
    }
    
    public void setAmount(int amount) {
        this.amount = amount;
    }
}

The amount field is now marked with the constraint, indicating it should not fall below the specified limit.

Implementing Validation Logic

Runtime enforcement requires a component capable of inspecting annotated elements. Using reflection, we can build a validator that checks field values against their annotations:

public class Validator {
    public static void validate(Object target) {
        Field[] fields = target.getClass().getDeclaredFields();
        
        for (Field field : fields) {
            if (field.isAnnotationPresent(NonNegative.class)) {
                NonNegative constraint = field.getAnnotation(NonNegative.class);
                int threshold = constraint.minValue();
                
                try {
                    field.setAccessible(true);
                    int currentValue = (int) field.get(target);
                    
                    if (currentValue < threshold) {
                        throw new IllegalStateException(
                            "Field '" + field.getName() + "' must be >= " + threshold
                        );
                    }
                } catch (IllegalAccessException exception) {
                    exception.printStackTrace();
                }
            }
        }
    }
}

This validator iterates through all declared fields, identifies those annotated with NonNegative, and ensures their current values meet the required condition.

Validation Example

Here's how the validation mechanism operates in practice:

public class Application {
    public static void main(String[] args) {
        ValueContainer container = new ValueContainer();
        container.setAmount(15);
        
        try {
            Validator.validate(container);
            System.out.println("Validation passed");
        } catch (IllegalStateException error) {
            System.err.println("Validation failed: " + error.getMessage());
        }
    }
}

In this example, setting amount to a positive value results in successful validation.