Quick Start

This guide will walk you through creating your first validator, using predefined rules, and handling validation errors. By the end, you’ll have a working validator for a user registration form.

Your First Validator

Let’s start by creating a simple validator that checks if a string is not null and equals “xxx”.

Create a basic validator

Create a new validator instance and add custom rules using lambda expressions:

HelloValidator.java

import io.github.ApamateSoft.validator.Validator;

public class HelloValidator {

  public static void main(String[] args) {

    // Instantiating a new validator
    Validator validator = new Validator.Builder();

    // First rule: checks if string is not null
    validator.rule("Enter a text other than null", (String evaluate) -> {
      return evaluate != null;
    });

    // Second rule: checks if string equals "xxx"
    validator.rule("The text is different from 'xxx'", (String evaluate) -> {
      return evaluate.equals("xxx");
    });

    // Test the validator
    System.out.println(validator.isValid("xxx"));  // true
    System.out.println(validator.isValid("abc"));  // false
  }

}

Rules are evaluated in the order they were added
When a rule fails, the remaining rules are ignored
A string is valid only if it passes all rules

Use the Builder pattern

Simplify your code with the fluent Builder API:

import io.github.ApamateSoft.validator.Validator;
import java.util.Objects;

public class HelloValidator {

  Validator validator = new Validator.Builder()
          .rule("Enter a text other than null", Objects::nonNull)
          .rule("The text is different from 'xxx'", evaluate -> evaluate.equals("xxx"))
          .build();

}

The Builder pattern provides a cleaner, more readable syntax for chaining rules.

Using Predefined Rules

Validator comes with 27+ predefined rules for common validation scenarios. Let’s explore some of the most useful ones.

Email Validation

EmailValidator.java

import io.github.ApamateSoft.validator.Validator;

Validator emailValidator = new Validator.Builder()
        .required()
        .email()
        .maxLength(255)
        .build();

// Test it
emailValidator.isValid("user@example.com");  // true
emailValidator.isValid("invalid-email");     // false
emailValidator.isValid("");                  // false

Number Validation

AgeValidator.java

import io.github.ApamateSoft.validator.Validator;

Validator ageValidator = new Validator.Builder()
        .required()
        .onlyNumbers()
        .minValue(18)
        .maxValue(120)
        .build();

// Test it
ageValidator.isValid("25");   // true
ageValidator.isValid("17");   // false (too young)
ageValidator.isValid("abc");  // false (not a number)

Phone Number Pattern

PhoneValidator.java

import io.github.ApamateSoft.validator.Validator;

Validator phoneValidator = new Validator.Builder()
        .required()
        .numberPattern("(xxxx) xxx-xxxx")
        .build();

// Test it
phoneValidator.isValid("(1234) 567-8901");  // true
phoneValidator.isValid("123-456-7890");     // false (wrong format)

The x character in numberPattern is a placeholder for digits. Any other characters must match exactly.

Password Strength

PasswordValidator.java

import io.github.ApamateSoft.validator.Validator;
import static io.github.ApamateSoft.validator.utils.Alphabets.*;

Validator passwordValidator = new Validator.Builder()
        .required()
        .minLength(8)
        .mustContainMin(1, ALPHA_LOWERCASE)
        .mustContainMin(1, ALPHA_UPPERCASE)
        .mustContainMin(1, NUMBER)
        .mustContainMin(1, "@#$%^&*")
        .build();

// Test it
passwordValidator.isValid("Password123!");  // true
passwordValidator.isValid("password");      // false (no uppercase, no number)
passwordValidator.isValid("Pass1!");        // false (too short)

Handling Validation Errors

Validator provides two approaches for handling validation errors: event-based and exception-based.

Event-Based Error Handling

Use onInvalidEvaluation to register a callback that receives error messages:

import io.github.ApamateSoft.validator.Validator;

Validator validator = new Validator.Builder()
        .required()
        .email()
        .build();

// Register error handler
validator.onInvalidEvaluation(message -> {
    System.out.println("Validation failed: " + message);
});

// Validate
if (!validator.isValid("invalid-email")) {
    // Error handler was called with the message
}

Exception-Based Error Handling

Use validOrFail to throw an exception when validation fails:

import io.github.ApamateSoft.validator.Validator;
import io.github.ApamateSoft.validator.exceptions.InvalidEvaluationException;

Validator validator = new Validator.Builder()
        .required()
        .email()
        .build();

try {
    validator.validOrFail("email", "invalid-email");
    // Validation passed, continue processing
} catch (InvalidEvaluationException e) {
    System.out.println("Field: " + e.getKey());      // "email"
    System.out.println("Value: " + e.getValue());    // "invalid-email"
    System.out.println("Error: " + e.getMessage());  // "Email invalid"
}

Comparing Strings

For password confirmation or matching fields, use isMatch or compareOrFail:

import io.github.ApamateSoft.validator.Validator;

Validator passwordValidator = new Validator.Builder()
        .required()
        .minLength(8)
        .setNotMatchMessage("Passwords do not match")
        .build();

// Event-based
if (passwordValidator.isMatch("password123", "password123")) {
    System.out.println("Passwords match!");
}

// Exception-based
try {
    passwordValidator.compareOrFail("password", "password123", "password123");
    // Passwords match
} catch (InvalidEvaluationException e) {
    System.out.println("Error: " + e.getMessage());
}

Complete Example: User Registration

Here’s a complete example that validates a user registration form:

UserRegistration.java

import io.github.ApamateSoft.validator.Validator;
import io.github.ApamateSoft.validator.exceptions.InvalidEvaluationException;
import static io.github.ApamateSoft.validator.utils.Alphabets.*;

public class UserRegistration {

    // Define reusable validators
    private static final Validator emailValidator = new Validator.Builder()
            .required()
            .email()
            .maxLength(255)
            .build();

    private static final Validator usernameValidator = new Validator.Builder()
            .required()
            .minLength(3)
            .maxLength(20)
            .onlyAlphanumeric()
            .build();

    private static final Validator passwordValidator = new Validator.Builder()
            .required()
            .minLength(8)
            .mustContainMin(1, ALPHA_LOWERCASE)
            .mustContainMin(1, ALPHA_UPPERCASE)
            .mustContainMin(1, NUMBER)
            .mustContainMin(1, "@#$%^&*")
            .build();

    public static void registerUser(String email, String username, 
                                   String password, String confirmPassword) {
        try {
            // Validate each field
            emailValidator.validOrFail("email", email);
            usernameValidator.validOrFail("username", username);
            passwordValidator.validOrFail("password", password);
            passwordValidator.compareOrFail("password", password, confirmPassword);

            // All validations passed - proceed with registration
            System.out.println("Registration successful!");
            System.out.println("Email: " + email);
            System.out.println("Username: " + username);

        } catch (InvalidEvaluationException e) {
            // Handle validation error
            System.err.println("Validation failed for " + e.getKey() + ": " + e.getMessage());
        }
    }

    public static void main(String[] args) {
        // Test with valid data
        registerUser(
            "user@example.com",
            "johndoe",
            "SecurePass123!",
            "SecurePass123!"
        );

        System.out.println();

        // Test with invalid data
        registerUser(
            "invalid-email",
            "ab",
            "weak",
            "weak"
        );
    }

}

Output:

Registration successful!
Email: user@example.com
Username: johndoe

Validation failed for email: Email invalid

Next Steps

Now that you understand the basics, explore these topics:

Core Concepts

Learn about different validation approaches and patterns

Validation Rules

Explore all 27+ predefined validation rules

Annotations

Use annotations for declarative validation

Form Validation

Build complete form validation systems

Getting Started

Core Concepts

Guides

Your First Validator

Using Predefined Rules

Email Validation

Number Validation

Phone Number Pattern

Password Strength

Handling Validation Errors

Event-Based Error Handling

Exception-Based Error Handling

Comparing Strings

Complete Example: User Registration

Next Steps

Core Concepts

Validation Rules

Annotations

Form Validation

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Documentation Index

​Your First Validator

​Using Predefined Rules

​Email Validation

​Number Validation

​Phone Number Pattern

​Password Strength

​Handling Validation Errors

​Event-Based Error Handling

​Exception-Based Error Handling

​Comparing Strings

​Complete Example: User Registration

​Next Steps

Core Concepts

Validation Rules

Annotations

Form Validation

Build docs developers (and LLMs) love

Your First Validator

Using Predefined Rules

Email Validation

Number Validation

Phone Number Pattern

Password Strength

Handling Validation Errors

Event-Based Error Handling

Exception-Based Error Handling

Comparing Strings

Complete Example: User Registration

Next Steps