Java Encapsulation — Syntax, Types, Examples & Best Practices

// ❌ BAD: No encapsulation — public fields, no protection
class StudentBad {
    public String name;
    public int    age;
    public double gpa;
    public String email;
}

// Anywhere in code — invalid data enters silently:
// StudentBad s = new StudentBad();
// s.age   = -5;          // Invalid — accepted silently
// s.gpa   = 15.0;        // GPA > 10 — invalid but accepted
// s.email = "notanemail"; // No @ sign — invalid but accepted
// s.name  = null;        // Null name — causes NPE later, hard to trace

// ✅ GOOD: Full encapsulation — private fields, public controlled access
class Student {

    private String name;
    private int    age;
    private double gpa;
    private String email;

    // Constructor uses setters — validation runs at creation too
    public Student(String name, int age, double gpa, String email) {
        setName(name);
        setAge(age);
        setGpa(gpa);
        setEmail(email);
    }

    // ── Getters ───────────────────────────────────────────────────
    public String getName()  { return name; }
    public int    getAge()   { return age; }
    public double getGpa()   { return gpa; }
    public String getEmail() { return email; }

    // ── Setters with validation ───────────────────────────────────
    public void setName(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Name cannot be blank");
        this.name = name.trim();
    }

    public void setAge(int age) {
        if (age < 5 || age > 100)
            throw new IllegalArgumentException("Age must be between 5 and 100, got: " + age);
        this.age = age;
    }

    public void setGpa(double gpa) {
        if (gpa < 0.0 || gpa > 10.0)
            throw new IllegalArgumentException("GPA must be between 0.0 and 10.0");
        this.gpa = gpa;
    }

    public void setEmail(String email) {
        if (email == null || !email.contains("@") || !email.contains("."))
            throw new IllegalArgumentException("Invalid email: " + email);
        this.email = email.toLowerCase().trim();
    }

    @Override
    public String toString() {
        return "Student{name='" + name + "', age=" + age
             + ", gpa=" + gpa + ", email='" + email + "'}";
    }
}

class DataHidingDemo {
    public static void main(String[] args) {
        Student s = new Student("Anjali Verma", 20, 8.75, "anjali@example.com");
        System.out.println(s);

        s.setGpa(9.1);
        System.out.println("Updated GPA: " + s.getGpa());

        // s.setAge(-5); // ❌ Throws IllegalArgumentException — caught immediately
        // s.age = -5;   // ❌ Compile error — field is private
    }
}

import java.time.LocalDate;

public class Employee {

    private String    name;
    private String    employeeId;
    private double    salary;
    private String    department;
    private LocalDate joiningDate;
    private boolean   active;

    public Employee(String name, String employeeId, double salary,
                    String department, LocalDate joiningDate) {
        setName(name);
        this.employeeId  = employeeId;   // ID is set once — no setter
        setSalary(salary);
        setDepartment(department);
        this.joiningDate = joiningDate;
        this.active      = true;         // default value
    }

    // ── Standard Getters ──────────────────────────────────────────
    public String    getName()        { return name; }
    public String    getEmployeeId()  { return employeeId; }   // read-only — no setter
    public double    getSalary()      { return salary; }
    public String    getDepartment()  { return department; }
    public LocalDate getJoiningDate() { return joiningDate; }

    // Boolean getter uses 'is' prefix — NOT 'get'
    public boolean isActive() { return active; }

    // ── Standard Setters with validation ──────────────────────────
    public void setName(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Employee name cannot be blank");
        this.name = name.trim();
    }

    public void setSalary(double salary) {
        if (salary < 0)
            throw new IllegalArgumentException("Salary cannot be negative: " + salary);
        this.salary = salary;
    }

    public void setDepartment(String department) {
        if (department == null || department.isBlank())
            throw new IllegalArgumentException("Department cannot be blank");
        this.department = department.trim();
    }

    public void setActive(boolean active) { this.active = active; }

    // ── Derived / Computed Getter — no backing field ──────────────
    public int getYearsOfService() {
        return LocalDate.now().getYear() - joiningDate.getYear();
    }

    // ── Conditional setter — applies raise only if eligible ────────
    public void applyRaise(double percentage) {
        if (percentage <= 0 || percentage > 50)
            throw new IllegalArgumentException("Raise % must be between 0 and 50");
        this.salary = this.salary * (1 + percentage / 100);
    }

    // ── Masked getter — sensitive data partially hidden ────────────
    public String getMaskedId() {
        return "EMP-****" + employeeId.substring(employeeId.length() - 3);
    }

    @Override
    public String toString() {
        return "Employee{name='" + name + "', id='" + getMaskedId()
             + "', salary=" + salary + ", dept='" + department + "', active=" + active + "}";
    }
}

package com.techsustainify.bank;

public class BankAccount {

    // ── private: only this class ──────────────────────────────────
    private String accountNumber;
    private double balance;
    private String pin;             // never exposed outside — not even a getter

    // ── private static: shared but internal ───────────────────────
    private static final double MIN_BALANCE     = 500.0;
    private static final int    MAX_DAILY_LIMIT = 50000;

    // ── protected: accessible in subclasses ───────────────────────
    protected String holderName;
    protected String accountType;

    // ── public: part of the class's API ───────────────────────────
    public BankAccount(String accountNumber, String holderName,
                       String accountType, double initialDeposit, String pin) {
        this.accountNumber = accountNumber;
        this.holderName    = holderName;
        this.accountType   = accountType;
        this.balance       = initialDeposit;
        this.pin           = hashPin(pin);
    }

    // ── public API — what the outside world sees ──────────────────
    public double getBalance()       { return balance; }
    public String getAccountNumber() { return "XXXX" + accountNumber.substring(8); }
    public String getHolderName()    { return holderName; }

    public boolean deposit(double amount) {
        if (amount <= 0) return false;
        balance += amount;
        return true;
    }

    public boolean withdraw(double amount, String enteredPin) {
        if (!verifyPin(enteredPin))      return false;
        if (amount <= 0)                 return false;
        if (amount > MAX_DAILY_LIMIT)    return false;
        if (balance - amount < MIN_BALANCE) return false;
        balance -= amount;
        return true;
    }

    // ── private helpers — internal implementation, never exposed ──
    private String hashPin(String rawPin) {
        return Integer.toHexString(rawPin.hashCode()); // simplified
    }

    private boolean verifyPin(String enteredPin) {
        return hashPin(enteredPin).equals(this.pin);
    }
}

import java.util.regex.Pattern;

public class Product {

    private static final Pattern SKU_PATTERN =
        Pattern.compile("^[A-Z]{3}-\\d{4}-[A-Z0-9]{2}$"); // e.g. LAP-1024-AB

    private String sku;
    private String name;
    private double mrp;
    private double sellingPrice;
    private int    stockQuantity;
    private String category;

    public Product(String sku, String name, double mrp,
                   double sellingPrice, int stockQuantity, String category) {
        setSku(sku);
        setName(name);
        setMrp(mrp);
        setSellingPrice(sellingPrice);  // validates against MRP too
        setStockQuantity(stockQuantity);
        setCategory(category);
    }

    // ── Setters with domain-specific validation ───────────────────

    public void setSku(String sku) {
        if (sku == null || !SKU_PATTERN.matcher(sku).matches())
            throw new IllegalArgumentException(
                "Invalid SKU format. Expected: XXX-0000-XX, got: " + sku);
        this.sku = sku.toUpperCase();
    }

    public void setName(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Product name cannot be blank");
        if (name.length() > 100)
            throw new IllegalArgumentException("Product name too long (max 100 chars)");
        this.name = name.trim();
    }

    public void setMrp(double mrp) {
        if (mrp <= 0)
            throw new IllegalArgumentException("MRP must be positive, got: " + mrp);
        this.mrp = mrp;
        // If selling price already set, re-validate it
        if (this.sellingPrice > 0 && this.sellingPrice > mrp)
            throw new IllegalStateException("Selling price cannot exceed new MRP");
    }

    public void setSellingPrice(double sellingPrice) {
        if (sellingPrice <= 0)
            throw new IllegalArgumentException("Selling price must be positive");
        if (mrp > 0 && sellingPrice > mrp)
            throw new IllegalArgumentException(
                "Selling price (" + sellingPrice + ") cannot exceed MRP (" + mrp + ")");
        this.sellingPrice = sellingPrice;
    }

    public void setStockQuantity(int qty) {
        if (qty < 0)
            throw new IllegalArgumentException("Stock quantity cannot be negative");
        this.stockQuantity = qty;
    }

    public void setCategory(String category) {
        if (category == null || category.isBlank())
            throw new IllegalArgumentException("Category cannot be blank");
        this.category = category.trim();
    }

    // ── Getters ───────────────────────────────────────────────────
    public String getSku()           { return sku; }
    public String getName()          { return name; }
    public double getMrp()           { return mrp; }
    public double getSellingPrice()  { return sellingPrice; }
    public int    getStockQuantity() { return stockQuantity; }
    public String getCategory()      { return category; }

    // ── Derived getter ────────────────────────────────────────────
    public double getDiscountPercent() {
        return ((mrp - sellingPrice) / mrp) * 100;
    }

    public boolean isInStock() { return stockQuantity > 0; }

    @Override
    public String toString() {
        return String.format("Product{sku='%s', name='%s', mrp=%.2f, price=%.2f," +
               " discount=%.1f%%, stock=%d, category='%s'}",
               sku, name, mrp, sellingPrice, getDiscountPercent(), stockQuantity, category);
    }
}

import java.time.LocalDateTime;
import java.util.UUID;

public class Order {

    // ── Read-only fields — set once, never changed ────────────────
    private final String        orderId;      // auto-generated — no setter
    private final LocalDateTime createdAt;    // set at creation — no setter
    private final String        customerId;   // owner — no setter

    // ── Mutable fields — getter + setter ──────────────────────────
    private String deliveryAddress;
    private String status;

    // ── Write-only field — stored but never directly exposed ───────
    private String internalNotes;   // only set by support team, never returned

    public Order(String customerId, String deliveryAddress) {
        this.orderId         = UUID.randomUUID().toString();  // generated internally
        this.createdAt       = LocalDateTime.now();            // timestamped internally
        this.customerId      = customerId;
        this.deliveryAddress = deliveryAddress;
        this.status          = "PENDING";
    }

    // ── Read-only getters (no corresponding setters) ──────────────
    public String        getOrderId()    { return orderId; }
    public LocalDateTime getCreatedAt()  { return createdAt; }
    public String        getCustomerId() { return customerId; }

    // ── Normal getter + setter ────────────────────────────────────
    public String getDeliveryAddress() { return deliveryAddress; }
    public void setDeliveryAddress(String address) {
        if ("DELIVERED".equals(status))
            throw new IllegalStateException("Cannot change address after delivery");
        if (address == null || address.isBlank())
            throw new IllegalArgumentException("Address cannot be blank");
        this.deliveryAddress = address;
    }

    public String getStatus() { return status; }
    public void setStatus(String status) {
        // Validate state machine transitions
        if (!isValidTransition(this.status, status))
            throw new IllegalStateException(
                "Invalid status transition: " + this.status + " → " + status);
        this.status = status;
    }

    // ── Write-only setter — no getter for internalNotes ───────────
    public void setInternalNotes(String notes) {
        this.internalNotes = notes; // stored internally but never exposed
    }

    // internalNotes has NO getter — write-only field
    // External code can set it but never read it back

    private boolean isValidTransition(String from, String to) {
        return switch (from) {
            case "PENDING"    -> to.equals("CONFIRMED") || to.equals("CANCELLED");
            case "CONFIRMED"  -> to.equals("SHIPPED")   || to.equals("CANCELLED");
            case "SHIPPED"    -> to.equals("DELIVERED");
            default           -> false;
        };
    }
}

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Objects;

// ── Immutable Money class ─────────────────────────────────────────
public final class Money {   // 'final' — cannot be subclassed

    private final BigDecimal amount;   // 'final' — cannot be reassigned
    private final String     currency;

    // Constructor — only place state is set
    public Money(BigDecimal amount, String currency) {
        if (amount == null)
            throw new IllegalArgumentException("Amount cannot be null");
        if (currency == null || currency.isBlank())
            throw new IllegalArgumentException("Currency cannot be blank");
        if (amount.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Amount cannot be negative");
        this.amount   = amount.setScale(2, RoundingMode.HALF_UP);
        this.currency = currency.toUpperCase().trim();
    }

    // Convenience constructor
    public Money(double amount, String currency) {
        this(BigDecimal.valueOf(amount), currency);
    }

    // ── Getters only — NO setters ──────────────────────────────────
    public BigDecimal getAmount()   { return amount; }
    public String     getCurrency() { return currency; }

    // ── 'Modification' returns NEW instances — original unchanged ──
    public Money add(Money other) {
        assertSameCurrency(other);
        return new Money(this.amount.add(other.amount), this.currency);
    }

    public Money subtract(Money other) {
        assertSameCurrency(other);
        BigDecimal result = this.amount.subtract(other.amount);
        if (result.compareTo(BigDecimal.ZERO) < 0)
            throw new IllegalArgumentException("Result cannot be negative");
        return new Money(result, this.currency);
    }

    public Money multiply(double factor) {
        if (factor < 0) throw new IllegalArgumentException("Factor cannot be negative");
        return new Money(this.amount.multiply(BigDecimal.valueOf(factor)), this.currency);
    }

    public boolean isGreaterThan(Money other) {
        assertSameCurrency(other);
        return this.amount.compareTo(other.amount) > 0;
    }

    private void assertSameCurrency(Money other) {
        if (!this.currency.equals(other.currency))
            throw new IllegalArgumentException(
                "Currency mismatch: " + this.currency + " vs " + other.currency);
    }

    // ── equals, hashCode, toString — essential for value objects ──
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money m)) return false;
        return amount.compareTo(m.amount) == 0 && currency.equals(m.currency);
    }

    @Override
    public int hashCode() { return Objects.hash(amount, currency); }

    @Override
    public String toString() { return currency + " " + amount.toPlainString(); }
}

class MoneyDemo {
    public static void main(String[] args) {
        Money price    = new Money(999.00, "INR");
        Money discount = new Money(100.00, "INR");
        Money tax      = new Money(0.18 * 899.0, "INR");

        Money finalPrice = price.subtract(discount).add(tax);
        System.out.println("Final price: " + finalPrice); // INR 1061.18

        // 'price' is still unchanged — immutability guarantees this
        System.out.println("Original price unchanged: " + price); // INR 999.00
    }
}

import java.util.ArrayList;
import java.util.Collections;
import java.util.Date;
import java.util.List;

// ── BAD: No defensive copying — encapsulation broken ─────────────
class CourseRosterBad {
    private List<String> students;

    public CourseRosterBad(List<String> students) {
        this.students = students; // ❌ stores the SAME reference
    }

    public List<String> getStudents() {
        return students; // ❌ returns the SAME reference
    }
}

// Attack:
// List<String> list = new ArrayList<>(List.of("Ravi", "Priya"));
// CourseRosterBad roster = new CourseRosterBad(list);
// list.add("HACKER");   // ❌ modifies the roster's internal list!
// roster.getStudents().clear(); // ❌ wipes the roster from outside!

// ── GOOD: Defensive copying — encapsulation intact ───────────────
class CourseRoster {

    private final List<String> students;

    public CourseRoster(List<String> students) {
        if (students == null)
            throw new IllegalArgumentException("Students list cannot be null");
        // ✅ Defensive copy IN constructor — caller's list changes don't affect us
        this.students = new ArrayList<>(students);
    }

    public void addStudent(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Student name cannot be blank");
        students.add(name.trim());
    }

    public List<String> getStudents() {
        // ✅ Defensive copy OUT of getter — caller cannot modify our list
        return Collections.unmodifiableList(students);
        // OR: return new ArrayList<>(students);
    }

    public int size() { return students.size(); }
}

// ── Date fields — classic defensive copy need ─────────────────────
final class EventSchedule {

    private final String name;
    private final Date   eventDate;  // Date is mutable!

    public EventSchedule(String name, Date eventDate) {
        this.name      = name;
        this.eventDate = new Date(eventDate.getTime()); // ✅ defensive copy IN
    }

    public Date getEventDate() {
        return new Date(eventDate.getTime()); // ✅ defensive copy OUT
        // Caller modifying returned Date won't affect our field
    }

    // ✅ BETTER: Use java.time.LocalDate — it's immutable, no copying needed
    // private final LocalDate eventDate;
}

class DefensiveCopyDemo {
    public static void main(String[] args) {
        List<String> original = new ArrayList<>(List.of("Ravi", "Priya", "Anjali"));
        CourseRoster roster   = new CourseRoster(original);

        original.add("Attacker"); // modifying original — should NOT affect roster
        System.out.println(roster.getStudents()); // [Ravi, Priya, Anjali] — safe ✅

        roster.addStudent("Rahul");
        System.out.println(roster.getStudents()); // [Ravi, Priya, Anjali, Rahul]

        // roster.getStudents().add("External"); // ❌ UnsupportedOperationException
    }
}

// ── Traditional immutable class — ~50 lines of boilerplate ───────
public final class PointTraditional {
    private final int x;
    private final int y;
    public PointTraditional(int x, int y) { this.x = x; this.y = y; }
    public int x() { return x; }
    public int y() { return y; }
    @Override public boolean equals(Object o) {
        if (!(o instanceof PointTraditional p)) return false;
        return x == p.x && y == p.y;
    }
    @Override public int hashCode() { return java.util.Objects.hash(x, y); }
    @Override public String toString() { return "Point[x=" + x + ", y=" + y + "]"; }
}

// ── Java 16+ Record — same thing in 1 line ────────────────────────
record Point(int x, int y) {}
// Compiler auto-generates: private final fields, canonical constructor,
// public accessors x() and y(), equals(), hashCode(), toString()

// ── Record with custom validation (compact constructor) ────────────
record Product(String name, double price, int stock) {

    // Compact constructor — no parameter list, fields assigned automatically
    public Product {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Name cannot be blank");
        if (price <= 0)
            throw new IllegalArgumentException("Price must be positive");
        if (stock < 0)
            throw new IllegalArgumentException("Stock cannot be negative");
        name = name.trim(); // can reassign parameters before they become fields
    }

    // ── Custom methods can be added ────────────────────────────────
    public boolean isInStock()     { return stock > 0; }
    public String displayPrice()   { return "₹" + String.format("%.2f", price); }
}

// ── Record as DTO (Data Transfer Object) ─────────────────────────
record UserDto(String username, String email, String role) {}

record ApiResponse<T>(boolean success, String message, T data) {
    // Static factory methods on records
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(true, "Success", data);
    }
    public static <T> ApiResponse<T> error(String message) {
        return new ApiResponse<>(false, message, null);
    }
}

class RecordDemo {
    public static void main(String[] args) {

        Point p1 = new Point(3, 4);
        Point p2 = new Point(3, 4);
        System.out.println(p1);           // Point[x=3, y=4]
        System.out.println(p1.equals(p2)); // true — equals auto-generated
        System.out.println(p1.x());        // 3 — accessor (no 'get' prefix)

        Product laptop = new Product("Laptop", 75000.0, 15);
        System.out.println(laptop);           // Product[name=Laptop, price=75000.0, stock=15]
        System.out.println(laptop.isInStock()); // true
        System.out.println(laptop.displayPrice()); // ₹75000.00

        // new Product("", 100, 5); // ❌ throws IllegalArgumentException

        UserDto user = new UserDto("ravi_k", "ravi@example.com", "ADMIN");
        ApiResponse<UserDto> response = ApiResponse.ok(user);
        System.out.println(response.success()); // true
        System.out.println(response.data().username()); // ravi_k
    }
}

// ❌ MISTAKE 1: Public fields — no encapsulation at all
class PersonBad {
    public String name;   // ❌ anyone can set null, blank, or anything
    public int    age;    // ❌ anyone can set -5, -999, no validation
}

// ❌ MISTAKE 2: Bypassing validation in constructor (not calling setters)
class PersonMistake {
    private String name;
    private int    age;
    public PersonMistake(String name, int age) {
        this.name = name; // ❌ bypasses setName() validation — null accepted
        this.age  = age;  // ❌ bypasses setAge() validation — negative accepted
    }
    public void setName(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Name required");
        this.name = name;
    }
    public void setAge(int age) {
        if (age < 0) throw new IllegalArgumentException("Age cannot be negative");
        this.age = age;
    }
}
// Fix: call setName(name) and setAge(age) in the constructor

// ❌ MISTAKE 3: Returning mutable internal reference from getter
import java.util.List;
import java.util.ArrayList;
class CartBad {
    private List<String> items = new ArrayList<>();
    public List<String> getItems() { return items; } // ❌ exposes internal list
}
// CartBad cart = new CartBad();
// cart.getItems().clear(); // ❌ wipes internal list bypassing all logic!
// Fix: return Collections.unmodifiableList(items)

// ❌ MISTAKE 4: Storing mutable object reference without defensive copy
import java.util.Date;
class EventBad {
    private Date date;
    public EventBad(Date date) {
        this.date = date; // ❌ caller keeps reference — can mutate the date!
    }
}
// Date d = new Date();
// EventBad e = new EventBad(d);
// d.setTime(0); // ❌ modifies the internal date of 'e' from outside!
// Fix: this.date = new Date(date.getTime()); // defensive copy

// ❌ MISTAKE 5: Exposing internal array directly
class ConfigBad {
    private int[] values = {1, 2, 3, 4, 5};
    public int[] getValues() { return values; } // ❌ returns reference to internal array
}
// ConfigBad c = new ConfigBad();
// c.getValues()[0] = 999; // ❌ modifies internal array from outside!
// Fix: return Arrays.copyOf(values, values.length);

// ❌ MISTAKE 6: Setting boolean field name with 'get' instead of 'is'
class UserBad {
    private boolean active;
    public boolean getActive() { return active; } // ❌ wrong naming convention
}
// Fix: public boolean isActive() { return active; }
// Jackson, Hibernate, Spring all look for 'is' prefix for boolean fields

package com.techsustainify.user.domain;

import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.UUID;

public class UserAccount {

    // ── Read-only identity fields ─────────────────────────────────
    private final String        userId;
    private final LocalDateTime createdAt;

    // ── Mutable but controlled fields ─────────────────────────────
    private String  username;
    private String  email;
    private String  passwordHash;
    private String  role;
    private boolean active;
    private boolean emailVerified;
    private int     failedLoginAttempts;

    // ── Mutable collection — protected by defensive copy ──────────
    private final List<String> loginHistory;

    // ── Constants ─────────────────────────────────────────────────
    private static final int MAX_FAILED_ATTEMPTS = 5;

    public UserAccount(String username, String email, String passwordHash) {
        this.userId              = UUID.randomUUID().toString();
        this.createdAt           = LocalDateTime.now();
        this.loginHistory        = new ArrayList<>();
        this.active              = true;
        this.emailVerified       = false;
        this.failedLoginAttempts = 0;
        this.role                = "USER";
        setUsername(username);
        setEmail(email);
        this.passwordHash = passwordHash; // pre-hashed by service layer
    }

    // ── Business methods — logic lives WITH the data ──────────────

    public boolean recordLoginSuccess(String ipAddress) {
        if (!active) return false;
        this.failedLoginAttempts = 0;
        loginHistory.add(LocalDateTime.now() + " SUCCESS from " + ipAddress);
        return true;
    }

    public boolean recordLoginFailure(String ipAddress) {
        failedLoginAttempts++;
        loginHistory.add(LocalDateTime.now() + " FAILED from " + ipAddress);
        if (failedLoginAttempts >= MAX_FAILED_ATTEMPTS) {
            this.active = false;
            return false; // account locked
        }
        return true; // still active
    }

    public void changePassword(String oldHash, String newHash) {
        if (!this.passwordHash.equals(oldHash))
            throw new IllegalArgumentException("Current password is incorrect");
        if (newHash == null || newHash.length() < 8)
            throw new IllegalArgumentException("New password hash is too short");
        this.passwordHash = newHash;
    }

    public void verifyEmail() { this.emailVerified = true; }

    public void deactivate() { this.active = false; }

    public void reactivate() {
        this.active              = true;
        this.failedLoginAttempts = 0;
    }

    // ── Getters — controlled read access ──────────────────────────
    public String        getUserId()            { return userId; }
    public LocalDateTime getCreatedAt()         { return createdAt; }
    public String        getUsername()          { return username; }
    public String        getEmail()             { return email; }
    public String        getRole()              { return role; }
    public boolean       isActive()             { return active; }
    public boolean       isEmailVerified()      { return emailVerified; }
    public int           getFailedLoginAttempts() { return failedLoginAttempts; }

    // passwordHash is NEVER exposed via getter — write-only from outside

    // Defensive copy of mutable list
    public List<String> getLoginHistory() {
        return Collections.unmodifiableList(loginHistory);
    }

    // ── Setters with validation ───────────────────────────────────
    public void setUsername(String username) {
        if (username == null || username.isBlank())
            throw new IllegalArgumentException("Username cannot be blank");
        if (!username.matches("^[a-zA-Z0-9_]{3,30}$"))
            throw new IllegalArgumentException(
                "Username must be 3-30 alphanumeric characters or underscores");
        this.username = username.toLowerCase();
    }

    public void setEmail(String email) {
        if (email == null || !email.matches("^[^@]+@[^@]+\\.[^@]+$"))
            throw new IllegalArgumentException("Invalid email: " + email);
        this.email         = email.toLowerCase().trim();
        this.emailVerified = false; // reset verification on email change
    }

    public void setRole(String role) {
        if (!List.of("USER", "ADMIN", "MODERATOR").contains(role))
            throw new IllegalArgumentException("Invalid role: " + role);
        this.role = role;
    }
}

package com.techsustainify.inventory;

import java.time.LocalDate;
import java.util.Objects;

// ── Immutable value object using Record ───────────────────────────
record ItemCode(String value) {
    public ItemCode {
        if (value == null || !value.matches("^ITM-[0-9]{6}$"))
            throw new IllegalArgumentException(
                "ItemCode must match ITM-XXXXXX format, got: " + value);
        value = value.toUpperCase();
    }
}

// ── Mutable entity with full encapsulation ────────────────────────
public class InventoryItem {

    private final ItemCode   itemCode;     // value object — immutable
    private final LocalDate  addedDate;    // read-only after creation
    private       String     name;
    private       int        quantity;
    private       double     unitCost;
    private       double     sellingPrice;
    private       boolean    discontinued;

    public InventoryItem(String itemCode, String name, int quantity,
                         double unitCost, double sellingPrice) {
        this.itemCode     = new ItemCode(itemCode); // validates format
        this.addedDate    = LocalDate.now();
        this.discontinued = false;
        setName(name);
        setQuantity(quantity);
        setUnitCost(unitCost);
        setSellingPrice(sellingPrice);
    }

    // ── Business operations ───────────────────────────────────────
    public void restock(int additionalQty) {
        if (discontinued)
            throw new IllegalStateException("Cannot restock a discontinued item");
        if (additionalQty <= 0)
            throw new IllegalArgumentException("Restock quantity must be positive");
        this.quantity += additionalQty;
    }

    public boolean sell(int qty) {
        if (qty <= 0 || qty > quantity) return false;
        this.quantity -= qty;
        return true;
    }

    public void discontinue() { this.discontinued = true; }

    // ── Computed getters ──────────────────────────────────────────
    public double getTotalStockValue()  { return quantity * unitCost; }
    public double getProfitMargin()     { return sellingPrice - unitCost; }
    public double getProfitMarginPct()  { return (getProfitMargin() / unitCost) * 100; }

    // ── Getters ───────────────────────────────────────────────────
    public ItemCode  getItemCode()      { return itemCode; }
    public LocalDate getAddedDate()     { return addedDate; }
    public String    getName()          { return name; }
    public int       getQuantity()      { return quantity; }
    public double    getUnitCost()      { return unitCost; }
    public double    getSellingPrice()  { return sellingPrice; }
    public boolean   isDiscontinued()   { return discontinued; }

    // ── Setters with validation ───────────────────────────────────
    public void setName(String name) {
        if (name == null || name.isBlank())
            throw new IllegalArgumentException("Name cannot be blank");
        this.name = name.trim();
    }
    public void setQuantity(int qty) {
        if (qty < 0) throw new IllegalArgumentException("Quantity cannot be negative");
        this.quantity = qty;
    }
    public void setUnitCost(double cost) {
        if (cost <= 0) throw new IllegalArgumentException("Unit cost must be positive");
        this.unitCost = cost;
    }
    public void setSellingPrice(double price) {
        if (price <= 0) throw new IllegalArgumentException("Selling price must be positive");
        if (price < unitCost)
            throw new IllegalArgumentException(
                "Selling price cannot be below unit cost (would cause loss)");
        this.sellingPrice = price;
    }
}