DEV Community: AnkitDevCode

JPA Mapping with Hibernate- Many-to-Many Relationship

AnkitDevCode — Sat, 14 Mar 2026 11:56:20 +0000

In the previous section, we discussed the One-to-Many and Many-to-One Relationship Now, let’s look at the Many-to-many relationship

Introduction
The Relational Model Behind @ManyToMany
Unidirectional @ManyToMany — Simplest Form
Bidirectional @ManyToMany
equals() and hashCode() — The Critical Foundation
Intermediate Entity for Join Table With Extra Columns
Fetch Strategies & The N+1 Problem
Cascade Types — What to Use and When
Serialization — Avoiding Infinite Recursion
Performance Best Practices
Quick Reference — Best Practices vs Pitfalls
Conclusion

1. Introduction

A many-to-many (M:N) relationship is one of the most common yet most misunderstood associations in relational modeling. When mapped carelessly in JPA/Hibernate, it becomes a prime source of N+1 query problems, infinite JSON recursion, unnecessary eager loading, and subtle data-integrity bugs.

This article walks through every important aspect of @ManyToMany, from the simplest unidirectional form to a full intermediate-entity approach, and pairs every concept with the best practices that keep your application performant and maintainable.

2. The Relational Model Behind @ManyToMany

In a relational database, an M:N relationship is always implemented via a join table (also called a bridge or association table). For example, a Student ↔ Course relationship requires a student_course join table:

students           student_course         courses
──────────────     ─────────────────      ──────────────────
student_id (PK)    student_id  (FK) ─▶    course_id (PK)
name               course_id   (FK) ─▶    title
email              enrolled_at            credits
                   grade

If the join table carries extra columns (enrolled_at, grade), you must model it as a separate entity — a plain @JoinTable annotation cannot capture those columns.

3. Unidirectional @ManyToMany — Simplest Form

Use this when only one side needs to navigate to the other, and the join table has no extra columns.

3.1 Mapping

@Entity
public class Student {
    @Id @GeneratedValue
    private Long id;
    private String name;

    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();   // ← Set, never List
}

@Entity
public class Course {
    @Id @GeneratedValue
    private Long id;
    private String title;
    // No back-reference here → unidirectional
}

✅ Best Practice — Use Set, not List

Always use Set<> for @ManyToMany collections. Hibernate's handling of List<> in many-to-many associations can throw MultipleBagFetchException when fetching multiple bag collections in the same query, and may produce duplicate records.

4. Bidirectional @ManyToMany

Bidirectional mapping lets both sides navigate to each other. Exactly one side must be the owning side (holds @JoinTable); the other is the inverse side (uses mappedBy).

4.1 Mapping

@Entity
public class Student {                            // OWNING SIDE
    @ManyToMany
    @JoinTable(
        name = "student_course",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();
}

@Entity
public class Course {                            // INVERSE SIDE
    @ManyToMany(mappedBy = "courses")            // mappedBy is mandatory
    private Set<Student> students = new HashSet<>();
}

❌ Pitfall — Forgetting mappedBy

Without mappedBy on the inverse side, JPA creates two independent join tables and double-inserts every link row. Always declare mappedBy on exactly one side.

4.2 Keeping Both Sides in Sync

In a bidirectional relationship you must update both sides programmatically in your helper methods, because the in-memory state is independent of the database state until flush:

// Add a convenience method on the owning side
public void enroll(Course course) {
    this.courses.add(course);
    course.getStudents().add(this);   // keep inverse in sync
}

public void unenroll(Course course) {
    this.courses.remove(course);
    course.getStudents().remove(this);
}

5. equals() and hashCode() — The Critical Foundation

Hibernate uses equals() and hashCode() to determine whether two entity instances represent the same row, especially when adding/removing from Set collections and when merging detached entities. The default Object identity implementation breaks all of this.

5.1 Correct Implementation (Business Key or UUID)

@Entity
public class Course {
    @Id @GeneratedValue
    private Long id;

    @NaturalId                     // Hibernate annotation
    @Column(nullable = false, unique = true)
    private String courseCode;     // e.g. "CS-101" — stable business key

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Course)) return false;
        Course other = (Course) o;
        return Objects.equals(courseCode, other.courseCode);
    }

    @Override
    public int hashCode() {
        return Objects.hashCode(courseCode);  // must be stable across states
    }
}

❌ Pitfall — Using id for hashCode

Never base hashCode on @Id if entities can be in a Set before being persisted. A transient entity has id = null, so its hashCode changes on persist, which silently corrupts any Set or HashMap that contained it.

6. Intermediate Entity for Join Table With Extra Columns

When the join table needs to store data (enrollment date, grade, seat number, etc.), replace the @ManyToMany shortcut with an explicit intermediate entity. This is the most robust and recommended pattern in production systems.

6.1 Composite Key Class

@Embeddable
public class EnrollmentId implements Serializable {
    @Column(name = "student_id")
    private Long studentId;

    @Column(name = "course_id")
    private Long courseId;

    // equals() + hashCode() required for @Embeddable PKs
    @Override public boolean equals(Object o) { ... }
    @Override public int hashCode() { ... }
}

6.2 Enrollment (Intermediate) Entity

@Entity
@Table(name = "student_course")
public class Enrollment {

    @EmbeddedId
    private EnrollmentId id = new EnrollmentId();

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("studentId")
    private Student student;

    @ManyToOne(fetch = FetchType.LAZY)
    @MapsId("courseId")
    private Course course;

    @Column(nullable = false)
    private LocalDate enrolledAt;

    private BigDecimal grade;
}

6.3 Parent Entities

@Entity
public class Student {
    @OneToMany(mappedBy = "student", cascade = CascadeType.ALL, orphanRemoval = true)
    private Set<Enrollment> enrollments = new HashSet<>();

    public void enroll(Course course, LocalDate date) {
        Enrollment e = new Enrollment();
        e.setStudent(this);
        e.setCourse(course);
        e.setEnrolledAt(date);
        enrollments.add(e);
    }
}

@Entity
public class Course {
    @OneToMany(mappedBy = "course")   // no cascade from Course side
    private Set<Enrollment> enrollments = new HashSet<>();
}

✅ Best Practice — Cascade only from the aggregate root

Apply CascadeType.ALL + orphanRemoval only on the owning aggregate root side (Student). Do not cascade from Course — it is a separate aggregate and should not delete enrollments when a course is touched.

7. Fetch Strategies & The N+1 Problem

Fetch strategy is the single most impactful performance decision in any JPA application.

7.1 Always Use LAZY — Never EAGER

// ✅ Correct — LAZY is the safe default
@ManyToMany(fetch = FetchType.LAZY)
private Set<Course> courses = new HashSet<>();

// ❌ Wrong — loads ALL courses for ALL students every time a Student is loaded
@ManyToMany(fetch = FetchType.EAGER)
private Set<Course> courses;

7.2 Solving N+1 With JOIN FETCH

Even with LAZY loading, iterating a collection inside a loop produces one SQL query per iteration. Fix this with a JOIN FETCH JPQL query:

// N+1 — fires one extra query per student
List<Student> students = em.createQuery("SELECT s FROM Student s", Student.class)
                           .getResultList();
students.forEach(s -> s.getCourses().size()); // N hits

// ✅ Fixed — single JOIN query
List<Student> students = em.createQuery(
    "SELECT DISTINCT s FROM Student s JOIN FETCH s.courses",
    Student.class).getResultList();

7.3 Using @BatchSize as a Middle Ground

@ManyToMany(fetch = FetchType.LAZY)
@BatchSize(size = 25)   // loads 25 students' courses in one IN (...) query
private Set<Course> courses = new HashSet<>();

❌ Pitfall — MultipleBagFetchException

You cannot JOIN FETCH two List<> collections in the same JPQL query. Hibernate throws MultipleBagFetchException. Fix: change both to Set<>, or fetch one in JPQL and use @BatchSize for the second.

8. Cascade Types — What to Use and When

Cascade types control which JPA lifecycle operations (PERSIST, MERGE, REMOVE, etc.) are propagated from parent to child.

8.1 Recommended Cascade Matrix

Scenario	Cascade	orphanRemoval	Notes
Simple `@ManyToMany` (no extra cols)	`PERSIST, MERGE`	`false`	Do NOT use `REMOVE`
Intermediate entity (owned)	`ALL`	`true`	Only from aggregate root
Intermediate entity (shared)	`PERSIST, MERGE`	`false`	Shared = don't remove
`Course → Enrollment` (inverse)	(none)	`false`	Let `Student` own it

❌ Pitfall — CascadeType.REMOVE on @ManyToMany

Using CascadeType.REMOVE (or ALL) on a plain @ManyToMany will delete the related entities themselves — not just the join row. Removing one Student will delete all their Course records from the courses table, affecting every other enrolled student.

9. Serialization — Avoiding Infinite Recursion

Bidirectional relationships create circular object graphs. When Jackson (or any JSON library) tries to serialize a Student that contains Courses, which contain Students, which contain Courses... it throws a StackOverflowError.

9.1 Jackson Annotations

// On the owning side (Student)
@JsonManagedReference
private Set<Course> courses;

// On the inverse side (Course)
@JsonBackReference
private Set<Student> students;  // this side is NOT serialized

9.2 Better: Use DTOs (Recommended)

Never serialize JPA entities directly to your API layer. Use dedicated DTO/response classes:

// DTO — safe, no cycles, no Hibernate proxies
public record CourseDTO(Long id, String title, int credits) {
    public static CourseDTO from(Course c) {
        return new CourseDTO(c.getId(), c.getTitle(), c.getCredits());
    }
}

public record StudentDTO(Long id, String name, Set<CourseDTO> courses) {
    public static StudentDTO from(Student s) {
        return new StudentDTO(
            s.getId(), s.getName(),
            s.getCourses().stream().map(CourseDTO::from).collect(Collectors.toSet())
        );
    }
}

10. Performance Best Practices

10.1 Projections and DTO Queries

For read-heavy endpoints, skip entity loading entirely and query directly into DTOs:

@Query("SELECT new com.example.dto.StudentCourseDTO(s.name, c.title) " +
       "FROM Student s JOIN s.courses c WHERE s.id = :studentId")
List<StudentCourseDTO> findCoursesByStudent(@Param("studentId") Long id);

10.2 Pagination — Never Paginate With JOIN FETCH

// ❌ Wrong — Hibernate loads ALL rows into memory, then paginates
@Query("SELECT DISTINCT s FROM Student s JOIN FETCH s.courses")
Page<Student> findAll(Pageable pageable);   // issues HHH90003004 warning

// ✅ Correct — paginate the root entity, load collection separately
@Query(value = "SELECT s FROM Student s",
       countQuery = "SELECT COUNT(s) FROM Student s")
Page<Student> findAll(Pageable pageable);
// Then use @BatchSize or a second query to load courses

10.3 Use @Transactional on Service, Not Repository

Keep your transactions at the service layer where the full unit of work is clear. Opening a transaction in a repository method gives you no control over lazy loading in the service.

11. Quick Reference — Best Practices vs Pitfalls

✅ Best Practice	❌ Pitfall to Avoid
Use `@ManyToMany` with intermediate entity for extra columns	Using plain `@JoinTable` when join table has extra data
Set `fetch = FetchType.LAZY` on both sides	Using `FetchType.EAGER` (causes N+1 queries)
Define owning side clearly with `mappedBy` on inverse	Bidirectional mapping without `mappedBy`
Use `Set<>` instead of `List<>` to avoid duplicates	Using `List<>` and getting `MultipleBagFetchException`
Use `orphanRemoval` + `CascadeType.ALL` on parent side only	Cascading `ALL` on both sides (infinite loops / dual deletes)
Implement `equals()`/`hashCode()` based on business key	Using default `Object` identity for `equals`/`hashCode`
Use `@BatchSize` or `JOIN FETCH` to load related data	Loading collections in a loop (classic N+1 problem)
Use DTOs and projections for read-heavy queries	Serializing full entity graphs to JSON (`StackOverflow` risk)

12. Conclusion

Many-to-many associations are powerful but require deliberate design. The key takeaways are:

Use Set<> — always. List<> in M:N leads to bags, duplicates, and MultipleBagFetchException.
Prefer intermediate entity — as soon as the join table has any extra column, model it explicitly.
Keep fetch=LAZY everywhere — solve loading problems with JOIN FETCH or @BatchSize, not EAGER.
Define equals()/hashCode() on a stable business key — never rely on the database-generated id.
Cascade carefully — REMOVE and orphanRemoval belong only on aggregate-root-owned children.
Use DTOs at the API layer — never serialize entity graphs directly to JSON.
Measure first — use Hibernate's statistics or a query logger (P6Spy/datasource-proxy) to confirm you have no N+1 queries before shipping.

JPA Mapping with Hibernate- One-to-Many and Many-to-One Relationship

AnkitDevCode — Sat, 14 Mar 2026 11:14:02 +0000

In the previous section, we discussed the One-to-One Relationship Now, let’s look at the one-to-many and many-to-one relationships

What Are These Relationships?
Setting Up a Bidirectional Relationship
- The Parent (One Side)
- The Child (Many Side)
Unidirectional @OneToMany — Avoid It
Best Practices
- 1. Always Use Lazy Fetching
- 2. Use List Instead of Set
- 3. Keep Both Sides in Sync
- 4. Use orphanRemoval for Parent-Owned Children
- 5. Never Cascade on @ManyToOne
- 6. Override equals and hashCode
Common Pitfalls
- The N+1 Query Problem
- LazyInitializationException
- Out-of-Sync Bidirectional State
- CascadeType.REMOVE + orphanRemoval Redundancy
Cascade Types Reference
Quick Reference Table
Summary

1. What Are These Relationships?

In JPA, One-to-Many and Many-to-One are two sides of the same coin. A Department can have many Employee records, and each Employee belongs to one Department. In the database, the foreign key (department_id) lives on the employees table — making Employee the owning side.

Key Terminology

Term	Meaning
Owning side	The entity that holds the foreign key column in the database — always the `@ManyToOne` side
Inverse side	The entity with `mappedBy` — does not control the FK, just navigates the relationship
`mappedBy`	Used on the inverse (non-owning) side to point back to the owning field
`CascadeType`	Which operations (`PERSIST`, `MERGE`, `REMOVE`, etc.) propagate from parent to child
`orphanRemoval`	Automatically deletes a child row when it is removed from the parent collection
`FetchType.LAZY`	Child data is loaded on demand when accessed — default for collections
`FetchType.EAGER`	Child data is always loaded with the parent — default for single associations

Database Representation

departments            employees
────────────────       ──────────────────────
dept_id  (PK)    ◀─    employee_id  (PK)
name                   name
                       department_id  (FK)  ← FK lives here (owning side)

2. Setting Up a Bidirectional Relationship

The recommended approach is a bidirectional mapping, where both entities know about each other.

The Parent (One Side)

@Entity
public class Department {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
private List<Employee> employees = new ArrayList<>();

    // Always use helper methods to keep both sides in sync
    public void addEmployee(Employee emp) {
        employees.add(emp);
        emp.setDepartment(this);
    }

    public void removeEmployee(Employee emp) {
        employees.remove(emp);
        emp.setDepartment(null);
    }
}

The Child (Many Side)

@Entity
public class Employee {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @ManyToOne(fetch = FetchType.LAZY)   // Always override the default!
    @JoinColumn(name = "department_id")
    private Department department;
}

Why mappedBy?
It tells JPA that Department is the inverse side — it does not own the FK column. Without it, Hibernate creates a join table, which is almost never what you want.

3. Unidirectional @OneToMany — Avoid It

// Looks clean but generates extra SQL
@OneToMany
@JoinColumn(name = "department_id")  // no mappedBy
private List<Employee> employees;

Here, Department knows about Employee, but Employee does not reference Department. When Hibernate cannot write the FK during the child INSERT (because it doesn't own the column), it issues extra UPDATE statements afterward. This produces unnecessary SQL and hurts performance.

Problems with unidirectional @OneToMany:

Generates extra UPDATE queries on every insert
Poor performance at scale
May silently create join tables if @JoinColumn is omitted
Harder to maintain relationship consistency
Limited query capability from the child side

✅ Best Practice: Always use @ManyToOne as the owning side and @OneToMany(mappedBy = "...") as the inverse side for bidirectional relationships.

4. Best Practices

1. Always Use Lazy Fetching

@ManyToOne defaults to EAGER — a hidden performance trap that loads the parent every time you load a child, even when you don't need it. Always override it explicitly.

@ManyToOne(fetch = FetchType.LAZY)   // override the EAGER default
@JoinColumn(name = "department_id")
private Department department;

@OneToMany is lazy by default, which is correct — leave it as-is.

2. Use `List` Instead of `Set`

If a JPA entity’s equals() and hashCode() are based on an auto-generated identifier, developers often use a constant hashCode() until the ID is assigned.

However, this hurts Set performance because all elements end up in the same hash bucket. As a result, every add() or contains() operation requires scanning all elements, degrading performance from O(1) to O(n).

In a Set, duplicate elements are not allowed because it relies on equals() and hashCode() to determine uniqueness. However, in Jakarta Persistence entities, equality typically corresponds to the identity of the associated database record. Since every child entity has a unique primary key (or a unique business key), entities retrieved from the database will already be distinct.
Because of this, a Set rarely provides any real benefit for a bidirectional @OneToMany association. Hibernate will not return duplicate rows for the same entity when loading the collection, so the collection naturally contains unique elements.

From a performance perspective, List implementations such as ArrayList are usually faster and simpler.

3. Keep Both Sides in Sync

In a bidirectional relationship, JPA uses the owning side to write to the DB. If you only update the inverse side (Department.employees), the FK won't be persisted. Always use helper methods:

// ✅ Good — updates both sides
department.addEmployee(employee);

// ❌ Bad — only updates the inverse side, FK not persisted
department.getEmployees().add(employee);

4. Use `orphanRemoval` for Parent-Owned Children

When the parent fully owns the lifecycle of its children, enable orphanRemoval:

@OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
private Set<Employee> employees = new HashSet<>();

Removing a child from the collection now automatically deletes it from the database on the next flush — no need for an explicit em.remove() call.

5. Never Cascade on `@ManyToOne`

cascade = CascadeType.ALL belongs on the parent (@OneToMany) side. Adding it to @ManyToOne can cause catastrophic side effects — like deleting a Department when you delete one Employee.

// ❌ WRONG — could delete the entire department!
@ManyToOne(cascade = CascadeType.ALL)
private Department department;

// ✅ CORRECT — no cascade on the child side
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "department_id")
private Department department;

6. Override `equals` and `hashCode`

Use a natural business key (e.g., email for an employee), not the database ID. The ID is null before the entity is persisted, so ID-based equality breaks collections like HashSet.

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Employee)) return false;
    Employee other = (Employee) o;
    return email != null && email.equals(other.email);
}

@Override
public int hashCode() {
    return getClass().hashCode();  // stable across transient and persistent states
}

5. Common Pitfalls

The N+1 Query Problem

The most common JPA performance issue. Loading a list of departments, then accessing each one's employees, fires one query per department.

// ❌ Triggers 1 + N queries
List<Department> depts = repo.findAll();
depts.forEach(d -> d.getEmployees().size()); // N extra queries!

Fix 1 — JOIN FETCH in JPQL:

@Query("SELECT DISTINCT d FROM Department d LEFT JOIN FETCH d.employees")
List<Department> findAllWithEmployees();

Fix 2 — @EntityGraph (Spring Data):

@EntityGraph(attributePaths = {"employees"})
List<Department> findAll();

Fix 3 — @BatchSize (Hibernate):

@OneToMany(mappedBy = "department")
@BatchSize(size = 25)
private List<Employee> employees;

@BatchSize loads children in batches using an IN (...) clause rather than one query each — a low-friction option when you don't want to change your JPQL queries.

`LazyInitializationException`

Accessing a lazy collection outside of an active Hibernate session (e.g., after the transaction has closed) throws this exception.

// ❌ Fails if the session is already closed
department.getEmployees().size(); // LazyInitializationException!

Fix: Always access lazy relationships within a @Transactional context, or eagerly fetch what you need in the repository query.

// ✅ Safe — transaction is open for the duration of the method
@Transactional
public DepartmentDTO getDepartmentWithEmployees(Long id) {
    Department dept = repo.findById(id).orElseThrow();
    dept.getEmployees().size(); // safe here
    return DepartmentDTO.from(dept);
}

Out-of-Sync Bidirectional State

Setting the child's reference without updating the parent's collection (or vice versa) leaves the in-memory object graph inconsistent, even if the DB is correct after flush.

// ❌ Only sets one side — department.getEmployees() won't contain emp in memory
emp.setDepartment(department);

// ✅ Use the helper method to keep both sides consistent
department.addEmployee(emp);

`CascadeType.REMOVE` + `orphanRemoval` Redundancy

Both cause child deletion when the parent is removed. Using both together is redundant and signals a misunderstanding of their purpose.

CascadeType.REMOVE — deletes children when the parent entity is explicitly removed via em.remove().
orphanRemoval = true — deletes children when they are removed from the parent's collection or when the parent is deleted.

✅ Use orphanRemoval = true when the parent fully owns the child lifecycle — it covers the REMOVE case and also handles disassociation from the collection. You do not need both.

6. Cascade Types Reference

Cascade Type	Effect	Use When
`PERSIST`	When parent is saved for the first time, unsaved children are also saved	Always safe on parent side
`MERGE`	When parent is merged (updated), children are also merged	Almost always paired with `PERSIST`
`REMOVE`	When parent is deleted, all children are deleted	Only on owned children; use `orphanRemoval` instead
`REFRESH`	When parent is refreshed from DB, children are also refreshed	Rarely needed
`DETACH`	When parent is detached from context, children are also detached	Rarely needed
`ALL`	Shorthand for all of the above	Convenient but potentially dangerous — review carefully

7. Quick Reference Table

Attribute	Recommended Setting	Notes
`@OneToMany` fetch	`LAZY` (default)	Don't override unless necessary
`@ManyToOne` fetch	`LAZY` (explicit)	Default is `EAGER` — always override
`mappedBy`	On the `@OneToMany` side	Marks the inverse (non-owning) side
`cascade`	`CascadeType.ALL` on parent only	Never put cascade on `@ManyToOne`
`orphanRemoval`	`true` for fully owned children	Handles both removal and disassociation
Collection type	`Set<T>`	Safer than `List<T>` with multiple joins
N+1 prevention	`JOIN FETCH` or `@EntityGraph`	`@BatchSize` is a low-friction alternative
`equals`/`hashCode`	Based on business key	Never based on database ID
Unidirectional `@OneToMany`	Avoid	Extra `UPDATE` SQL, harder to maintain
Helper methods	Always define on parent	Keep both sides of bidirectional mapping in sync

8. Summary

The FK lives on the many side — that entity is the owning side.
Use mappedBy on @OneToMany to declare the inverse side and avoid a spurious join table.
Always set @ManyToOne(fetch = FetchType.LAZY) — the default EAGER is a performance trap.
Write bidirectional helper methods (addEmployee / removeEmployee) to keep both sides in sync.
Use Set<> over List<> to avoid Cartesian products when joining multiple collections.
Watch for the N+1 problem whenever you iterate over collections — fix with JOIN FETCH, @EntityGraph, or @BatchSize.
Never cascade from child to parent (@ManyToOne).
Prefer orphanRemoval = true over CascadeType.REMOVE — it handles more cases cleanly.
Base equals()/hashCode() on a stable business key, never on the auto-generated database ID.

Code

@Entity
@Getter
@Setter
public class Department {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<Employee> employees = new ArrayList<>();

    // Always use helper methods to keep both sides in sync
    public void addEmployee(Employee emp) {
        employees.add(emp);
        emp.setDepartment(this);
    }

    public void removeEmployee(Employee emp) {
        employees.remove(emp);
        emp.setDepartment(null);
    }
}

@Entity
@Getter
@Setter
public class Employee {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;

    private String email;

    public Employee(String name, String email) {
        this.name = name;
        this.email = email;
    }

    @ManyToOne(fetch = FetchType.LAZY)   // Always override the default!
    @JoinColumn(name = "department_id")
    private Department department;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Employee)) return false;
        Employee other = (Employee) o;
        return email != null && email.equals(other.email);
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

public interface DepartmentRepository extends JpaRepository<Department, Long> {
}

public interface EmployeeRepository extends JpaRepository<Employee, Long> {
}

@Component
public class DataLoader implements ApplicationRunner {

    private final DepartmentRepository departmentRepo;
    private final EmployeeRepository employeeRepo;

    public DataLoader(DepartmentRepository departmentRepo, EmployeeRepository employeeRepo) {
        this.departmentRepo = departmentRepo;
        this.employeeRepo = employeeRepo;
    }

    @Override
    @Transactional
    public void run(ApplicationArguments args) {

        /*
         * STEP 1: Create a Department entity
         * No DB query yet because the entity is only created in memory.
         */
        Department engineering = new Department();
        engineering.setName("Engineering");

        /*
         * STEP 2: Create Employee entities
         * These are also only in memory at this point.
         */
        Employee alice = new Employee("Alice", "alice@example.com");
        Employee bob   = new Employee("Bob",   "bob@example.com");

        /*
         * STEP 3: Link employees to department
         * The helper method usually:
         * 1. Adds employee to department.employees list
         * 2. Sets employee.department = this
         *
         * This ensures both sides of the bidirectional relationship stay consistent.
         */
        engineering.addEmployee(alice);
        engineering.addEmployee(bob);

        /*
         * STEP 4: Persist department
         *
         * Because the Department entity likely has:
         *
         * @OneToMany(mappedBy="department", cascade = CascadeType.ALL, orphanRemoval = true)
         *
         * Hibernate will cascade the persist operation to Employee entities.
         *
         * Expected SQL queries:
         *
         * INSERT INTO department (name)
         * INSERT INTO employee (name, email, department_id)
         * INSERT INTO employee (name, email, department_id)
         *
         * Total queries = 3
         */
        departmentRepo.save(engineering);

        /*
         * STEP 5: Read all departments
         *
         * Expected SQL:
         * SELECT * FROM department
         *
         * If employees collection is LAZY (recommended),
         * employees are NOT fetched until accessed.
         */
        departmentRepo.findAll().forEach(d ->
                System.out.println("Dept: " + d.getName())

        );

        /*
         * STEP 6: Find department by ID
         *
         * Expected SQL:
         * SELECT * FROM department WHERE id = ?
         */
        Optional<Department> dept = departmentRepo.findById(engineering.getId());
        dept.ifPresent(d -> System.out.println("Found: " + d.getName()));

        System.out.println("Department loaded");

      // employees should load only here
        dept.get().getEmployees().forEach(e ->
                System.out.println(e.getName()));


        /*
         * STEP 7: Update employee
         *
         * Changing Alice's name marks the entity as dirty.
         *
         * Expected SQL on flush/commit:
         * UPDATE employee SET name='Alice Smith' WHERE id=?
         */
        alice.setName("Alice Smith");
        employeeRepo.save(alice);

        /*
         * STEP 8: Remove employee from department
         *
         * Helper method typically:
         * 1. Removes Bob from department.employees list
         * 2. Sets bob.department = null
         *
         * Because orphanRemoval = true:
         * Hibernate will DELETE the employee record automatically.
         *
         * Expected SQL:
         * DELETE FROM employee WHERE id = ?
         */
        engineering.removeEmployee(bob);

        /*
         * Saving department ensures Hibernate detects the orphan removal.
         */
        departmentRepo.save(engineering);
    }
}

JPA Mapping with Hibernate-One-to-One Relationship

AnkitDevCode — Sat, 07 Mar 2026 12:46:24 +0000

What is JPA?
What is Hibernate?
JPA vs Hibernate — Key Differences
Relationship Mapping in JPA — Quick Reference
What is a One-to-One Relationship?
- Unidirectional vs Bidirectional
- How to Identify Owner, FK Side, and Child
- JPA Annotation Summary
Bidirectional One-to-One — Standard Mapping
- The Child Entity (Owning Side)
- The Parent Entity (Inverse Side)
The Lazy Loading Problem on the Inverse Side
- Why the Extra Query Fires
Solutions to the Inverse-Side Probe Query
- Option 1 — @LazyToOne Bytecode Instrumentation
- Option 2 — JOIN FETCH Query
- Option 3 — @NamedEntityGraph
- Option 4 — @MapsId Shared Primary Key (Best & Simplest)
Deep Dive — @MapsId
- Advantages of @MapsId
- Downsides of @MapsId
- When @MapsId Is Ideal
Comparison — @JoinColumn vs @MapsId
Quick Reference Table
Summary

1. What is JPA?

The Java Persistence API (JPA) is a Java specification that defines a standard way to manage relational data in Java applications using Object Relational Mapping (ORM).

It provides a set of interfaces and annotations that allow developers to map Java objects to database tables, perform CRUD operations, and manage persistence without writing large amounts of SQL.

Key points:

JPA is a specification, not an implementation
It standardizes how Java applications interact with relational databases
It uses annotations and configuration to map objects to tables
It simplifies database operations through entity management and persistence context

2. What is Hibernate?

Hibernate is a popular open-source ORM framework that provides a concrete implementation of the JPA specification.

It allows developers to interact with databases using Java objects instead of writing complex SQL queries, making application code loosely coupled with the underlying database.

Key points:

Hibernate is a JPA implementation
Provides powerful ORM capabilities beyond the JPA spec
Handles CRUD operations automatically
Supports caching, lazy loading, and transaction management
Reduces boilerplate JDBC code

3. JPA vs Hibernate — Key Differences

	JPA	Hibernate
Type	Specification (standard API)	Implementation of JPA
Who defines it	Jakarta EE / Oracle	Red Hat / JBoss
Can run standalone?	No — needs an implementation	Yes
Extra features	Standard only	Caching, `@BatchSize`, `@NaturalId`, etc.
Code coupling	Low — portable across providers	Higher — Hibernate-specific annotations

In practice:

Developers write code using JPA annotations and interfaces
Hibernate executes the actual database operations behind the scenes

4. Relationship Mapping in JPA — Quick Reference

Annotation	Relationship	FK Location
`@OneToOne`	One entity ↔ one entity	Child / owning side
`@OneToMany`	One entity → many entities	Child table
`@ManyToOne`	Many entities → one entity	Owning entity (FK here)
`@ManyToMany`	Many entities ↔ many entities	Join / junction table

Key best practices across all relationship types:

Always use FetchType.LAZY on relationships — avoids N+1 query problems
mappedBy goes on the non-owning side (the side without the FK column)
Cascade carefully — only cascade from parent to child, never upward
@JoinColumn explicitly names your FK column for clarity
Use Set instead of List for @ManyToMany to avoid duplicate join queries

5. What is a One-to-One Relationship?

A One-to-One relationship occurs when one entity is associated with exactly one instance of another entity.

Real-world examples:

Person → Passport
User → UserProfile
Order → Invoice

Unidirectional vs Bidirectional

Unidirectional — Only one entity has a reference to the other. Navigation works in one direction only.

User  →  UserProfile      (User knows about UserProfile; UserProfile does NOT know about User)

Bidirectional — Both entities have a reference to each other. Navigation works in both directions.

User  ⇆  UserProfile      (both sides can navigate to the other)

How to Identify Owner, FK Side, and Child

Ask yourself these three questions:

Question	Answer
Who cannot exist without the other?	That's the child → holds the FK
Who exists independently?	That's the parent → has `mappedBy`
Who makes sense to delete first?	That's the child → cascade from parent

Rule of thumb: Child = cannot exist without parent = has @JoinColumn (FK).
Parent = exists independently = has mappedBy (no FK).

JPA Annotation Summary

Annotation	Side	FK
`@JoinColumn`	Owning / Child	FK lives here
`mappedBy`	Inverse / Parent	No FK
`@JoinTable`	`@ManyToMany` owner	Junction table
`cascade`	Parent → Child	Delete parent = delete child

6. Bidirectional One-to-One — Standard Mapping

In a User ↔ UserProfile relationship, UserProfile is the child because the foreign key (user_id) lives in the user_profile table. User is the parent (inverse side).

users                  user_profile
─────────────          ──────────────────────
id  (PK)        ◀──    id  (PK)
username               phone
password               address
enabled                user_id  (FK) ← FK lives here

The Child Entity (Owning Side)

@JoinColumn is used on the owning side — the child entity contains the foreign key pointing to the parent's primary key.

@Entity
@Table(name = "user_profile")
public class UserProfile {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String phone;

    @Column(nullable = false)
    private String address;

    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", unique = true)   // FK column lives here
    private User user;
}

The Parent Entity (Inverse Side)

@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 50)
    private String username;

    @Column(nullable = false)
    private String password;

    @Column(nullable = false)
    private boolean enabled = true;

    @OneToOne(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private UserProfile profile;

    @ElementCollection(fetch = FetchType.EAGER)
    @CollectionTable(
        name = "user_roles",
        joinColumns = @JoinColumn(name = "user_id"),
        uniqueConstraints = @UniqueConstraint(columnNames = {"user_id", "role"})
    )
    @Enumerated(EnumType.STRING)
    @Column(name = "role", nullable = false)
    private Set<Role> roles = new HashSet<>();

    // Bidirectional sync helper — keeps both sides consistent
    public void setProfile(UserProfile profile) {
        this.profile = profile;
        if (profile != null) {
            profile.setUser(this);
        }
    }

    // Role helper methods
    public void addRole(Role role) {
        if (role != null) this.roles.add(role);
    }

    public void removeRole(Role role) {
        this.roles.remove(role);
    }

    public boolean hasRole(Role role) {
        return this.roles.contains(role);
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User user)) return false;
        return username != null && username.equals(user.getUsername());
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();
    }
}

Note on @ElementCollection: @ElementCollection stores simple values (like enum Role) in a separate table — it is not a full entity relationship, so there is no "other side" to sync.
Keeping FetchType.EAGER here is intentional when using Spring Security — UserDetails needs roles immediately on authentication.

7. The Lazy Loading Problem on the Inverse Side

Declaring fetch = FetchType.LAZY on the inverse side (mappedBy) of a @OneToOne does not actually make it lazy. Hibernate silently fires an extra query anyway.

Why the Extra Query Fires

On the owning side, the FK column is in the same row — Hibernate immediately knows if the association is null or not, and can safely create a proxy.

On the inverse side, there is no FK column. Hibernate must probe the database just to determine whether a UserProfile exists for a given User.

Query 1: SELECT * FROM users          ← your actual request
Query 2: SELECT * FROM user_profile   ← YOU DIDN'T ASK FOR THIS (Hibernate probe)
Query 3: SELECT * FROM user_roles     ← expected (EAGER @ElementCollection)

Query 2 is Hibernate asking: "does a profile exist for this user?" — because the inverse side has no FK column to check locally.

8. Solutions to the Inverse-Side Probe Query

Option 1 — @LazyToOne Bytecode Instrumentation

Forces truly lazy loading via Hibernate bytecode enhancement — Hibernate injects an interceptor into the bytecode so it never needs to probe the DB.

// User.java
@OneToOne(mappedBy = "user", fetch = FetchType.LAZY)
@LazyToOne(LazyToOneOption.NO_PROXY)   // forces true lazy via bytecode
private UserProfile profile;

Requires adding the Hibernate bytecode enhancer plugin to your build tool:

<!-- Maven -->
<plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <configuration>
        <enableLazyInitialization>true</enableLazyInitialization>
    </configuration>
</plugin>

Without Enhancement	With Enhancement
Hibernate probes DB to check if profile is null	Bytecode interceptor handles it — no probe needed
Extra query always fires	Truly lazy — query only fires on access

Option 2 — JOIN FETCH Query

Load both entities together in a single SQL query — profile is already in memory, no probe needed.

@Query("SELECT u FROM User u LEFT JOIN FETCH u.profile")
List<User> findAllWithProfile();

Hibernate generates:

SELECT
    u.id, u.enabled, u.password, u.username,
    p.id, p.address, p.phone
FROM users u
LEFT JOIN user_profile p ON u.id = p.user_id

Without JOIN FETCH	With JOIN FETCH
`SELECT FROM users` + `SELECT FROM user_profile` (2 queries)	`SELECT FROM users LEFT JOIN user_profile` (1 query)

Option 3 — @NamedEntityGraph

A @NamedEntityGraph defines a pre-declared fetch plan that can be reused across multiple repository methods, avoiding the need to write JOIN FETCH everywhere.

@NamedEntityGraph(
    name = "User.withDetails",
    attributeNodes = {
        @NamedAttributeNode("roles"),
        @NamedAttributeNode("profile")
    }
)
@Entity
@Table(name = "users")
public class User { ... }

Use it in the repository:

public interface UserRepository extends JpaRepository<User, Long> {

    @Query("SELECT u FROM User u LEFT JOIN FETCH u.profile")
    List<User> findAllWithProfile();

    @EntityGraph("User.withDetails")   // applies the named graph
    List<User> findAll();
}

Combining with @NamedSubgraph for nested associations:

When you need to fetch deeply nested associations (e.g., User → UserProfile → Address), use @NamedSubgraph:

@Entity
@NamedEntityGraph(
    name = "User.profile",
    attributeNodes = {
        @NamedAttributeNode(value = "profile", subgraph = "profile-subgraph")
    },
    subgraphs = {
        @NamedSubgraph(
            name = "profile-subgraph",
            attributeNodes = {
                @NamedAttributeNode("address")
            }
        )
    }
)
public class User { ... }

@Entity
public class UserProfile {
    @Id
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    private Address address;
}

@Repository
public interface UserRepository extends JpaRepository<User, Long> {

    @EntityGraph(value = "User.profile", type = EntityGraph.EntityGraphType.FETCH)
    Optional<User> findById(Long id);
}

With the entity graph, Hibernate generates a single query:

SELECT u.*, p.*, a.*
FROM users u
LEFT JOIN user_profile p ON p.user_id = u.id
LEFT JOIN address a       ON p.address_id = a.id
WHERE u.id = ?

When to use @EntityGraph:

You want dynamic fetch strategies per query
You want associations to be LAZY by default
You want to avoid scattering JOIN FETCH across all queries
Different repository methods need different fetch plans

Option 4 — @MapsId Shared Primary Key (Best & Simplest)

Since both entities share the same PK, Hibernate already knows the profile ID without probing. This is the cleanest solution for a strict @OneToOne relationship.

See Section 9 — Deep Dive: @MapsId for full details.

9. Deep Dive — @MapsId

The best way to map a @OneToOne relationship in Hibernate is using @MapsId, which allows the child entity to share the same primary key as the parent entity.

In this approach:

The child table uses the parent's PK as its own PK
This avoids creating an additional FK column
Hibernate already knows the child's ID — no probe query needed

users                  user_profile
─────────────          ──────────────────────
id  (PK)        ═══    id  (PK = FK) ← shared PK, no separate user_id column
username               phone
password               address

@Entity
@Table(name = "user_profile")
public class UserProfile {

    @Id                          // No @GeneratedValue — value is copied from User
    private Long id;

    @Column(nullable = false)
    private String phone;

    @Column(nullable = false)
    private String address;

    @OneToOne(fetch = FetchType.LAZY)
    @MapsId                      // this entity's PK = users.id
    @JoinColumn(name = "id")
    private User user;
}

The id column in user_profile serves as both PK and FK — its value is copied directly from User.id.

Key Differences Per Entity

	`User`	`UserProfile`
`@GeneratedValue`	✅ Yes — generates own PK	❌ No — copies from `User`
Owns the relationship	No — no `profile` field needed	Yes — has `@MapsId`
Probe query on fetch	Gone — no inverse field	—
Save strategy	`userRepository.save(user)`	`userProfileRepository.save(profile)`

Advantages of @MapsId

No extra FK column — cleaner schema, better normalization
No probe query — Hibernate already knows the child's ID
Efficient joins — PK = FK means the join is on the same column
No need for bidirectional association — User can be unidirectional
UserProfile can always be fetched directly using the User ID

Downsides of @MapsId

Tight coupling — UserProfile cannot exist without User (shares PK)
Insert order dependency — User must be persisted before UserProfile
Less flexibility — migrating from one-to-one → one-to-many requires schema redesign
Harder independent lifecycle management — deleting User invalidates UserProfile
Not suitable for optional relationships — if a User can exist without a UserProfile, this gets awkward
Harder for beginners — shared PK, @MapsId, and entity lifecycle can be confusing
Schema migration complexity — adding a separate PK to the child table later requires a full refactor

When @MapsId Is Ideal

Use @MapsId when:

The relationship is strictly one-to-one
The child cannot exist without the parent
The child is more like an extension of the parent (e.g., UserProfile is just extra columns for User)
You want zero extra queries and a cleaner schema

10. Comparison — @JoinColumn vs @MapsId

	`@JoinColumn` on child	`@MapsId`
Profile FK column	`user_profile.user_id`	`user_profile.id` = `users.id`
Hibernate knows child ID?	Must probe DB	Already has it
Extra query on `getUser()`?	Always fires (inverse side)	Only when accessed
DB schema	Extra `user_id` column	Shared PK — cleaner
Optional relationship?	✅ Yes	❌ Not ideal
Child exists independently?	✅ Can	❌ Cannot
Schema simplicity	Slightly more columns	Minimal columns

11. Quick Reference Table

Topic	Recommendation	Notes
Owning side	Entity holding the FK (`@JoinColumn`)	Always the child
Inverse side	Entity with `mappedBy`	No FK — navigation only
`@OneToOne` fetch (owning)	`FetchType.LAZY`	FK in same row — proxy safe
`@OneToOne` fetch (inverse)	`FetchType.LAZY` declared, but won't be	Hibernate probes regardless
Probe query fix	`@MapsId` or `JOIN FETCH`	`@MapsId` is cleanest for strict 1:1
N+1 prevention	`JOIN FETCH` or `@EntityGraph`	`@NamedSubgraph` for nested graphs
Cascade	`CascadeType.ALL` on parent only	Never cascade from child to parent
`orphanRemoval`	`true` for owned children	Handles disassociation too
`equals`/`hashCode`	Based on business key	Never based on database ID
Collection for roles	`Set<Role>`	Safer than `List` with multiple joins
Best overall mapping	`@MapsId` for strict 1:1	`@JoinColumn` for optional or flexible

12. Summary

In a @OneToOne relationship, the child holds the FK (@JoinColumn); the parent uses mappedBy.
Declaring FetchType.LAZY on the inverse side does not make it truly lazy — Hibernate fires a probe query anyway because there is no FK column to inspect locally.
Four ways to fix the probe query: bytecode instrumentation (@LazyToOne), JOIN FETCH, @NamedEntityGraph, or @MapsId.
@MapsId is the cleanest solution for strict one-to-one relationships — the child shares the parent's PK, eliminating the extra FK column and the probe query entirely.
Bidirectional = convenience (user.getProfile()) but costs a probe query. Unidirectional = no probe but you lose navigation from the User side.
For most applications — skip bytecode plugins, go unidirectional with @MapsId, and use JOIN FETCH when you need both entities at once.
Always use CascadeType.ALL on the parent side only — never cascade upward from child to parent.
Base equals()/hashCode() on a stable business key (e.g., username), never on the auto-generated database ID.

REST API Design: A Comprehensive Guide

AnkitDevCode — Sat, 07 Mar 2026 09:54:56 +0000

Understanding REST Fundamentals

REST works on top of the HTTP protocol, where each URI represents a resource. Because of this, endpoints should use nouns, not verbs. An RPC-style endpoint like /api/v1/getStudents becomes simply /api/v1/students in REST. The distinction between actions is handled by HTTP methods — GET, POST, PUT, PATCH, and DELETE — rather than the URL itself.

A REST endpoint is a unique URI that represents a resource. For example, https://demo.app/api/v1/students is a REST endpoint, where /api/v1/students is the path and students is the resource.

REST does not maintain server-side state — it only transfers state between server and client, which is the origin of the name REpresentational State Transfer. REST also leverages HTTP cache control, making responses cacheable because every representation is self-descriptive.

REST operates using three key components:

Resources and URIs — the nouns that identify what you're working with
HTTP methods — the verbs that define the action
HATEOAS — hypermedia links that guide clients dynamically

HTTP Methods

The five primary HTTP methods map to standard CRUD operations:

Method	Operation	Notes
`POST`	Create (or search)	Use for search when filter params exceed GET limits
`GET`	Read	Should be side-effect free
`PUT`	Full update / replace	Replaces the entire resource
`PATCH`	Partial update	Updates only the provided fields
`DELETE`	Delete	Should be idempotent

Some organisations also expose the HEAD method to retrieve only response headers without a body — useful for checking resource existence or metadata. For example:

curl --head https://api.github.com/users

Note: REST does not strictly mandate which method maps to which operation, but the conventions above are widely adopted across the industry.

POST

POST is normally used for create operations. There are two notable exceptions where POST is acceptable for reads:

Long filter criteria — GET query strings are limited to around 2,048 characters. When filter parameters exceed this, POST is a reasonable alternative.
Sensitive parameters — if input parameters contain private data, POST with HTTPS keeps them out of the URL and server logs.

A successful create operation should return 201 Created.

GET

GET is used for read operations. It should never modify server state. Successful responses return 200 OK when data is present, or 204 No Content when there is nothing to return.

PUT

PUT is used for full update or replace operations. It replaces the entire resource with the provided representation. Successful responses return 200 OK with data or 204 No Content without.

DELETE

DELETE removes a resource. For example, DELETE /licenses/agpl-3.0 deletes the resource identified by the agpl-3.0 key. A successful delete returns 204 No Content.

PATCH

PATCH is used for partial updates — only the supplied fields are changed. A successful response returns 200 OK. Unlike PUT, you do not need to send the full resource representation.

HTTP Status Codes

Status codes fall into five categories:

Range	Category
100–199	Informational
200–299	Success
300–399	Redirection
400–499	Client errors
500–599	Server errors

Commonly Used Codes

2xx — Success

200 OK — Request succeeded. Used for GET, PUT, and PATCH responses with a body.
201 Created — Resource was successfully created.
202 Accepted — Request received but processing is deferred (e.g., async or batch jobs).
204 No Content — Request succeeded with no response body.

3xx — Redirection

304 Not Modified — Resource hasn't changed; client should use its cached copy.

4xx — Client Errors

400 Bad Request — Missing, malformed, or invalid input parameters.
401 Unauthorized — Request is unauthenticated (despite the misleading name).
403 Forbidden — Authenticated but not authorised to perform the action.
404 Not Found — The requested resource does not exist.
405 Method Not Allowed — The HTTP method is not supported for this endpoint.
409 Conflict — Duplicate create or a state conflict (e.g., version mismatch).
429 Too Many Requests — Rate limit has been exceeded.

5xx — Server Errors

500 Internal Server Error — A generic, unexpected server-side failure.
502 Bad Gateway — An upstream dependency (e.g., a payment provider) returned an error.
503 Service Unavailable — The server is temporarily unable to handle requests (overload or maintenance).

HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) means that a REST API dynamically provides links to related actions and resources within its responses — rather than requiring clients to construct URLs themselves.

A client starts from a single known URL and discovers everything else through the hypermedia links in each response. This has two key benefits:

Clients don't need hardcoded knowledge of the API's URL structure.
When endpoint paths change, clients pick up the new URLs automatically through the links.

Best Practices

1. Use Nouns for Resource Names

HTTP methods already supply the verb. Adding a verb to the URL is redundant and produces RPC-style paths:

# Wrong (RPC style)
GET /getLicenses
POST /createUser

# Correct (REST style)
GET /licenses
POST /users

2. Use Plural Names for Collections

/licenses   ✓
/license    ✗

A GET /licenses call returns a collection. Plural naming makes the intent clear and consistent regardless of whether you're fetching one or many.

3. Version Your APIs

APIs evolve over time, and existing clients may depend on older behaviour. Always include a version identifier so you can introduce breaking changes without affecting existing integrations.

Option A — Version in the path (most common):

https://demo.app/api/v1/students

Clients always know exactly which version they're calling.

Option B — Version in the Accept header (GitHub's approach):

Accept: application/vnd.github.v3+json

Allows a default version when no header is present, but requires clients to update the header when upgrading.

Either approach works — the important thing is to pick one and apply it consistently from day one.

4. Model Nested Resources

When a resource belongs to another, reflect that in the URL hierarchy:

GET    /customers/1/addresses       # all addresses for customer 1
GET    /customers/1/addresses/2     # address 2 of customer 1
POST   /customers/1/addresses       # add a new address
PUT    /customers/1/addresses/2     # replace address 2
PATCH  /customers/1/addresses/2     # partially update address 2
DELETE /customers/1/addresses/2     # delete address 2

For resources that exist independently (e.g., payments in a microservices architecture), a top-level endpoint is often cleaner:

GET /payments/1    # instead of /orders/1/payments/1

HATEOAS helps here — the order response can include a payment link rather than the client needing to know the URL structure upfront.

5. Secure Your APIs

Always use HTTPS — never expose REST APIs over plain HTTP.
Use JWT or OAuth 2.0 tokens for authentication. REST is stateless, so cookies and server-side sessions are not appropriate.
Regularly review OWASP's API Security Top 10 for current threats and mitigations.
Validate all inputs on the server side regardless of client-side validation.

6. Implement Caching

HTTP provides two standard mechanisms for cache validation:

ETag — the server returns a hash of the response body in the ETag header. The client sends it back as If-None-Match on subsequent requests. If the resource hasn't changed, the server returns 304 Not Modified and saves the bandwidth of resending the body.

Last-Modified — the server returns the resource's last modification timestamp. The client sends it back as If-Modified-Since. The server returns 304 if nothing has changed since that timestamp. This is less precise than ETag and should be used as a fallback.

7. Enforce Rate Limiting

Use 429 Too Many Requests when a client exceeds its allowed request quota. Communicate rate limit status via response headers so clients can adapt:

Header	Meaning	Example
`X-Ratelimit-Limit`	Requests allowed per period	`60`
`X-Ratelimit-Remaining`	Requests left in current period	`55`
`X-Ratelimit-Used`	Requests used in current period	`5`
`X-Ratelimit-Reset`	Seconds until the period resets	`1601299930`

8. Support Filtering, Sorting, and Pagination

For endpoints that return collections, always support query parameters to avoid returning unbounded result sets:

GET /products?category=electronics&sort=price       # filter + sort
GET /users?page=1&size=20                           # pagination
GET /orders?status=pending&sort=created_at&page=2  # combined

9. Maintain Documentation

Good documentation is part of your API contract. It should:

Stay in sync with the current implementation, including version history.
Include code samples and example request/response pairs.
Clearly document deprecated endpoints and provide migration paths.
Be generated from the code where possible (e.g., OpenAPI/Swagger) to reduce drift.

10. Return Consistent Error Responses

Error responses should follow a predictable structure so clients can handle them programmatically:

{
  "status": 400,
  "error": "Bad Request",
  "message": "The 'email' field is required.",
  "path": "/api/v1/users"
}

Consistency here dramatically reduces the integration effort for API consumers.

Quick Reference

Concern	Recommendation
URL naming	Nouns, plural, lowercase, hyphen-separated
HTTP methods	Match semantics: `GET` reads, `POST` creates, `PUT` replaces, `PATCH` partially updates, `DELETE` removes
Status codes	Use the most specific code; avoid overusing `200` for everything
Versioning	Include from day one (`/api/v1/`)
Auth	JWT or OAuth 2.0 — no cookies or sessions
Caching	Use `ETag` or `Last-Modified` headers
Rate limiting	Return `429` with `X-Ratelimit-*` headers
Pagination	`?page=&size=` query params on collection endpoints
Documentation	OpenAPI/Swagger, kept current, with examples
Error format	Consistent JSON structure across all endpoints

Reference:

AI tools such as ChatGpt and Claude
Modern API Development with Spring and Spring Boot | Web Development | Paperback

Design highly scalable and maintainable APIs with REST, gRPC, GraphQL, and the reactive paradigm. 12 customer reviews. Top rated Web Development products.

packtpub.com

Java Virtual Threads — Quick Guide

AnkitDevCode — Sun, 01 Feb 2026 12:12:55 +0000

Java Virtual Threads — Quick Guide

Java 21+ · Spring Boot 3.2+ · Project Loom

A concise, production-focused guide to Java Virtual Threads — what they are, how to enable them, when to use them, and the real-world pitfalls that can silently hurt performance.

01 · What Are Virtual Threads

Before Project Loom, there is only one type of threads in Java, which is called platform thread in Project Loom. Platform threads are typically mapped 1:1 to kernel threads scheduled by the operating system. In Project Loom, virtual threads are introduced as a new type of threads.

Virtual threads are typically user-mode threads scheduled by the Java runtime rather than the operating system. Virtual threads are mapped M:N to kernel threads.

Platform and virtual threads are both represented using java.lang.Thread

Extremely lightweight compared to platform (OS) threads.
Millions of virtual threads can be created safely.
Allow developers to write simple, blocking-style code while remaining highly scalable.

How to create virtual threads?

The first approach to create virtual threads is using the Thread.ofVirtual method.

In the code below, a new virtual thread is created and started. The return value is an instance of java.lang.Thread object.

var thread = Thread.ofVirtual().name("My virtual thread")
    .start(() -> System.out.println("I'm running"))

The second approach is using Thread.startVirtualThread(Runnable task) method. This is the same as calling Thread.ofVirtual().start(task).

The third approach is using ThreadFactory.

var factory = Thread.ofVirtual().factory();
var thread = factory.newThread(() -> System.out.println("Create in factory"));

How to check if a thread is virtual?

The new isVirtual() method in java.lang.Thread returns true is this thread is a virtual thread.

Can virtual threads be non-daemon threads?

No. Virtual threads are always daemon threads. So they cannot prevent JVM from terminating. Calling setDaemon(false) on a virtual thread will throw an IllegalArgumentException exception.

Should virtual threads be pooled?

No. Virtual threads are light-weight. There is no need to pool them.

Can virtual threads support thread-local variables?

Yes. Virtual threads support both thread-local variables (ThreadLocal) and inheritable thread-local variables (InheritableThreadLocal).

Can virtual threads support thread-local variables?

Yes. Virtual threads support both thread-local variables (ThreadLocal) and inheritable thread-local variables (InheritableThreadLocal).

Can ExecutorService use virtual threads?

An ExecutorService can start a virtual thread for each task. This kind of ExecutorServices can be created using Executors.newVirtualThreadPerTaskExecutor() or Executors.newThreadPerTaskExecutor(ThreadFactory threadFactory) methods. The number of virtual threads created by the Executor is unbounded.

In the code below, a new ExecutorService is created to use virtual threads. 10000 tasks are submitted to this ExecutorService.

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
  IntStream.range(0, 10_00).forEach(i -> executor.submit(() -> {
    Thread.sleep(Duration.ofSeconds(1));
    return i;
  }));
}

Blocking comparison

OS Thread blocks

RestTemplate blocks an OS thread
Thread is idle during I/O
Under load → thread exhaustion

Virtual Thread blocks

JVM suspends the virtual thread
Carrier thread is released immediately
Scales safely under high concurrency

Why we need virtual threads?

Enable in Spring Boot

One property. No code changes.

# application.yml
server:
  servlet:
    threads:
      virtual-threads-enabled: true

Requirements

Java 21+ (final, not preview)
Spring Boot 3.2+

What changes

Each HTTP request runs on a fresh virtual thread
Controllers, services, RestTemplate → unchanged

What `virtual-threads-enabled: true` Actually Does in Spring

It replaces Tomcat’s entire servlet thread pool with a virtual-thread-per-request executor. Every incoming HTTP request is immediately assigned a new virtual thread. There is no fixed pool size — Tomcat doesn’t cap anything. The JVM manages it all.

This means your entire request lifecycle — from the moment the request hits the DispatcherServlet to the moment the response is written — runs on a virtual thread. Every blocking call inside that chain (RestTemplate, JDBC, Thread.sleep()) is automatically cheap because it’s already on a virtual thread.

The Manual Offload Approach

Tomcat’s default OS thread pool handles accept and dispatch, then the work is explicitly handed off to a virtual thread executor. For example, CompletableFuture.supplyAsync() offloads work to the virtual thread executor. The OS thread that accepted the request is released immediately.

Spring MVC knows how to handle a returned CompletableFuture:

It suspends servlet processing
It resumes when the future completes

The key point: Spring MVC does not block the servlet thread waiting for the future. It registers a callback internally and frees the thread immediately.

Service and Client Layers Remain Unchanged

The service and client layers stay completely unchanged in both approaches.

Virtual Threads Adoption Strategy in Spring Boot

Context

The existing Spring Boot microservice handles incoming HTTP requests using Spring MVC (Servlet stack) and communicates with multiple downstream services using blocking clients such as RestTemplate and JDBC.

Key constraints and characteristics:

The current implementation cannot be changed or rewritten.
The codebase contains:
- synchronized blocks and methods
- Heavy reliance on ThreadLocal (SecurityContext, MDC, request attributes)
The service performs I/O-heavy aggregation across multiple downstream services.
Scalability issues arise due to thread blocking under load.

The goal is to improve concurrency and scalability using Java Virtual Threads, without breaking existing behavior or introducing subtle runtime risks.

Two approaches are available in Spring Boot:

Property-based virtual threads (spring.threads.virtual.enabled=true)
Manual offloading to a virtual-thread executor using CompletableFuture

Option 1: Property-Based Virtual Threads (Global Enablement)

Description

Enabling:

(spring.threads.virtual.enabled=true)

replaces Tomcat's servlet thread pool with a virtual-thread-per-request executor.

Each HTTP request:

Is assigned a fresh virtual thread
Runs entirely on that virtual thread (filters → controllers → services → response)
Executes blocking calls cheaply (RestTemplate, JDBC, Thread.sleep)

Benefits

Zero code changes
Uniform behavior across the entire application
Automatic scalability for blocking I/O

Risks and Limitations

Pinning Risk

synchronized blocks pin carrier threads
Pinning is invisible and global
Concurrent access can exhaust the small carrier thread pool

[Virtual Thread]

↓

synchronized block  ← carrier pinned

↓

blocking I/O

If N concurrent requests enter pinned sections, N carrier threads are required. With only ~CPU-count carriers available, the application can stall.

ThreadLocal Assumptions Break

Virtual threads are short-lived
No thread reuse across requests
ThreadLocal data does not persist beyond a single request

This breaks assumptions made by existing code that was written for pooled OS threads.

ThreadLocal Abuse: If your project stores massive objects in ThreadLocal, you might run into memory issues because you could suddenly have 100,000 threads instead of 200.

Lack of Control

No isolation boundary
No way to selectively exclude endpoints or code paths
Fixing issues requires rewriting synchronized and ThreadLocal-dependent code

Option 2: Manual Offload to Virtual Threads (Selective Adoption)

Description

Tomcat continues to use its default OS-thread servlet pool
Existing code runs unchanged on OS threads
I/O-heavy logic is explicitly offloaded using:

CompletableFuture.supplyAsync(task, virtualThreadExecutor)

Spring MVC:

Natively supports CompletableFuture return types
Suspends request processing
Releases the servlet thread immediately
Resumes when the future completes

ThreadLocal Considerations

Offloading creates a hard thread boundary.

Context such as:

SecurityContext
MDC tracing data

is not propagated automatically and must be captured and restored manually.

This boundary is explicit and controlled.

Benefits

Preserves existing assumptions (synchronized, ThreadLocal)
Avoids carrier-thread pinning in legacy code
Allows targeted use of virtual threads only where beneficial
Enables incremental migration
Clear isolation between OS-thread and virtual-thread execution

Trade-offs

Slightly more boilerplate
Requires explicit context propagation
Virtual thread usage must be consciously applied

Consequences

Positive

Improved scalability for I/O-heavy endpoints
No need to refactor existing synchronized code
Predictable runtime behavior
Clear migration path

Negative

Additional boilerplate for context propagation
Requires discipline to maintain offload boundaries

Final Verdict

The property-based virtual thread approach is suitable only for codebases that are already virtual-thread-friendly.

For this system, manual offloading is the safest and most effective strategy, delivering the benefits of virtual threads while preserving correctness and operational stability.

Pitfalls (Read Before Production)

`synchronized` pins carrier threads

Problem

Virtual thread becomes glued to the carrier
9 concurrent requests + 8 carriers → deadlock

Fix: use ReentrantLock

// Pins carrier
public synchronized Product fetch(String id) {
    return restTemplate.getForObject("/p/{id}", Product.class, id);
}

// Safe
private final ReentrantLock lock = new ReentrantLock();

public Product fetch(String id) {
    lock.lock();
    try {
        return restTemplate.getForObject("/p/{id}", Product.class, id);
    } finally {
        lock.unlock();
    }
}

ThreadLocal context loss during manual offload

What breaks

MDC
SecurityContext
RequestAttributes

Fix: capture & restore context

Map<String, String> mdc = MDC.getCopyOfContextMap();
SecurityContext sec = SecurityContextHolder.getContext();

return CompletableFuture.supplyAsync(() -> {
    if (mdc != null) MDC.setContextMap(mdc);
    SecurityContextHolder.setContext(sec);
    try {
        return service.doWork();
    } finally {
        MDC.clear();
        SecurityContextHolder.clearContext();
    }
}, ioExecutor);

💡 This issue does not exist when using virtual-threads-enabled: true globally.

ThreadLocal leaks with pooled executors

Problem

Someone replaces the executor with a fixed pool
ThreadLocals leak across requests

Fix: enforce correct executor

@Bean
public Executor ioExecutor() {
    return Executors.newVirtualThreadPerTaskExecutor();
}

Native (JNI) calls pin silently

Examples

Some JDBC drivers
Crypto libraries

Contain the damage

private static final ExecutorService NATIVE_POOL =
    Executors.newFixedThreadPool(10);

public Future<Result> callNative(String input) {
    return NATIVE_POOL.submit(() -> nativeLib.process(input));
}

Enable pin logging (dev only):

-XX:+PrintVirtualThreadPinning

MVC + WebFlux together

If both starters are present, Spring chooses MVC
No warning is shown

Rule

Virtual Threads → keep spring-boot-starter-web
Remove starter-webflux

CPU-bound work on virtual threads

Anti-pattern

Heavy computation
Image processing
Crypto loops

Correct split

// I/O work
CompletableFuture.supplyAsync(
    () -> restTemplate.getForObject(...),
    Executors.newVirtualThreadPerTaskExecutor());

// CPU work
CompletableFuture.supplyAsync(
    () -> heavyComputation(data),
    ForkJoinPool.commonPool());

Final Takeaway

Virtual Threads are the best choice for blocking, I/O-heavy Spring Boot services you cannot rewrite.

They give you scalability, simplicity, and production safety — without reactive complexity.

Concurrency and Asynchronous Programming Part-1

AnkitDevCode — Fri, 30 Jan 2026 17:24:29 +0000

What is Parallel Programming?

Tasks run at the same time.
Progress happens simultaneously at any given instant.
Requires sufficient hardware resources (e.g., multiple CPU cores).

Example

Walking and talking:
- Both actions occur at the same time.
- At every moment, both are progressing.

What is Concurrent Programming?

Tasks make progress over time, but not at the same instant.
The system switches between tasks.
Over a time interval, all tasks move forward.

Example

Talking and drinking:
- You alternate between the two.
- At any moment, you’re doing one or the other, not both.

What “Asynchronous” Really Means?

Tasks don’t block while waiting for something (I/O, timers, network).

Key idea:

Asynchrony is about waiting efficiently.

A task starts work
It pauses when waiting
Resumes later via callbacks, promises

Common Misconception

Asynchronous ≠ no waiting
Tasks still wait for data.

The Real Question

Does the thread block while waiting?

Blocking threads = poor scalability.

Free threads = better resource utilization.

The twist: they’re not opposites

You can have:

Concurrent + synchronous (multiple threads blocking)
Single-threaded + asynchronous (Node.js style)
Concurrent + asynchronous (modern web servers)
Parallel (true simultaneous execution on multiple cores)

Parallelism = literally running at the same time

Concurrency = dealing with multiple things

Asynchrony = not blocking while waiting

Real-world analogy

Concurrency: A chef cooking 3 dishes at once

Asynchronous: Putting something in the oven and doing other prep instead of staring at it

Parallel: Multiple chefs cooking at the same time

Why threads are expensive?

Threads are considered expensive because each thread consumes significant system resources, even when it’s idle.

Main reasons:

Memory usage (stack space)
- Each thread has its own stack
- Typical stack size:
  - ~1 MB per thread (common default on 64-bit systems)
  - Can range from 256 KB to several MB, depending on OS and JVM/runtime configuration
- 1,000 threads ≈ ~1 GB of memory just for stacks
Context switching overhead
- The CPU must save and restore thread state when switching
- Frequent context switches reduce CPU efficiency
- Becomes costly at high thread counts
Scheduling overhead
- The OS scheduler must manage runnable threads
- Large numbers of threads increase scheduling complexity and latency
Synchronization costs
- Threads often require locks, mutexes, or other coordination mechanisms
- Leads to contention, deadlocks, and performance bottlenecks

Why Blocking Threads Hurt Scalability

When threads block on I/O:

They sit idle.
More threads are created to compensate.
Threads are limited by:
- CPU cores.
- Memory.

This leads to:

More machines.
More architectural complexity.
Higher costs (and environmental impact).

Evolution of Java Multithreading

Java 5 – `ExecutorService`

Introduced thread pools.
Solved:
- Uncontrolled thread creation.
New problem:
- Thread-pool–induced deadlocks.

Java 7 – Fork/Join Framework

Introduced work stealing.
Reduced pool starvation issues.
Well-suited for CPU-bound parallelism.

Java 8 – Expressive Concurrency

Introduced:

Parallel Streams
CompletableFuture

Enabled:

More declarative parallelism.
Better asynchronous composition.

Java 20 / 21 – Virtual Threads

Another major step forward.
Makes blocking cheap and scalable.
Simplifies concurrency for many workloads.

What Are Virtual Threads?

Virtual threads are a lightweight threading model introduced with Project Loom in Java.
They are managed by the JVM, not the operating system.
Designed to support massive concurrency with minimal resource usage.

Key Characteristics

Extremely lightweight compared to platform (OS) threads.
Millions of virtual threads can be created safely.
Allow developers to write simple, blocking-style code while remaining highly scalable.

The Problem Virtual Threads Aim to Solve

Traditional Java Concurrency Issues

Thread-per-request model:
- Threads block during I/O (DB, network, file).
- Blocking threads consume memory and OS resources.
- Scalability is limited by thread count.
To scale:
- More threads → more memory.
- More machines → higher cost and complexity.

Rise of Reactive Programming

Reactive frameworks (Reactor, RxJava) emerged to:
- Avoid blocking OS threads.
- Handle high concurrency using non-blocking I/O.
Downsides:
- Complex APIs.
- Harder to read, debug, and reason about.

How Virtual Threads Work?

Virtual threads are scheduled by the JVM, not the OS.
When a virtual thread blocks on I/O:
- It is unmounted from its carrier (platform) thread.
- The carrier thread is reused for other work.
- The virtual thread is remounted once I/O completes.
Result:
- Blocking no longer wastes threads.
- High scalability with familiar programming models.

Virtual Threads vs Reactive Programming

Shared Goal

Both aim to:

Maximize concurrency.
Avoid wasting threads during I/O.
Improve scalability of server-side applications.

Key Differences

Virtual Threads	Reactive Programming
Blocking code is acceptable	Requires non-blocking code
Simple, imperative style	Functional, stream-based style
Easier to read and debug	Steeper learning curve
Works with existing APIs	Requires reactive-compatible APIs

Core Argument

Virtual threads make thread-per-task scalable again.
This reduces the need for reactive frameworks in many common cases.

Benefits of Virtual Threads

Simplicity

Write synchronous, blocking code.
No need to manage callbacks or reactive pipelines.

Scalability

Blocking no longer ties up OS threads.
Supports very high concurrency with low overhead.

Compatibility

Works with existing Java libraries and APIs.
No need to rewrite large codebases.

Does Virtual Threads Kill Reactive Programming?

Short Answer: No — But It Shrinks Its Use Cases

Reactive programming still matters when:

Fine-grained event streams are required.
Backpressure control is critical.
Complex data-flow transformations are needed.

Virtual threads:

Do not automatically provide:
- Backpressure.
- Stream composition.
- Reactive operators.

Takeaways

Why Reactive Programming Existed

To avoid blocking OS threads and improve scalability.

What Changed

Virtual threads make blocking cheap and scalable.
Structured concurrency brings better control and safety.

Practical Impact

Many server-side workloads can return to:
- Simple, imperative code.
- Thread-per-request style.
Reactive programming remains relevant for specialized scenarios, but is no longer mandatory for scalability.

Advanced Java Data Structures and Their Best Use Cases

AnkitDevCode — Thu, 11 Sep 2025 17:06:48 +0000

Introduction

While Java’s standard collections like List, Set, and Map cover most needs, complex applications often require advanced data structures for efficiency, concurrency, and memory optimization.

This guide explores key advanced Java data structures, their core operations, complexities, and best use cases to help developers build high-performance, scalable applications.

1. PriorityQueue (Heap)

PriorityQueue in Java (from java.util) is a queue that arranges elements according to their priority.

PriorityQueue in Java is a min-heap by default, implemented as a binary heap using an array. It maintains elements in a partially ordered tree where the smallest element is always at the root.

A heap is a specialized binary tree-based data structure that satisfies the heap property:

In a Min-Heap, the parent node is always smaller (or equal) than its children.
In a Max-Heap, the parent node is always larger (or equal) than its children.

Heaps are typically implemented using arrays (not linked nodes) because the tree is always a complete binary tree (all levels filled except possibly the last, which is filled left to right).

Key Properties

Time Complexity: O(log n) for insertion and deletion, O(1) for peek
Space Complexity: O(n)
Not thread-safe
Unbounded (grows dynamically)
Natural ordering or custom Comparator

Basic Syntax for PriorityQueue

PriorityQueue<Integer> minHeap = new PriorityQueue<>();
PriorityQueue<Integer> maxHeap = new PriorityQueue<>(Collections.reverseOrder());

Core Operations

Operation	Description	Time Complexity
`add(e)`	Inserts element `e` into the queue.	O(log n)
`offer(e)`	Inserts element `e` into the queue.	O(log n)
`poll()`	Removes and returns the top (priority) element.	O(log n)
`peek()`	Returns the top element without removing it.	O(1)
`remove()`	Removes a specified element from the queue.	O(n)
`size()`	Returns the number of elements in the queue.	O(1)
`clear()`	Removes all elements from the queue.	O(n)
`contains(e)`	Checks if the queue contains element `e`.	O(n)

Classic Use Cases & Problems

K Largest/Smallest Elements
Merge K Sorted Lists
Dijkstra's Shortest Path
Task Scheduler with Priority
Top K Frequent Elements
Sliding Window Maximum
Meeting Rooms II (Minimum Conference Rooms)
Kth Largest Element in Stream
Memory Management

Example

1. PriorityQueue to implement Heap Sort

import java.util.PriorityQueue;
import java.util.Arrays;

public class HeapSortExample {
    public static void main(String[] args) {
        int[] nums = {20, 5, 15, 10};

        // Min-Heap for ascending order
        PriorityQueue<Integer> pq = new PriorityQueue<>();

        // Add all elements to the heap
        for (int num : nums) {
            pq.add(num);
        }

        // Extract elements to get sorted order
        int index = 0;
        while (!pq.isEmpty()) {
            nums[index++] = pq.poll();
        }

        System.out.println("Sorted array: " + Arrays.toString(nums)); // [5, 10, 15, 20]
    }
}

Add all elements to a Min-Heap (PriorityQueue by default).
Poll elements one by one → smallest element comes first.
Store them back → array becomes sorted in ascending order.
For descending order, use a Max-Heap: PriorityQueue<Integer> pq = new PriorityQueue<>(Collections.reverseOrder());

2. PriorityQueue with Objects

import java.util.PriorityQueue;
import java.util.Comparator;

class Student {
    String name;
    int score;

    Student(String name, int score) {
        this.name = name;
        this.score = score;
    }

    @Override
    public String toString() {
        return name + " (" + score + ")";
    }
}

public class Main {
    public static void main(String[] args) {
        // Max-Heap: higher score = higher priority
        PriorityQueue<Student> pq = new PriorityQueue<>(Comparator.comparingInt((Student s) -> s.score).reversed());

        pq.add(new Student("Alice", 85));
        pq.add(new Student("Bob", 92));
        pq.add(new Student("Charlie", 78));

        System.out.println("Students served by priority:");
        while (!pq.isEmpty()) {
            System.out.println(pq.poll());
        }
    }
}

Rule of Thumb:

Use Comparable for natural/default sorting.
Use Comparator for custom/multiple sorting logic.

// Comparable
class Student implements Comparable<Student> {
    int score;
    public int compareTo(Student s) { return this.score - s.score; }
}

// Comparator
Comparator<Student> byScoreDesc = (a, b) -> b.score - a.score;

Summary

PriorityQueue is the go-to choice when you need efficient access to the minimum/maximum element with frequent insertions and deletions, making it perfect for algorithms that require greedy selection based on priority.

2. Deque (ArrayDeque/LinkedDeque)

Deque (pronounced "deck" is part of the java.util package ) is a double-ended queue that allows insertion and deletion at both ends. Java provides two main implementations:

ArrayDeque: Resizable array implementation
LinkedList: Doubly-linked list implementation (also implements Deque)

Key Properties

Double-ended operations - Insert/remove from both front and rear
No capacity restrictions - Dynamically resizable
Not thread-safe - Requires external synchronization
Null elements not allowed (ArrayDeque) vs Null allowed (LinkedList)
Faster than Stack and LinkedList for stack/queue operations
More memory efficient than LinkedList (ArrayDeque)
Implements both Queue and Deque interfaces
Supports both LIFO and FIFO operations

Basic Syntax for ArrayDeque and LinkedList

import java.util.Deque;
import java.util.ArrayDeque;
import java.util.LinkedList;

public class Main {
    public static void main(String[] args) {
        // Using ArrayDeque
        Deque<Integer> arrayDeque = new ArrayDeque<>();
        arrayDeque.addFirst(10);
        arrayDeque.addLast(20);
        System.out.println("ArrayDeque peekFirst: " + arrayDeque.peekFirst()); // 10
        System.out.println("ArrayDeque peekLast: " + arrayDeque.peekLast());   // 20
        arrayDeque.removeFirst();
        arrayDeque.removeLast();

        // Using LinkedList
        Deque<Integer> linkedListDeque = new LinkedList<>();
        linkedListDeque.addFirst(30);
        linkedListDeque.addLast(40);
        System.out.println("LinkedList peekFirst: " + linkedListDeque.peekFirst()); // 30
        System.out.println("LinkedList peekLast: " + linkedListDeque.peekLast());   // 40
        linkedListDeque.removeFirst();
        linkedListDeque.removeLast();
    }
}

Core Operations

Operation	ArrayDeque	LinkedList	Description
addFirst(e)	O(1) amortized	O(1)	Insert at front
addLast(e)	O(1) amortized	O(1)	Insert at rear
removeFirst()	O(1)	O(1)	Remove from front
removeLast()	O(1)	O(1)	Remove from rear
peekFirst()	O(1)	O(1)	Get first without removing
peekLast()	O(1)	O(1)	Get last without removing
pollFirst()	O(1)	O(1)	Remove first (null if empty)
pollLast()	O(1)	O(1)	Remove last (null if empty)
size()	O(1)	O(1)	Get number of elements
isEmpty()	O(1)	O(1)	Check if empty
contains(o)	O(n)	O(n)	Search for element
remove(o)	O(n)	O(n)	Remove specific element
clear()	O(1)	O(1)	Remove all elements

ArrayDeque vs LinkedList Performance

Aspect	ArrayDeque	LinkedList
Memory	Lower overhead	Higher overhead (node pointers)
Cache Performance	Better (array locality)	Worse (scattered nodes)
Add/Remove Ends	Faster	Slightly slower
Random Access	Not supported	Not efficient
Iterator	Faster	Slower
Memory Allocation	Bulk allocation	Per-element allocation

Classic Use Cases & Problems

Sliding Window Maximum/Minimum - Maintain elements in window
Palindrome Checking - Compare characters from both ends
Undo/Redo Functionality - Stack-like operations with flexibility
BFS with Level Tracking - Process nodes level by level
Expression Evaluation - Handle nested brackets and operators
Implementing Stack and Queue - Single data structure for both
Monotonic Deque Problems - Maintain increasing/decreasing order
Circular Buffer Implementation - Ring buffer with dynamic size
Browser History Navigation - Forward/backward navigation
Task Scheduling - Priority-based insertion at both ends

Example

sliding-window-maximum

import java.util.*;

public class SlidingWindowMaximum {
    public int[] maxSlidingWindow(int[] nums, int k) {
        if (nums == null || nums.length == 0 || k <= 0) {
            return new int[0];
        }

        Deque<Integer> deque = new ArrayDeque<>(); // Stores indices
        int[] result = new int[nums.length - k + 1];
        int resultIndex = 0;

        for (int i = 0; i < nums.length; i++) {
            // Remove indices that are out of current window
            while (!deque.isEmpty() && deque.peekFirst() < i - k + 1) {
                deque.pollFirst();
            }

            // Remove indices whose corresponding values are smaller than current
            while (!deque.isEmpty() && nums[deque.peekLast()] < nums[i]) {
                deque.pollLast();
            }

            // Add current index
            deque.offerLast(i);

            // If we have processed at least k elements, add to result
            if (i >= k - 1) {
                result[resultIndex++] = nums[deque.peekFirst()];
            }
        }

        return result;
    }

    public static void main(String[] args) {
        SlidingWindowMaximum solution = new SlidingWindowMaximum();
        int[] nums = {1, 3, -1, -3, 5, 3, 6, 7};
        int k = 3;

        int[] result = solution.maxSlidingWindow(nums, k);
        System.out.println("Sliding Window Maximum: " + Arrays.toString(result));
        // Output: [3, 3, 5, 5, 6, 7]
    }
}

Summary

Use ArrayDeque for better performance and LinkedList when frequent insertions/removals in the middle are needed.

3. BlockingQueue (ArrayBlockingQueue, LinkedBlockingQueue)

BlockingQueue is a thread-safe queue interface that supports operations that wait for the queue to become non-empty when retrieving an element, and wait for space to become available when storing an element. It's part of the java.util.concurrent package.

Key Properties

Thread-safe - Built-in synchronization for concurrent access
Blocking operations - Threads wait when queue is full/empty
Producer-Consumer pattern - Perfect for multi-threaded scenarios
No null elements - Null values are not permitted
Capacity management - Can be bounded or unbounded
Multiple implementations - ArrayBlockingQueue, LinkedBlockingQueue, etc.
Timeout support - Operations can have time limits
Collection interface - Implements Queue and Collection interfaces
Atomic operations - All operations are atomic and thread-safe
Fair access - Optional fairness policy for thread scheduling

Basic Syntax for ArrayBlockingQueue and LinkedBlockingQueue

import java.util.concurrent.BlockingQueue;
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.LinkedBlockingQueue;

public class Main {
    public static void main(String[] args) throws InterruptedException {
        // ArrayBlockingQueue
        BlockingQueue<Integer> arrayQueue = new ArrayBlockingQueue<>(3);
        arrayQueue.put(1);
        arrayQueue.put(2);
        System.out.println("ArrayBlockingQueue peek: " + arrayQueue.peek()); // 1
        System.out.println("ArrayBlockingQueue removed: " + arrayQueue.take()); // 1

        // LinkedBlockingQueue
        BlockingQueue<Integer> linkedQueue = new LinkedBlockingQueue<>(3);
        linkedQueue.put(10);
        linkedQueue.put(20);
        System.out.println("LinkedBlockingQueue peek: " + linkedQueue.peek()); // 10
        System.out.println("LinkedBlockingQueue removed: " + linkedQueue.take()); // 10
    }
}

Core Operations

Operation / Method	ArrayBlockingQueue	LinkedBlockingQueue	Description
Insert (Block) `put(e)`	O(1)	O(1)	Blocks until space available
Insert (Timeout) `offer(e, time, unit)`	O(1)	O(1)	Waits for specified time
Insert (No Block) `offer(e)`	O(1)	O(1)	Returns false if full
Insert (Exception) `add(e)`	O(1)	O(1)	Throws exception if full
Remove (Block) `take()`	O(1)	O(1)	Blocks until element available
Remove (Timeout) `poll(time, unit)`	O(1)	O(1)	Waits for specified time
Remove (No Block) `poll()`	O(1)	O(1)	Returns null if empty
Remove (Exception) `remove()`	O(1)	O(1)	Throws exception if empty
Examine `peek()`	O(1)	O(1)	Returns head without removing
Size `size()`	O(1)	O(1)	Current number of elements
Capacity `remainingCapacity()`	O(1)	O(1)	Available space
Contains `contains(o)`	O(n)	O(n)	Search for element
Remove Specific `remove(o)`	O(n)	O(n)	Remove specific element
Drain `drainTo(collection)`	O(n)	O(n)	Transfer all elements to collection

ArrayBlockingQueue vs LinkedBlockingQueue features:

Feature	ArrayBlockingQueue	LinkedBlockingQueue
Storage	Fixed-size array	Dynamic linked nodes
Capacity	Fixed at creation	Fixed or unbounded
Memory	Pre-allocated	Allocated on demand
Locks	Single lock	Two locks (put/take)
Performance	Better for bounded queues	Better for high throughput
GC Pressure	Lower	Higher (node allocation)

Classic Use Cases & Problems

Producer-Consumer Pattern - Multiple threads producing/consuming data
Thread Pool Task Queues - Executor framework uses BlockingQueue
Rate Limiting and Throttling - Control processing speed
Batch Processing Systems - Accumulate work units for batch processing
Event-Driven Architectures - Decouple event producers from consumers
Message Passing Systems - Inter-thread communication
Resource Pool Management - Manage limited resources among threads
Data Pipeline Processing - Chain of processing stages
Load Balancing - Distribute work across multiple worker threads
Bounded Buffer Problem - Classic synchronization problem
Work Stealing Algorithms - Task distribution in parallel computing
Real-time Data Processing - Handle continuous data streams
Microservices Communication - Async communication between services
Cache Warming - Pre-load cache data in background threads

Example

import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.BlockingQueue;

/**
 * Simple Producer-Consumer Example using BlockingQueue
 * 
 * Real scenario: Online Store Order Processing
 * - Customer places orders (Producer)
 * - Warehouse processes orders (Consumer)
 */
public class SimpleProducerConsumer {

    public static void main(String[] args) {
        // Shared queue between producer and consumer (max 5 orders)
        BlockingQueue<String> orderQueue = new ArrayBlockingQueue<>(5);

        // Producer: Customer placing orders
        Thread customer = new Thread(() -> {
            String[] orders = {
                "Order-1: iPhone 14", 
                "Order-2: MacBook Pro", 
                "Order-3: AirPods", 
                "Order-4: iPad", 
                "Order-5: Apple Watch",
                "Order-6: Magic Mouse",
                "Order-7: Keyboard"
            };

            try {
                for (String order : orders) {
                    System.out.println("Customer placing: " + order);
                    orderQueue.put(order); // Blocks if queue is full
                    Thread.sleep(500); // Customer thinks for 500ms before next order
                }
                System.out.println("Customer finished placing all orders");

            } catch (InterruptedException e) {
                System.out.println("Customer interrupted");
            }
        });

        // Consumer: Warehouse processing orders
        Thread warehouse = new Thread(() -> {
            try {
                Thread.sleep(2000); // Warehouse starts working after 2 seconds

                while (true) {
                    String order = orderQueue.take(); // Blocks if queue is empty
                    System.out.println("Warehouse processing: " + order);
                    Thread.sleep(1000); // Takes 1 second to process each order
                    System.out.println("Warehouse completed: " + order);
                }

            } catch (InterruptedException e) {
                System.out.println("Warehouse stopped working");
            }
        });

        // Start both threads
        customer.start();
        warehouse.start();

        // Let them run for 10 seconds, then stop
        try {
            Thread.sleep(10000);
            warehouse.interrupt(); // Stop the warehouse
            customer.join(); // Wait for customer to finish
            System.out.println("\n Store closed for the day!");

        } catch (InterruptedException e) {
            System.out.println("Main interrupted");
        }
    }
}

Summary

BlockingQueue is the cornerstone of concurrent programming in Java, providing thread-safe, blocking operations that are essential for producer-consumer patterns. ArrayBlockingQueue offers better memory efficiency for bounded scenarios, while LinkedBlockingQueue provides higher throughput for demanding applications. Choose based on your specific concurrency needs, memory constraints, and performance requirements.

4. BitSet

BitSet is a resizable array of bits that provides efficient storage and manipulation of boolean values. Each bit can be set (1) or cleared (0), making it extremely memory-efficient for representing large sets of boolean flags or performing set operations on integers.It's part of the java.util package.

Key Properties

Memory efficient - Uses only 1 bit per boolean value (vs 8 bits for boolean array)
Dynamically resizable - Grows automatically as needed
Fast bitwise operations - Hardware-optimized bit manipulation
Set operations support - AND, OR, XOR, NOT operations
Thread-unsafe - Requires external synchronization for concurrent access
Zero-based indexing - Bits are numbered from 0 to size-1
Automatic bit clearing - Unset bits are automatically 0 (false)
Efficient iteration - Special methods to iterate over set bits only
Serializable - Can be serialized/deserialized
Cloneable - Supports deep copying
No null values - Only boolean states (set/clear)
Compact representation - Internally uses long arrays for storage

Basic Syntax for BitSet

import java.util.BitSet;

public class Main {
    public static void main(String[] args) {
        // Create a BitSet
        BitSet bits = new BitSet();

        // Set bits
        bits.set(0);          // set bit at index 0
        bits.set(2);          // set bit at index 2
        bits.set(4, 7);       // set bits from index 4 to 6 (7 exclusive)

        // Get bits
        System.out.println("Bit at index 2: " + bits.get(2)); // true
        System.out.println("Bit at index 3: " + bits.get(3)); // false

        // Clear bits
        bits.clear(2);        // clear bit at index 2

        // Flip bits
        bits.flip(0);         // flip bit at index 0

        // Size and length
        System.out.println("BitSet length: " + bits.length());
        System.out.println("BitSet size: " + bits.size());

        // Print BitSet
        System.out.println("BitSet: " + bits);
    }
}

Core Operations

Operation	Method	Time Complexity	Space Complexity	Description
Set Bit	`set(int bitIndex)`	O(1) amortized	O(1)	Set bit at index to 1
Set Range	`set(int from, int to)`	O(n)	O(1)	Set multiple bits in range
Clear Bit	`clear(int bitIndex)`	O(1)	O(1)	Set bit at index to 0
Clear Range	`clear(int from, int to)`	O(n)	O(1)	Clear multiple bits in range
Clear All	`clear()`	O(1)	O(1)	Clear all bits
Get Bit	`get(int bitIndex)`	O(1)	O(1)	Get bit value at index
Get Range	`get(int from, int to)`	O(n)	O(n)	Get BitSet subset
Flip Bit	`flip(int bitIndex)`	O(1)	O(1)	Toggle bit at index
Flip Range	`flip(int from, int to)`	O(n)	O(1)	Toggle multiple bits
AND Operation	`and(BitSet set)`	O(n)	O(1)	Logical AND with another BitSet
OR Operation	`or(BitSet set)`	O(n)	O(1)	Logical OR with another BitSet
XOR Operation	`xor(BitSet set)`	O(n)	O(1)	Logical XOR with another BitSet
AND-NOT	`andNot(BitSet set)`	O(n)	O(1)	AND with complement of set
Size	`size()`	O(1)	O(1)	Number of bits of space used
Length	`length()`	O(1)	O(1)	Highest set bit index + 1
Cardinality	`cardinality()`	O(n)	O(1)	Number of set bits
Is Empty	`isEmpty()`	O(1)	O(1)	Check if no bits are set
Next Set Bit	`nextSetBit(int from)`	O(1) avg	O(1)	Find next set bit from index
Next Clear Bit	`nextClearBit(int from)`	O(1) avg	O(1)	Find next clear bit from index
Previous Set Bit	`previousSetBit(int from)`	O(1) avg	O(1)	Find previous set bit
Previous Clear Bit	`previousClearBit(int from)`	O(1) avg	O(1)	Find previous clear bit
Intersects	`intersects(BitSet set)`	O(n)	O(1)	Check if any bits are common
Clone	`clone()`	O(n)	O(n)	Create deep copy
To Byte Array	`toByteArray()`	O(n)	O(n)	Convert to byte array
To Long Array	`toLongArray()`	O(n)	O(n)	Convert to long array

BitSet vs Alternatives

Use Case	BitSet	boolean[]	Set	EnumSet
Memory Efficiency	Excellent	Poor	Very Poor	Excellent
Performance	Excellent	Good	Poor	Excellent
Set Operations	Native	Manual	Good	Native
Range Operations	Native	Manual	Manual	Limited
Thread Safety	No	No	Depends	No
Sparse Data	Good	Poor	Excellent	N/A

Classic Use Cases & Problems

Sieve of Eratosthenes - Finding prime numbers efficiently
Bloom Filters - Probabilistic membership testing
Set Operations - Union, intersection, difference of integer sets
Graph Algorithms - Visited node tracking in BFS/DFS
Permutation Generation - Track used elements in backtracking
Bit Manipulation Problems - Subset generation, bit counting
Database Indexing - Bitmap indexes for fast queries
Compiler Design - Register allocation, live variable analysis
Image Processing - Binary image representation and operations
Game Development - Collision detection, state flags
Network Protocols - Flag management, packet filtering
Cryptography - One-time pad, stream ciphers
Data Compression - Run-length encoding preprocessing
Memory Management - Free/allocated block tracking
Scheduling Algorithms - Resource availability tracking
Machine Learning - Feature selection, sparse data representation

Example

Finding Primes Using BitSet

import java.util.BitSet;

public class SieveBitSet {
    public static void main(String[] args) {
        int N = 50;
        BitSet primes = new BitSet(N + 1);

        // Initially assume all numbers >=2 are prime
        primes.set(2, N + 1); // set bits 2..N

        for (int i = 2; i * i <= N; i++) {
            if (primes.get(i)) {
                // Mark multiples of i as non-prime
                for (int j = i * i; j <= N; j += i) {
                    primes.clear(j);
                }
            }
        }

        // Print primes
        System.out.println("Primes up to " + N + ":");
        for (int i = 2; i <= N; i++) {
            if (primes.get(i)) {
                System.out.print(i + " ");
            }
        }
    }
}

Summary

BitSet is a specialized, highly efficient data structure for boolean operations and set manipulation. It shines in mathematical algorithms, large-scale boolean flag management, and memory-constrained environments. Choose BitSet when you need fast bitwise operations on large datasets, especially for algorithms like sieve methods, graph traversal state tracking, or any scenario involving set theory operations on integers. Its memory efficiency (1 bit per boolean vs 8 bits for boolean arrays) makes it invaluable for applications handling millions of boolean flags.

5. CopyOnWriteArrayList/CopyOnWriteArraySet

CopyOnWriteArrayList is a thread-safe variant of ArrayList (in java.util.concurrent) where all mutative operations (add, set, remove, etc.) create a fresh copy of the underlying array. Its iterators work on an immutable snapshot, so they never throw ConcurrentModificationException.

CopyOnWriteArraySet is a thread-safe Set that uses CopyOnWriteArrayList internally. It enforces uniqueness with addIfAbsent, and iterators also operate on a snapshot.

Both are ideal for read-heavy, infrequently modified data—iterations are fast and lock-free, while writes are costly due to array copying. Common use cases include listener registries, configuration snapshots, and caches. They are not suitable for write-heavy workloads because of high write overhead and GC pressure.

Key Properties

Thread-safe, suitable for concurrent read-heavy scenarios.
All mutative operations (add, set, remove) create a fresh copy of the underlying array.
Iterators are weakly consistent: do not throw ConcurrentModificationException.
Reads are lock-free, writes are expensive due to array copying.

Basic Syntax for CopyOnWriteArrayList and CopyOnWriteArraySet

import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.CopyOnWriteArraySet;

public class Main {
    public static void main(String[] args) {
        // -------------------------
        // CopyOnWriteArrayList
        // -------------------------
        CopyOnWriteArrayList<String> list = new CopyOnWriteArrayList<>();
        list.add("Apple");
        list.add("Banana");
        list.add("Orange");

        System.out.println("CopyOnWriteArrayList elements:");
        for (String fruit : list) {
            System.out.println(fruit);
        }

        list.remove("Banana");
        System.out.println("After removal: " + list);

        // -------------------------
        // CopyOnWriteArraySet
        // -------------------------
        CopyOnWriteArraySet<String> set = new CopyOnWriteArraySet<>();
        set.add("Apple");
        set.add("Banana");
        set.add("Apple"); // duplicate ignored

        System.out.println("\nCopyOnWriteArraySet elements:");
        for (String fruit : set) {
            System.out.println(fruit);
        }

        set.remove("Banana");
        System.out.println("After removal: " + set);
    }
}

Core Operations

Operation	Method	Time Complexity	Description
Add	`add(E e)`	O(n)	Adds element at the end
Remove	`remove(Object o)`	O(n)	Removes first occurrence
Get	`get(int index)`	O(1)	Retrieves element at index
Set	`set(int index, E element)`	O(n)	Replaces element at index
Contains	`contains(Object o)`	O(n)	Checks if element exists
Size	`size()`	O(1)	Returns number of elements
Iterator	`iterator()`	O(1)	Returns snapshot iterator
Clear	`clear()`	O(n)	Removes all elements

Example

import java.util.concurrent.CopyOnWriteArrayList;

// Subscriber interface
interface Subscriber {
    void notify(String message);
}

// Event Bus
class EventBus {
    private CopyOnWriteArrayList<Subscriber> subscribers = new CopyOnWriteArrayList<>();

    // Add a subscriber
    public void subscribe(Subscriber subscriber) {
        subscribers.add(subscriber);
    }

    // Remove a subscriber
    public void unsubscribe(Subscriber subscriber) {
        subscribers.remove(subscriber);
    }

    // Publish an event to all subscribers
    public void publish(String message) {
        for (Subscriber s : subscribers) {
            s.notify(message);
        }
    }
}

// Demo
public class Main {
    public static void main(String[] args) {
        EventBus bus = new EventBus();

        // Add subscribers
        bus.subscribe(msg -> System.out.println("Subscriber 1 received: " + msg));
        bus.subscribe(msg -> System.out.println("Subscriber 2 received: " + msg));

        // Publish events
        bus.publish("Event A");
        bus.publish("Event B");

        // Remove a subscriber
        bus.unsubscribe(msg -> System.out.println("Subscriber 2 received: " + msg));

        // Publish another event
        bus.publish("Event C");
    }
}

Multiple threads can publish events (read/iterate) safely while subscribers are added/removed.
Iteration is snapshot-based, so no ConcurrentModificationException occurs.
Writes (adding/removing subscribers) are rare, which suits the cost of copying the array.

Classic Use Cases & Problems

Event listener lists where reads are frequent but modifications are rare.
Caching read-heavy data structures.
Pub-sub systems where many threads read concurrently.
Iterating safely without worrying about ConcurrentModificationException.
Maintaining snapshots in concurrent applications.

Problems / Considerations:

High memory and CPU overhead if writes are frequent (copying entire array on every write).
Not suitable for write-heavy workloads.

Summary

Use CopyOnWriteArrayList / CopyOnWriteArraySet when reads far exceed writes and you need thread-safe, snapshot-style iteration without extra synchronization. Avoid them for write-heavy workloads due to the high cost of copying the array on every modification.

6. Disjoint Set Union (DSU) / Union-Find in Java

A Disjoint Set Union (DSU) is a data structure that keeps track of a partition of a set into disjoint (non-overlapping) subsets. It is especially useful in problems involving connectivity, merging groups, and cycle detection.

Supports two main operations:

Find: Determine which subset a particular element belongs to.
Union: Merge two subsets into a single subset.

Optimizations include:

Path Compression in find()
Union by Rank / Sizeinunion()`

Key Properties

Efficient for connectivity problems in graphs (like detecting cycles, Kruskal’s MST algorithm).
Each element belongs to exactly one subset.
Supports dynamic connectivity queries.
Almost constant time per operation: O(α(n)), where α(n) is the inverse Ackermann function.

Core Operations

Operation	Method	Time Complexity	Description
Find	`find(int x)`	O(α(n))	Returns the representative (root) of element x
Union	`union(int x, int y)`	O(α(n))	Merges the sets containing x and y
Connected	`connected(int x, int y)`	O(α(n))	Checks if x and y belong to the same set
Size	`size()` (optional)	O(1)	Returns the number of disjoint sets

Classic Use Cases

Kruskal’s Minimum Spanning Tree algorithm.
Detecting cycles in undirected graphs.
Dynamic connectivity problems (e.g., network connectivity).
Union of sets in clustering algorithms or percolation problems.

Example


public class DSU {
    private int[] parent;
    private int[] rank;

    // Initialize n elements
    public DSU(int n) {
        parent = new int[n];
        rank = new int[n];
        for (int i = 0; i < n; i++) {
            parent[i] = i; // each element is its own parent
            rank[i] = 0;
        }
    }

    // Find with path compression
    public int find(int x) {
        if (parent[x] != x) {
            parent[x] = find(parent[x]);
        }
        return parent[x];
    }

    // Union by rank
    public void union(int x, int y) {
        int rootX = find(x);
        int rootY = find(y);
        if (rootX == rootY) return;

        if (rank[rootX] < rank[rootY]) {
            parent[rootX] = rootY;
        } else if (rank[rootX] > rank[rootY]) {
            parent[rootY] = rootX;
        } else {
            parent[rootY] = rootX;
            rank[rootX]++;
        }
    }

    // Check if two elements are connected
    public boolean connected(int x, int y) {
        return find(x) == find(y);
    }
}

// Demo
public class Main {
    public static void main(String[] args) {
        DSU dsu = new DSU(5);

        dsu.union(0, 1);
        dsu.union(1, 2);

        System.out.println(dsu.connected(0, 2)); // true
        System.out.println(dsu.connected(0, 3)); // false
    }
}

Summary

Use Disjoint Set Union for connectivity problems and graph algorithms.
Highly efficient due to path compression and union by rank, almost constant time per operation. Ideal for Kruskal’s MST, dynamic connectivity, clustering, and percolation problems.

7. Fenwick Tree (Binary Indexed Tree) in Java

A Fenwick Tree, also called Binary Indexed Tree (BIT), is a data structure that efficiently supports:

Prefix sum queries (sum of first k elements)
Point updates (update a single element)
- Time complexity: O(log n) for both query and update.
- Space complexity: O(n).
- Ideal for scenarios where you have frequent prefix sum or cumulative frequency queries with dynamic updates.

Key Properties

Efficient for range sum queries on mutable arrays.
Uses binary representation of indices to traverse parent/child relationships.
Supports additive operations (sum, XOR, etc.).
Not suitable for arbitrary range updates unless combined with advanced variants (like range update BIT).

Core Operations

Operation	Method	Time Complexity	Description
Update / Add	`update(index, value)`	O(log n)	Adds value to element at index
Query / PrefixSum	`query(index)`	O(log n)	Returns sum of elements [0..index]
Build Tree	Constructor / `build(arr)`	O(n)	Initializes tree from array

Classic Use Cases

Range sum queries with dynamic updates (e.g., cumulative frequency tables).
Counting inversions in an array.
Competitive programming problems involving prefix sums, frequencies, or 2D variants.
Efficiently implementing histograms or cumulative statistics.

Example


public class FenwickTree {
    private int[] bit; // Binary Indexed Tree array (1-based indexing)
    private int size;  // Size of the original array

    /**
     * Constructs a Fenwick Tree for an array of a given size.
     * The tree is initialized with all zeros.
     *
     * @param size The size of the original array for which the Fenwick Tree is built.
     */
    public FenwickTree(int size) {
        this.size = size;
        this.bit = new int[size + 1]; // 1-based indexing, so size + 1
    }

    /**
     * Updates the value at a specific index in the original array by adding 'delta'.
     * This update propagates through the Fenwick Tree.
     *
     * @param index The 0-based index in the original array to update.
     * @param delta The value to add to the element at the given index.
     */
    public void update(int index, int delta) {
        // Convert to 1-based indexing for BIT operations
        index++; 
        while (index <= size) {
            bit[index] += delta;
            // Move to the next parent node by adding the rightmost set bit
            index += (index & -index); 
        }
    }

    /**
     * Queries the prefix sum up to a specific index (inclusive) in the original array.
     *
     * @param index The 0-based index in the original array up to which to calculate the sum.
     * @return The sum of elements from index 0 to 'index' in the original array.
     */
    public int query(int index) {
        int sum = 0;
        // Convert to 1-based indexing for BIT operations
        index++; 
        while (index > 0) {
            sum += bit[index];
            // Move to the next parent node by subtracting the rightmost set bit
            index -= (index & -index); 
        }
        return sum;
    }

    /**
     * Calculates the sum of elements within a given range [left, right] (inclusive, 0-based).
     *
     * @param left The 0-based starting index of the range.
     * @param right The 0-based ending index of the range.
     * @return The sum of elements from 'left' to 'right'.
     */
    public int rangeSum(int left, int right) {
        if (left > right) {
            throw new IllegalArgumentException("Left index cannot be greater than right index.");
        }
        return query(right) - (left > 0 ? query(left - 1) : 0);
    }

    // Example Usage
    public static void main(String[] args) {
        int[] arr = {1, 2, 3, 4, 5};
        FenwickTree ft = new FenwickTree(arr.length);

        // Initialize Fenwick Tree with values from the array
        for (int i = 0; i < arr.length; i++) {
            ft.update(i, arr[i]);
        }

        System.out.println("Prefix sum up to index 2 (0-based): " + ft.query(2)); // Expected: 1 + 2 + 3 = 6
        System.out.println("Prefix sum up to index 4 (0-based): " + ft.query(4)); // Expected: 1 + 2 + 3 + 4 + 5 = 15

        // Update value at index 2 (change 3 to 10)
        ft.update(2, 7); // Add 7 to the existing value at index 2 (3 + 7 = 10)
        System.out.println("Prefix sum up to index 2 after update: " + ft.query(2)); // Expected: 1 + 2 + 10 = 13

        System.out.println("Range sum from index 1 to 3 (0-based): " + ft.rangeSum(1, 3)); // Expected: 2 + 10 + 4 = 16
    }
}

Summary

Use Fenwick Tree for dynamic prefix sums or cumulative frequency queries.
Efficient alternative to segment trees for point updates and prefix queries. Time complexity per operation: O(log n), space complexity: O(n).
Ideal for competitive programming, range queries, and real-time cumulative statistics.

8. Trie (Prefix Tree) in Java

A Trie, also known as a Prefix Tree, is a tree-like data structure used to store a dynamic set of strings efficiently, particularly for operations involving prefixes.

There is no built-in Trie in Java.
Typically implemented manually using custom classes with Map or arrays.
Can use java.util.Map or java.util.HashMap for child nodes.

Key Properties

Tree-based data structure storing strings or sequences.
Each node represents a single character or part of the key.
Supports fast prefix-based searches.
Root node represents empty string.
Efficient for word lookup, autocomplete, and dictionary operations.
Can store boolean flag to mark end of a word.

Core Operations

Operation	Method/Description	Time Complexity	Description
Insert	`insert(String word)`	O(L)	Add a word of length L
Search Exact	`search(String word)`	O(L)	Returns true if word exists
Starts With	`startsWith(String prefix)`	O(L)	Returns true if any word starts with given prefix
Delete	`delete(String word)`	O(L)	Removes a word
Traverse	`traverse()`	O(N*L)	Traverse all words stored (N words of avg length L)

Classic Use Cases & Problems

Use Cases:
- Autocomplete / Search suggestions
- Spell checking
- IP routing (storing prefixes)
- Dictionary / word frequency problems
- Longest prefix matching
Problems / Considerations:
- High memory usage for large alphabets if implemented naïvely.
- Insertion and search depend on word length, not number of words.
- Typically implemented with arrays (fixed alphabet) or HashMaps for children.

Example



import java.util.HashMap;

import java.util.Map;

class TrieNode {

    Map children = new HashMap<>();

    boolean isEndOfWord = false;

}

class Trie {

    private TrieNode root;

    public Trie() {

        root = new TrieNode();

    }

// Insert a word
public void insert(String word) {
    TrieNode node = root;
    for (char ch : word.toCharArray()) {
        node.children.putIfAbsent(ch, new TrieNode());
        node = node.children.get(ch);
    }
    node.isEndOfWord = true;
}

// Search for exact word
public boolean search(String word) {
    TrieNode node = root;
    for (char ch : word.toCharArray()) {
        node = node.children.get(ch);
        if (node == null) return false;
    }
    return node.isEndOfWord;
}

// Search for prefix
public boolean startsWith(String prefix) {
    TrieNode node = root;
    for (char ch : prefix.toCharArray()) {
        node = node.children.get(ch);
        if (node == null) return false;
    }
    return true;
}


}





// Demo

public class Main {

    public static void main(String[] args) {

        Trie trie = new Trie();

        trie.insert("apple");

        trie.insert("app");

        trie.insert("banana");

    System.out.println(trie.search("apple"));  // true
    System.out.println(trie.search("app"));    // true
    System.out.println(trie.search("appl"));   // false
    System.out.println(trie.startsWith("ap")); // true
    System.out.println(trie.startsWith("ba")); // true
}


}

Summary

Use Trie when you need efficient prefix searches or word lookups.
Ideal for autocomplete, dictionary, spell check, and IP prefix matching.
Efficient in search time (O(L)) but can be memory-intensive for large datasets.
Use HashMap children for dynamic alphabets, or arrays for fixed small alphabets.

Spring Boot Testing: A Comprehensive Best Practices Guide

AnkitDevCode — Tue, 02 Sep 2025 17:12:44 +0000

Introduction

In modern software development, testing is not a one-size-fits-all activity. Different kinds of tests serve different purposes — from quickly verifying small units of code to validating entire system flows under real-world conditions.
To design an efficient and maintainable test strategy, it’s important to understand the various types of tests, their scope, and their trade-offs in terms of speed, reliability, and coverage

The table below provides an overview to helps teams balance their testing strategy according to the Test Pyramid principle — having more fast, cheap unit tests at the base, fewer integration tests in the middle, and only a handful of slow, expensive tests (E2E, performance) at the top.

The golden rule is to write lots of unit tests, some integration tests, and few end-to-end tests.

A typical ratio:

70–80% unit tests (fast, isolated, cover edge cases)
15–20% integration tests (cross-layer correctness)
5–10% end-to-end (E2E) (real dependencies, full workflow)

Testing Strategy Guidelines

When to Use Each Test Type

Unit Tests: Use for business logic, algorithms, utility functions, and any code that can be tested in isolation. Aim for high coverage of your core business logic.
Integration Tests: Use for testing interactions between your application components, database operations, and internal service communication.
Component Tests: Use when you need to test a specific layer or module with some real dependencies but want faster execution than full integration tests.
E2E Tests: Use sparingly for critical user workflows that span multiple systems. Focus on high-value scenarios that would cause significant business impact if broken.
Functional Tests: Use to verify that features meet business requirements. Often written in collaboration with product owners and business analysts.
Contract Tests: Use when your application communicates with other services, especially in microservices architectures where service boundaries are critical.
Performance Tests: Use when you have specific performance requirements or when you need to understand system behavior under load.
Smoke Tests: Use for quick validation after deployments or major changes. Include in your deployment pipeline for immediate feedback.
Regression Tests: Maintain as part of your overall test suite to prevent reintroduction of fixed bugs and ensure stable functionality.
Security Tests: Integrate into your development and deployment process to identify vulnerabilities early and ensure security controls function correctly.

Note: This article highlights a few important test types, rather than covering every possible category.

Unit Testing

Purpose

Unit tests verify that individual classes and methods work correctly in isolation, without any external dependencies like databases, web services, or file systems.

Best Practices

Mock External Dependencies: Replace all external dependencies with mocks or stubs to ensure tests run fast and reliably. This includes databases, HTTP clients, file systems, and third-party services.
Follow the AAA Pattern: Structure tests with clear Arrange, Act, and Assert sections. Set up test data and mocks, execute the method under test, then verify the results and interactions.
Test Edge Cases: Don't just test the happy path. Include tests for null inputs, empty collections, boundary values, and error conditions. These edge cases often reveal bugs that normal usage might miss.
Use Descriptive Test Names: Test names should clearly describe what scenario is being tested and what outcome is expected. Avoid generic names like "testMethod1" or "shouldWork".
Keep Tests Independent: Each test should be able to run independently and in any order. Avoid shared state between tests and ensure proper setup and teardown.
Test One Thing at a Time: Each test should verify a single behavior or scenario. If you need multiple assertions, make sure they're all related to the same logical outcome.
Use Test Data Builders: Create builder patterns for test data to make tests more readable and maintainable. This approach makes it easy to create variations of test objects.

Let’s assume we want to write a unit test (using JUnit 5 + Mockito) for the following UserService class.

public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public String getUserName(Long id) {
        return userRepository.findById(id)
                .map(User::getName)
                .orElseThrow(() -> new RuntimeException("User not found"));
    }
}

The class under test→ UserService
Its dependency → UserRepository

Without Annotations (Manual Mocks, No Extension)
No @ExtendWith needed because we’re manually creating mocks with mock().

class UserServiceTest {

    private final UserRepository userRepository = mock(UserRepository.class);
    private final UserService userService = new UserService(userRepository);

    @Test
    void shouldReturnUserNameWhenUserExists() {
        when(userRepository.findById(1L)).thenReturn(Optional.of(new User(1L, "Alice")));

        String result = userService.getUserName(1L);

        assertEquals("Alice", result);
    }
}

When to Use @ExtendWith(MockitoExtension.class)

If you want to use Mockito annotations like:

@Mock → creates mock objects
@InjectMocks → injects mocks into the class under test then you need @ExtendWith(MockitoExtension.class) on your test class.

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    @Test
    void shouldReturnUserNameWhenUserExists() {
        when(userRepository.findById(1L)).thenReturn(Optional.of(new User(1L, "Alice")));

        String result = userService.getUserName(1L);

        assertEquals("Alice", result);
    }
}

What is @InjectMocks?

@InjectMocks is a Mockito annotation that creates an instance of the class under test and automatically injects the required dependencies (the ones you marked with @Mock) into it.

So instead of you manually writing:

UserRepository userRepository = mock(UserRepository.class);
UserService userService = new UserService(userRepository);

You can let Mockito handle it:

@Mock
private UserRepository userRepository;

@InjectMocks
private UserService userService;

Why use @InjectMocks?

Less boilerplate — no need to manually new-up UserService.
Clearer intent — it’s obvious which class is being tested (userService).
Works with constructor, setter, or field injection.

👉 Follow the method naming pattern:

should<ExpectedBehavior>When<Condition>

shouldReturnUnknownWhenUserDoesNotExist
shouldThrowExceptionWhenUserAlreadyExists

Use @ParameterizedTest for multiple inputs

Example without ParameterizedTest

@Test
void shouldReturnAliceWhenIdIs1() {
    when(userRepository.findById(1L)).thenReturn(Optional.of(new User(1L, "Alice")));
    assertEquals("Alice", userService.getUserName(1L));
}

@Test
void shouldReturnUnknownWhenIdDoesNotExist() {
    when(userRepository.findById(99L)).thenReturn(Optional.empty());
    assertEquals("Unknown", userService.getUserName(99L));
}

Example with ParameterizedTest

@ParameterizedTest
    @CsvSource({
        "1, Alice",    // user exists
        "2, Bob",      // user exists
        "3, Unknown"   // user does not exist
    })
    void shouldReturnUserNameOrUnknownBasedOnExistence(Long id, String expectedName) {
        // Arrange
        if (!expectedName.equals("Unknown")) {
            when(userRepository.findById(id))
                .thenReturn(Optional.of(new User(id, expectedName)));
        } else {
            when(userRepository.findById(id)).thenReturn(Optional.empty());
        }

        // Act
        String result = userService.getUserName(id);

        // Assert
        assertEquals(expectedName, result);
    }

Verify interactions with mocks

@Test
void shouldDeleteUser() {
    userService.deleteUser(1L);
    verify(userRepository, times(1)).deleteById(1L);
}

Test with ArgumentCaptor

The use of ArgumentCaptor in unit testing (with Mockito) is to capture arguments that are passed to mocked methods, so you can make assertions on them.

Useful when you want to inspect properties of the passed object.
Can capture multiple values if the method is called multiple times.
Makes assertions more fine-grained than just verifying method calls.

Capture argument for verification

Simple Example: please note createUser doesn't return anything here.
Without ArgumentCaptor, you can only check if save() was called.But you don’t know what object was passed. ArgumentCaptor lets you inspect the actual argument (User) and assert its fields.

class UserService {
    private final UserRepository repo;

    UserService(UserRepository repo) {
        this.repo = repo;
    }

    void createUser(String name) {
        User user = new User(null, name);
        repo.save(user);
    }
}

 @ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository repo;

    @InjectMocks
    private UserService service;

    @Test
    void shouldCaptureUserPassedToRepository() {
        // Given
        ArgumentCaptor<User> captor = ArgumentCaptor.forClass(User.class);

        // When
        service.createUser("Alice");

        // Then
        Mockito.verify(repo).save(captor.capture());
        assertEquals("Alice", captor.getValue().getName()); // we can check input
    }
}

Answer / custom return behavior

This is very useful when the stubbed method needs to do something dynamic based on the input, not just return a fixed value.

Basic Example (Fixed Return)

when(repo.save(any(User.class))).thenReturn(new User(1L, "Alice"));

Here the save() method always returns the same user, regardless of what was passed.

thenReturn() → good for simple, static returns.
thenAnswer() → powerful when return depends on input or custom logic.

Using Answer for Dynamic Return

Sometimes you want the return value to depend on the argument passed. That’s where Answer comes in.

when(repo.findById(anyLong()))
    .thenAnswer(invocation -> {
        Long id = invocation.getArgument(0);
        if (id == 0) throw new IllegalArgumentException("Invalid ID");
        return new User(id, "User" + id);
    });

When To Use Answer

When you want to simulate DB behavior (e.g., assigning IDs).
When the return should depend on input values.
When you need to throw exceptions for specific inputs.

Void Methods (doNothing / doThrow

Since void methods can’t be stubbed with when(...).thenReturn(...), Mockito gives us:

doNothing() → clarify intention when void method should just pass.
doThrow() → test error handling for void methods.
doAnswer() → add side-effects like logging, counters, or capturing arguments.

Snnipet:

@Test
void shouldRegisterUserAndSendEmail() {
    // void method -> doNothing
    doNothing().when(emailService).sendWelcomeEmail(any(User.class));

    service.register("Alice");

    verify(emailService).sendWelcomeEmail(any(User.class));
}

@Test
void shouldHandleEmailFailure() {
    doThrow(new RuntimeException("SMTP error"))
        .when(emailService).sendWelcomeEmail(any(User.class));

    assertThrows(RuntimeException.class, () -> service.register("Bob"));
}

What is BDDMockito?

BDD = Behavior-Driven Development
Mockito provides BDD style methods: given(), willReturn(), willThrow(), then().
The behavior is the same as standard Mockito, but it improves readability and aligns with BDD conventions.

Test in BDD Style

    @Test
    void shouldRegisterUserAndSendEmail() {
        // Given
        User user = new User(null, "Alice", "alice@example.com");
        given(repo.save(any(User.class))).willAnswer(inv -> {
            User u = inv.getArgument(0);
            u.setId(101L); // mimic DB
            return u;
        });

        // When
        User saved = service.register("Alice", "alice@example.com");

        // Then
        then(repo).should().save(any(User.class));
        then(email).should().sendWelcomeEmail("alice@example.com");

        assertEquals(101L, saved.getId());
        assertEquals("Alice", saved.getName());
    }

Advantages of BDDMockito

Improves readability: clearly separates Given, When, Then.
Aligns tests with BDD style requirements.
Makes test intentions obvious for new team members.

Parallel Test Execution

JUnit 5 supports junit.jupiter.execution.parallel.enabled=true.

Combine with Stateless test design (no shared mutable state).
Be careful with shared resources

Controlling Test Lifecycle with @TestInstance

By default, JUnit creates a new test class instance per test method (PER_METHOD).
With @TestInstance(PER_CLASS), JUnit creates only one instance of the test class for all methods.

import org.junit.jupiter.api.*;

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class UserServiceIntegrationTest {

    private UserService userService;

    @BeforeAll
    void setUpAll() {
        System.out.println("Init once for the whole class");
        userService = new UserService();
    }

    @BeforeEach
    void setUpEach() {
        System.out.println("Runs before each test");
    }

    @Test
    void testCreateUser() {
        System.out.println("Test 1");
        // uses same UserService instance
    }

    @Test
    void testFindUser() {
        System.out.println("Test 2");
        // still same UserService instance
    }
}

Why Use PER_CLASS

Performance optimization
- If your test class has expensive setup (e.g., loading Spring beans manually, external resource initialization), using a single test instance avoids redoing that work for every test method.
- Example: Large @BeforeEach → becomes @BeforeAll.
State sharing between tests
- With PER_CLASS, you can keep shared state across test methods (e.g., Testcontainers instance, mock server, expensive cached objects).
- Useful when multiple test methods need to reuse the same resource.
Cleaner lifecycle management
- You can use non-static @BeforeAll and @AfterAll methods (normally they must be static in JUnit)..

Caveats

Shared state across tests can lead to test pollution if not carefully managed.
Best paired with clear teardown logic or immutable test data to avoid flaky tests.

Follow FIRST principles

Fast → runs quickly
Isolated → doesn’t depend on DB/network
Repeatable → same result every run
Self-validating → uses assertions, not console output
Timely → written close to when code is written

Component Testing

Purpose

Component testing (sometimes called slice testing) is:
Testing a single Spring-managed component or a set of components together without starting the full application.

Best Practices

Use Spring Boot Test Slices: Leverage annotations like WebMvcTest, DataJpaTest, and JsonTest to load only the relevant parts of the Spring context for faster test execution.
Test Layer Boundaries: Focus on testing how different layers of your application interact. For example, test how controllers handle requests and responses, or how repositories interact with the database.
Mock Collaborators: Mock services and components that aren't part of the slice being tested. This keeps tests focused and fast while still testing real integration points.
Test Error Handling: Verify that your components properly handle and propagate errors. Test validation, exception handling, and error responses.
Validate Serialization: Test JSON serialization and deserialization, especially for REST APIs. Ensure that your DTOs and entities are correctly mapped.

Use Slice Annotations When Possible

Spring Boot provides slice testing annotations:

@WebMvcTest Test controllers with MockMvc, auto-configures MVC beans
@DataJpaTest Test repositories with in-memory DB (H2)
@RestClientTest Test REST clients like WebClient
@JsonTest Test JSON serialization/deserialization
@SpringBootTest Full context (use sparingly for component integration)
@TestConfiguration For custom test configurations.

Mock External Dependencies

Choose the Right Test Slice: Use specific annotations like @WebMvcTest for controllers, @DataJpaTest for repositories, rather than always using @SpringBootTest which loads the entire context.
Mock Dependencies Properly: Use @MockBean for Spring-managed beans and @Mock for regular dependencies. This keeps tests fast and isolated.

Testing Controller Components

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    void shouldCreateUserAndReturnCreated() throws Exception {
        // Arrange
        CreateUserRequest request = new CreateUserRequest("john@example.com", "John Doe");
        UserResponse response = new UserResponse(1L, "john@example.com", "John Doe");

        when(userService.createUser(any(CreateUserRequest.class))).thenReturn(response);

        // Act & Assert
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.id").value(1))
                .andExpect(jsonPath("$.email").value("john@example.com"))
                .andExpect(jsonPath("$.name").value("John Doe"));

        verify(userService).createUser(any(CreateUserRequest.class));
    }
}

Testing Repository Components

For repositories: @DataJpaTest + H2 in-memory DB.

@DataJpaTest
class UserRepositoryTest {

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldSaveAndFindUser() {
        User user = userRepository.save(new User(null, "Alice"));
        assertTrue(userRepository.findById(user.getId()).isPresent());
    }
}

Testing Service Components

For service layer, use @ExtendWith(MockitoExtension.class)
Mock dependencies to test service logic without DB or external calls.

We have already seen a couple of examples in the previous section.

Use Spring Profiles for Tests

Using Spring Profiles for tests is a best practice in Spring applications to isolate test configurations from production configurations.

Spring Boot automatically looks for configuration files in the src/main/resources and src/test/resources folders.

Test Configuration (src/test/resources/application-test.yml)

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driverClassName: org.h2.Driver
    username: sa
    password:
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
  logging:
    level:
      org.springframework.web: DEBUG
      com.yourpackage: DEBUG

app:
  cache:
    enabled: false
  external-api:
    base-url: http://localhost:8080/mock

# Disable unnecessary features in tests
management:
  endpoints:
    enabled-by-default: false

Activate Test Profile in Component Tests

Use @ActiveProfiles on your test class:

@ExtendWith(MockitoExtension.class)
@ActiveProfiles("test")
@WebMvcTest(UserController.class)
class UserControllerTest {
}

This loads beans from application-test.yml instead of application.yml.

By default, Spring Boot always loads application.yml (and then applies overrides from profile-specific files like application-local.yml).
If you put application-test.yml only under src/test/resources, and not under src/main/resources, then in test runs only the test file exists and Since there’s no application.yml in classpath, Spring won’t load or merge it.

Use Test-Specific Configuration Classes

Only loaded when @ActiveProfiles("test") is set.
Keeps test beans separate from production beans.

You should create TestConfig in the src/test package.

@Configuration
@Profile("test")
public class TestConfig {

    @Bean
    public EmailService emailService() {
        // return a mock or dummy email service for tests
        return Mockito.mock(EmailService.class);
    }
}

Can be imported in your test classes with @Import(TestConfig.class) if needed.

@WebMvcTest(UserController.class)
@Import(TestConfig.class)
class UserControllerTest {

    @Autowired
    private EmailService emailService; // comes from TestConfig
}

Use @TestConfiguration for Inline Test Beans

Spring Boot provides @TestConfiguration for test-only bean definitions:
This keeps test beans scoped to this test class.

@WebMvcTest(UserController.class)
class UserControllerTest {

    @TestConfiguration
    static class Config {
        @Bean
        public EmailService emailService() {
            return Mockito.mock(EmailService.class);
        }
    }

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Autowired
    private EmailService emailService;

When to Use Spring Profiles for Tests

Separate Test-Specific Configuration
Use a dedicated profile (e.g., test) to load beans, properties, or configurations that are only relevant during testing.
Example: different database (H2 in-memory DB) for tests instead of production DB.
Avoid Interference with Production Configuration
Running tests with a separate profile prevents accidental use of production services or endpoints.
You can define test-specific beans that mock external services (e.g., payment gateway, email service) under the test profile.

Integration Testing

Purpose

Integration tests verify that multiple components work together correctly, including interactions between services, databases, and external systems.

Why Integration Tests Matter

Bridging the Gap: Unit tests validate logic, but only integration tests confirm that layers (controller ↔ service ↔ repo ↔ DB) actually work together.
Catch Environment Gaps: Many bugs in production come from misconfigured beans, serialization issues, or DB quirks (H2 ≠ Postgres!) that unit tests miss.
CI/CD Gatekeeper: In most mature teams, integration tests run on every pull request → preventing broken builds from merging.

Best Practices

Use Real Databases When Possible: While H2 in-memory databases are fast, they don't always behave like production databases. Consider using containers with real database engines for more accurate testing.
Test Actual Data Flow: Verify that data correctly flows through your application layers. Test that controllers properly call services, services interact with repositories, and data is correctly persisted and retrieved.
Isolate External Dependencies: Use test doubles for external services while keeping internal components real. This provides confidence in your integration while maintaining test reliability.
Use Transaction Rollback: Configure tests to rollback database transactions after each test to maintain clean state between tests.
Test Configuration: Verify that your Spring configuration works correctly by testing that beans are properly wired and configurations are applied.
Focus on Critical Paths: Integration tests are more expensive than unit tests, so focus on testing the most critical business workflows and integration points.

Use @SpringBootTest Wisely

@SpringBootTest loads the full context (all beans).
Useful when testing end-to-end within the app.
But it’s heavy → avoid for every test class.
Prefer narrower slices (@WebMvcTest, @DataJpaTest) when possible.

** Choose the Right Testing Strategy based on use case**

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserIntegrationTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldCreateUserSuccessfully() {
        // Test full request flow
        CreateUserRequest request = new CreateUserRequest("john@example.com", "John");

        ResponseEntity<User> response = restTemplate.postForEntity(
            "/api/users", request, User.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(userRepository.findByEmail("john@example.com")).isPresent();
    }
}

What @SpringBootTest Does

Loads the entire Spring ApplicationContext (all beans, configs, filters, interceptors, DB connections, etc.).
Boots your app in an embedded container (Tomcat/Jetty/Undertow, depending on your setup).
You can then hit your controller endpoints just like a real client would.

Use Profiles for Testing

As discussed in detail in the previous section.

Keep application-test.yml with test-specific configs and separate profile i.e @ActiveProfiles("integration-test")
Example: lower logging level, test DB credentials, disable real integrations (e.g., email).

Performance and Optimization

integration tests in Spring Boot can easily become slow if not optimized. Let’s talk about performance best practices with focus on context reuse and related tricks.

Context Reuse (Spring TestContext Framework)

By default, Spring caches the application context between test classes, so it doesn’t restart for every test.
This is one of the biggest optimizations: context startup is the slowest part of integration testing.

How Context Caching Works in Spring Boot Tests
Spring Boot optimizes test execution by caching the application context when possible. This avoids expensive reinitialization and speeds up test suites.

Reusing Application Context using Base class

 // Base class to share context
@SpringBootTest
@Testcontainers
abstract class BaseIntegrationTest {

}

// Concrete test classes extend base class
class UserIntegrationTest extends BaseIntegrationTest {
    // Test methods
}

class OrderIntegrationTest extends BaseIntegrationTest {
    // Test methods
}

Best Practices:

Group tests by profile to maximize reuse.
Use @DirtiesContext only when necessary—it forces context reload.
Avoid unnecessary profile changes unless isolation is required.

Using MockMvc inside @SpringBootTest (mock servlet layer, faster)

You can also inject MockMvc when using @SpringBootTest.
This does not use a real HTTP server but still goes through Spring MVC dispatching.

So with @SpringBootTest, you’re not limited — you can test controllers via MockMvc (mock HTTP) or TestRestTemplate (real HTTP).

Two directions of HTTP in Spring Boot

Inbound HTTP calls → when clients call your service.
- Example: curl http://my-service/api/users/1 hits your controller.
Outbound HTTP calls → when your service calls another service.
- Example: Your UserService calls http://orders-service/api/orders/123.

Which tool is for which direction?

Inbound (your service)

Test /api/users/1 returns JSON.
Use MockMvc (fast, no real server) OR TestRestTemplate (full stack, real HTTP).

Outbound (your service calls another)

@SpringBootTest
class ExternalServiceIntegrationTest {

    private MockWebServer mockWebServer;

    @BeforeEach
    void setUp() throws IOException {
        mockWebServer = new MockWebServer();
        mockWebServer.start();
    }

    @AfterEach
    void tearDown() throws IOException {
        mockWebServer.shutdown();
    }

    @Test
    void shouldHandleExternalServiceResponse() {
        // Given
        mockWebServer.enqueue(new MockResponse()
            .setBody("{\"status\":\"success\"}")
            .addHeader("Content-Type", "application/json"));

        String baseUrl = String.format("http://localhost:%s", mockWebServer.getPort());

        // When
        ExternalServiceResponse response = externalService.callService(baseUrl);

        // Then
        assertThat(response.getStatus()).isEqualTo("success");
    }
}

Here:

Your service thinks it called a real API.
But actually, MockWebServer intercepted and returned your fake response

WireMock for Complex External APIs

WireMock is like a "supercharged" version of MockWebServer.

Testing outbound HTTP calls (your app → external services)
Just like MockWebServer, you don’t want your tests to depend on real APIs.
WireMock lets you stub those APIs so your service thinks it’s calling the real thing.
WireMock shines when the mocked responses are not just static.

@SpringBootTest
class PaymentServiceIntegrationTest {

    @RegisterExtension
    static WireMockExtension wireMock = WireMockExtension.newInstance()
            .options(wireMockConfig().port(8089))
            .build();

    @Test
    void shouldProcessPaymentSuccessfully() {
        // Given
        wireMock.stubFor(post(urlEqualTo("/api/payments"))
            .willReturn(aResponse()
                .withStatus(200)
                .withHeader("Content-Type", "application/json")
                .withBody("{\"transactionId\":\"123\",\"status\":\"approved\"}")));

        // When
        PaymentResult result = paymentService.processPayment(100.0);

        // Then
        assertThat(result.isSuccessful()).isTrue();
        assertThat(result.getTransactionId()).isEqualTo("123");
    }
}

Features WireMock adds (compared to MockWebServer):

Request matching (by URL, headers, body, query params).
Dynamic responses (different responses for same endpoint depending on input).
Fault injection (timeouts, connection reset → great for resilience testing).
Scenarios (simulate stateful APIs, e.g., first call = pending, second call = success).
Recording & playback (record real API responses and replay them).

Rule of thumb:

Use MockWebServer if you just need lightweight static mocks.
Use WireMock when your tests need realistic API simulation (matching, state, errors).

Testing Security

@SpringBootTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class SecurityIntegrationTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void shouldRequireAuthenticationForProtectedEndpoints() {
        ResponseEntity<String> response = restTemplate.getForEntity(
            "/api/users/profile", String.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);
    }

    @Test
    @WithMockUser(roles = "USER")
    void shouldAllowAccessWithValidRole() {
        ResponseEntity<UserProfile> response = restTemplate.getForEntity(
            "/api/users/profile", UserProfile.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

Testing with TestContainers (Database Integration)

What is Test containers ?

It uses Docker containers to spin up temporary instances of real services.
You can use it in JUnit 5, JUnit 4, and Spock tests.
Containers are started before tests and stopped after tests.

Why use Testcontainers?

Mocks and in-memory DBs (like H2) are not 100% identical to real services.
Testcontainers gives you production-like testing environments.
Makes integration tests reliable and closer to reality.

Test with PostgreSQL Container

@SpringBootTest
@Testcontainers
class UserServiceIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
    }

    @Autowired
    private UserService userService;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldPersistUserToDatabase() {
        // Arrange
        CreateUserRequest request = new CreateUserRequest("integration@example.com", "Integration Test");

        // Act
        UserResponse result = userService.createUser(request);

        // Assert
        assertThat(result.getId()).isNotNull();

        Optional<User> savedUser = userRepository.findById(result.getId());
        assertThat(savedUser).isPresent();
        assertThat(savedUser.get().getEmail()).isEqualTo("integration@example.com");
    }
}

Cons:

Docker Dependency- Docker must be installed and running on your machine (or CI/CD runner).
Slower Test Execution
Heavier Resource Usage

Not always necessary (sometimes mocks/in-memory are enough).
When you need confidence that your application works correctly with the real dependencies (DBs, brokers, caches, search engines), Testcontainers is the most reliable way to test.

It hits the sweet spot between:

Mocks/in-memory (too fake → risk of prod bugs).
E2E with full infra (too heavy → slow & fragile).

In short:

If your app depends on anything external (Postgres, Kafka, Redis, etc.), Testcontainers is the best balance of speed, realism, and maintainability.

End-to-End Testing

Purpose

E2E (End-to-End) testing is where you validate the entire Spring Boot application stack, often including databases, messaging, external APIs, and even UI (if applicable). These tests are slower but high value because they simulate production usage.

Integration tests ask: "Do my components work together correctly?"

E2E tests ask: "Does the whole system behave correctly from the outside?"

Best Practices

Test Critical User Journeys: Focus on the most important user workflows that directly impact business value. Don't try to test every possible path through your application.
Use Real Infrastructure: Test against production-like environments with real databases, message queues, and external services when possible.
Implement Proper Setup and Teardown: Ensure tests start with a known state and clean up after themselves. Use database migrations, test data scripts, and proper cleanup procedures.
Handle Asynchronous Operations: Many real applications involve asynchronous processing. Use appropriate waiting strategies and timeouts to handle eventual consistency.
Keep Tests Stable: E2E tests are prone to flakiness. Use robust waiting strategies, proper timeouts, and retry mechanisms for operations that might be timing-dependent.
Run in CI/CD Pipeline: Automate E2E tests as part of your deployment pipeline, but consider running them less frequently than unit and integration tests due to their cost.

Test Only Critical Paths

Don’t aim for 100% E2E coverage — it’s slow, brittle, and expensive.
Focus on happy paths and business-critical flows (e.g., “user signup → email sent → user can log in”).
Leave edge cases to unit/integration tests.

Use Real Dependencies Where Feasible

Prefer Testcontainers for real databases (Postgres, MySQL, Mongo, Kafka, Redis, etc.).
This ensures tests are realistic and not tied to in-memory substitutes like H2 (which can behave differently).

Run on Random Ports

Use webEnvironment = RANDOM_PORT with @SpringBootTest so tests don’t conflict in CI/CD when run in parallel.
Access app endpoints via TestRestTemplate or WebTestClient.

Stub External Services

Don’t hit real third-party APIs in E2E tests.
Use WireMock or MockWebServer to mock external APIs.
This isolates your tests while still simulating realistic HTTP responses.

Scenario

We’re building a user registration flow:
User sends a POST /api/register request.
App stores user in the real database (H2/Postgres via Testcontainers).
App calls an external email service to send a welcome email.
Returns 201 Created if everything succeeds.

Technologies in Test

@SpringBootTest(webEnvironment = RANDOM_PORT) → run full app with real HTTP layer.
TestRestTemplate → to call our real API.
WireMock → mock the external email service.
Testcontainers (optional) → real DB, no mocks.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureWireMock(port = 0) // WireMock on random port
@Testcontainers
class UserRegistrationE2ETest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Container
    static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:15")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("email.api.url", () -> "http://localhost:" + WireMockServerRunner.port());
    }

    @Test
    void shouldRegisterUserAndSendWelcomeEmail() {
        // Stub external Email API
        stubFor(post("/send-email")
                .willReturn(aResponse()
                    .withStatus(200)
                    .withBody("{\"status\":\"sent\"}")));

        // Call real API endpoint
        UserRequest newUser = new UserRequest("alice", "password123", "alice@example.com");
        ResponseEntity<String> response = restTemplate
                .postForEntity("/api/register", newUser, String.class);

        // Assert response
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);

        // Verify Email API was called with expected payload
        verify(postRequestedFor(urlEqualTo("/send-email"))
                .withRequestBody(matchingJsonPath("$.to", equalTo("alice@example.com"))));
    }
}

What This Test Covers

Real HTTP call → TestRestTemplate hits POST /api/register.
Real DB interaction → user stored in Postgres (via Testcontainers).
External dependency → email API is faked by WireMock, so test doesn’t hit the real email server.
End-to-End flow validated → request travels full stack: controller → service → repo → DB → external call → response.

Alternatives to TestRestTemplate

WebTestClient (Reactive-style, but works in Servlet apps too)
- Originally built for Spring WebFlux, but works with Spring MVC too.
- Provides a fluent API that’s easier to chain and assert.
- Can test reactive responses (e.g., streaming JSON).
RestAssured
- A third-party library popular for API testing.
- Syntax is very expressive and close to BDD (Given/When/Then).
- Good for contract tests and multi-service E2E testing.
- Downside: needs app running on a real port (not just mock HTTP layer).

Contract Testing

Purpose

Contract tests ensure that services can communicate correctly by verifying that the producer provides what the consumer expects.

Best Practices

Define Clear Contracts: Establish explicit contracts between services that specify request and response formats, error codes, and behavior expectations.
Test Producer and Consumer Sides: Verify that the service producing data matches the contract, and that consuming services can properly handle the provided data.
Version Your Contracts: When contracts change, ensure backward compatibility or coordinate changes between teams. Use semantic versioning for API changes.
Automate Contract Verification: Run contract tests automatically when either producer or consumer code changes to catch breaking changes early.
Use Schema Validation: Validate that JSON schemas, API specifications, and message formats are correctly implemented by both sides of the contract.

What is Contract Testing?

A way to ensure compatibility between a service provider (e.g., UserService API) and its consumer (e.g., OrderService that calls UserService).

Instead of running heavy E2E tests across multiple services, contract testing verifies:

The provider returns responses that match what the consumer expects.
The consumer sends requests that the provider can understand

Why It’s Needed

Microservices scale problem – E2E tests get slow and brittle as the number of services grows.
Independent deployments – teams should be able to deploy services without waiting on each other.
Shift-left testing – catch breaking API changes early, during CI/CD, before hitting staging or prod.

Use Consumer-Driven Contracts (CDC)

Consumers define expectations, providers validate against them.
Ensures consumers never get surprises after provider changes.

Adopt a Contract Testing Framework

Spring Cloud Contract (most popular in Spring Boot).
Others: Pact (language agnostic, widely adopted).

Keep Contracts in Version Control

Store contracts (JSON/YAML/Groovy DSL) in the same repo as the provider OR shared contract repo.
Use them in CI/CD pipelines.

Version Your Contracts

Treat them like APIs. Breaking changes should follow semantic versioning.

Real example of Pact contract testing with Spring Boot

Imagine a retail platform with microservices:

Order Service (Consumer) → Places an order, needs user details.
User Service (Provider) → Manages users, exposes /api/users/{id}.
Pact Broker → Central hub where contract files are shared

Pact Test (Consumer-Driven Contract)

@ExtendWith(PactConsumerTestExt.class)
public class OrderServicePactTest {

    @Pact(consumer = "order-service", provider = "user-service")
    public RequestResponsePact createPact(PactDslWithProvider builder) {
        return builder
            .given("User with ID 100 exists")
            .uponReceiving("Request to fetch user 100")
                .path("/api/users/100")
                .method("GET")
            .willRespondWith()
                .status(200)
                .headers(Map.of("Content-Type", "application/json"))
                .body("{\"id\":100,\"name\":\"Alice\"}")
            .toPact();
    }

    @Test
    void verifyUserApi(MockServer mockServer) throws IOException {
        URL url = new URL(mockServer.getUrl() + "/api/users/100");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");

        String response = new BufferedReader(new InputStreamReader(conn.getInputStream()))
                .lines().collect(Collectors.joining("\n"));

        assertTrue(response.contains("Alice"));
    }
}

This generates a Pact contract:
order-service-user-service.json

Defines request expectations (path, method, headers).
Defines response expectations (status, JSON body).

Industry Practice

Pact file is automatically uploaded to a Pact Broker via CI (GitHub Actions, Jenkins, GitLab).

Provider Side (User Service)

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Provider("user-service")
@PactBroker(host = "pact-broker.mycompany.com", port = "80")
public class UserServiceContractTest {

    @LocalServerPort
    private int port;

    @BeforeEach
    void setup(PactVerificationContext context) {
        context.setTarget(new HttpTestTarget("localhost", port));
    }

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void verifyPacts(PactVerificationContext context) {
        context.verifyInteraction();
    }
}

This does not use a mock server. It runs against the real Spring Boot app and verifies:

API paths
Request/response schema
Status codes

If provider response changes (e.g., name → fullName), the verification fails → contract broken.

CI/CD Flow

🔹 Consumer pipeline (Order Service)

Run Pact tests → generate pact file.
Publish pact to Pact Broker.
Tag it with branch/environment (dev, staging, prod).

🔹 Provider pipeline (User Service)

Fetch contract from Pact Broker.
Run Pact verification tests against real app.
If passes ✅ → Provider can be deployed.
If fails ❌ → Provider cannot break consumer expectations.

References & Credits

AI tools were used to assist in research and writing but final content was reviewed and verified by the author.

Parking Lot System Design (LLD in Action)

AnkitDevCode — Sun, 31 Aug 2025 15:21:15 +0000

What is Low-Level Design (LLD)?

Low-Level Design (LLD) is the process of translating High-Level Design (HLD) into concrete implementation (like class diagrams, interfaces, object relationships, and design patterns) that can be directly implemented in code.

Core Components of LLD

You can find a more in-depth information of this concept in my earlier post Object-oriented programming System(OOPs)

Classes and Objects
Interfaces and Abstractions
Relationships Between Classes

Key Considerations for LLD

Scope & Requirements
Clear Data Models
Core Design Principles (SOLID & Beyond)
System Robustness & Scalability
Design Patterns & Reusability

Common Pitfalls to Avoid

God classes that handle too many responsibilities.
Inconsistent Data Models
Overuse of inheritance, leading to fragile hierarchies.
Ignoring non-functional requirements until it’s too late.
Overengineering: Don’t use complex patterns unless justified—keep it lean.

Parking Lot System

Problem Statement

Design a parking lot management system for a multi-story parking garage that can handle different types of vehicles, dynamic pricing, real-time availability tracking.

Focus: Low-Level Design (LLD), Object-Oriented Programming, System Architecture

Essential Questions to Ask:

What types of vehicles should the system support?
How many floors will the parking lot have?
What are the different parking spot sizes?
How should pricing work - hourly, flat rate, or both?
Do we need real-time availability tracking?
Should the system handle reservations?
What payment methods are supported?
Do we need administrative features?

❌ Red Flags - Poor Requirements Gathering

Jumping straight to code without understanding requirements
Making assumptions without asking questions
Not clarifying scope - building too much or too little
Ignoring edge cases early in the discussion

How to approach the problem statement ?

When approaching system design, there are two common strategies:

Top-down approach → Start with the big picture. Break the larger problem into smaller, manageable parts, and then continue refining each part step by step.

Recommended during the analysis and design phase.
Starts with the big picture of the system.
Breaks the system into smaller, manageable sub-systems step by step.
Focus is on defining responsibilities and interactions at higher levels before going into details.
Useful for requirements gathering and system architecture design.

Bottom-up approach → Start small. Focus first on solving the smaller, individual problems, and then integrate them together to form the complete solution.

Recommended during the implementation phase.
Uses structure diagrams (e.g., class diagrams) to represent system components.
Focuses on breaking the problem statement into smaller components without deep details initially.
Behavior diagrams (e.g., sequence diagrams) are used alongside to show how the system functions overall.
Helps in understanding both the structure and the functionality of the system in its early stages.

Good Approach - Identify Core Components

+---------------------+       1..* +---------------------+       1..* +---------------------+
|      ParkingLot     |<>----------|    ParkingFloor     |<>----------|    ParkingSpot      |
+---------------------+            +---------------------+            +---------------------+
| - id: String        |            | - floorNumber: int  |            | - spotId: String    |
| - levels: List      |            | - spots: Map        |            | - isOccupied: bool  |
| - gates: Map        |            | - freeSpots: Map    |            | - vehicle: Vehicle  |
| - tickets: Map      |            +---------------------+            | - type: SpotType    |
+---------------------+            | + findSpot(vType)   |            +---------------------+
| + parkVehicle()     |            | + parkVehicle(v)    |                  |
| + unparkVehicle()   |            | + unparkVehicle(t)  |                  | 1
| + processPayment()  |            | + getFreeSpots()    |                  |
+---------------------+            | + notifyObserver()  |                  |
                                   +---------------------+                  |
                                                                            | 1..*
+-----------------+     +-----------------+     +-----------------+         |
|      Vehicle    |     |   ParkingTicket |     |      Payment    |         |
+-----------------+     +-----------------+     +-----------------+         |
| - license: String |   | - ticketId: int |     | - amount: double|         |
| - type: VehicleType | | - entryTime: Date |   | - method: String|         |
+-----------------+     | - spot: ParkingSpot|  | - status: String|         |
| + getType()     |     +-----------------+     +-----------------+         |
+-----------------+     | + getDuration() |                                 |
                        +-----------------+                                 |
                                                                            |
                                                                            |
                                                                            |
+------------------+     +-----------------------+                          |
|   PaymentProcessor|<-----|  DefaultPaymentProcessor|                      |
+------------------+     +-----------------------+                          |
| + process() |                                                             |
+------------------+                                                        |
                                                                            |
+------------------+     +-----------------------+                          |
|   PricingStrategy|<-----|  HourlyPricingStrategy|                         |
+------------------+     +-----------------------+                          |
| + calculateFee() |                                                        |
+------------------+                                                        |
                                                                            |
+------------------+                                                        |
|  ParkingObserver |<------------------------------------------------------+
+------------------+
| + update()       |
+------------------+

Parking Lot LLD – Component Summary

1. ParkingLot

The central manager of the entire parking system.

Responsibilities:

Keeps track of multiple floors.
Handles parking and unparking.
Interacts with Payment and PricingStrategy.

Key Methods:

parkVehicle(vehicle): Finds an available spot and issues a ParkingTicket
unparkVehicle(ticket): Frees the spot and processes payment
processPayment(ticket, paymentMethod): Calculates fee and completes payment

2. ParkingFloor

Manages spots on a single floor.

Responsibilities:

Keeps track of all parking spots on the floor.
Notifies observers when a spot becomes occupied or free.

Key Methods:

notifyObserver(): Updates DisplayBoard or other systems
getAvailableSpot(vehicleType): Returns a free spot suitable for the vehicle

3. ParkingSpot

Represents a single parking slot.

Attributes:

spotNumber, spotType (COMPACT, LARGE, ELECTRIC, HANDICAPPED), isOccupied, vehicle

Methods:

assignVehicle(vehicle)
removeVehicle()
isOccupied()

4. ParkingTicket

Tracks a vehicle’s parking session.

Attributes:

ticketId, vehicle, spot, entryTime, exitTime

Methods:

getDuration(): Time elapsed since entry

5. Payment

Handles payment processing.

Attributes:

amount, method (CASH, CARD), status (PENDING, COMPLETED)

Methods:

process(): Completes the payment

6. PricingStrategy

Defines how fees are calculated.

calculateFee(duration): returns fee

Example Implementation:

HourlyPricingStrategy, FlatRatePricingStrategy

7. ParkingObserver

Used to update displays or other systems when a spot changes.

update(): Called when spot becomes free/occupied

Example: DisplayBoard implements ParkingObserver to show available spots.

UML Diagram Analysis - Parking Lot System

The UML class diagram illustrates a comprehensive parking lot management system that demonstrates multiple design patterns and object-oriented principles. Let me break down each section:

Please find full diagram on kroki

Class Structure:

Vehicle (Abstract)
├── Motorcycle
├── Car  
├── Truck
└── ElectricCar

UML Relationships Explained:

Inheritance (Generalization) - Solid Line with Empty Triangle:

Vehicle <|-- Motorcycle
Vehicle <|-- Car
Vehicle <|-- Truck
Vehicle <|-- ElectricCar

Composition and Aggregation Relationships

Strong Composition (Filled Diamond):

ParkingLot "has many" ParkingFloor
ParkingFloor "has many" ParkingSpot
ParkingSpot "has one" Vehicle

ParkingLot "1" *-- "many" ParkingFloor
ParkingFloor "1" *-- "many" ParkingSpot

Meaning:

Parking floors cannot exist without the parking lot
Parking spots cannot exist without their floor
Lifecycle dependency: Child objects destroyed when parent is destroyed

Weak Aggregation (Empty Diamond):

ParkingLot "1" o-- "many" ParkingObserver

Meaning:

Observers can exist independently of the parking lot
Loose coupling: Observers can be shared across multiple parking lots

Simple Association (Solid Line):

ParkingSpot --> Vehicle : parkedVehicle
ParkingTicket --> ParkingSpot
ParkingTicket --> Payment

Meaning:

Objects reference each other but are independent
Temporary relationships: Vehicle can move to different spots

Design Pattern Implementations

Strategy Pattern:

PricingStrategy (Interface)
├── HourlyPricingStrategy
└── FlatRatePricingStrategy

UML Notation

PricingStrategy <|.. HourlyPricingStrategy
PricingStrategy <|.. FlatRatePricingStrategy

Interface implementation relationship
Enables runtime strategy switching
Open/Closed Principle: Add new strategies without modifying existing code

Observer Pattern:

Relationship: ParkingLot "1" o-- "many" ParkingObserver

Loose coupling: ParkingLot doesn't know concrete observer types
Event-driven: Automatic notifications on state changes

Factory Pattern:

Factory creates Vehicle instances but doesn't store references
Encapsulates creation logic: Hides vehicle instantiation complexity

Singleton Pattern:

Single instance guarantee: Only one parking lot can exist
Global access point: Available throughout the application

Builder Pattern:

Purpose: Constructs complex ParkingLot objects step by step

Fluent interface: Method chaining for easy configuration
Complex construction: Handles multi-floor setup with different spot types

Key Relationships Analysis

1. Vehicle ↔ ParkingSpot Interaction

Bidirectional relationship: Each knows about the other when parked
Validation logic: Vehicle determines if it can fit in spot

2. ParkingLot as Central Coordinator

Hub pattern: Central point for all parking operations
Dependency injection: Strategy and observers injected at runtime

Interface vs Abstract Class Decisions

Interfaces Used:

PricingStrategy: Behavior-only contract (no shared data)
ParkingObserver: Event handling contract (no shared implementation)

Abstract Classes Used:

Vehicle: Shared data (licensePlate, color) + abstract behavior

Decision Criteria:

Interface when: Pure behavior contract, no shared data
Abstract class when: Shared data + some abstract behaviors

Encapsulation and Access Modifiers

Field Visibility Patterns:

Private Fields (-):

All internal state in ParkingSpot, Payment, ParkingTicket
Information hiding: Implementation details not exposed

Protected Fields (#):

Vehicle class fields accessible to subclasses
Inheritance support: Subclasses can access parent data

Public Methods (+):

All service methods and getters
Clear API: Well-defined public interface

Thread Safety Considerations

ReentrantLock Usage:

ParkingSpot has individual locks for fine-grained control
ParkingFloor has floor-level locks for coordination
ParkingLot has system-wide locks for complex operations

Thread-Safe Collections:

Maps shown as ConcurrentHashMap implementations
Concurrent access: Multiple threads can safely access shared data

🧩 LLD Implementation

What You’ll Find in the Repository - ParkingLot implementation

All core components, including:
Vehicle and its subclasses (e.g., Car, Bike, Truck)
ParkingSpot, ParkingFloor
ParkingTicket
PricingStrategy with a sample HourlyPricingStrategy
Payment
PaymentProcessor
ParkingLot as the central controller
Basic Observer pattern implementation with ParkingObserver and DisplayBoard
Simple and clean code, designed to be easy to understand and extend for beginners.
README documentation that explains how to set up, run the project, and test the functionality.

📌 Note
This repository is a work in progress. The current design and implementation may have some limitations or areas that can be improved. I will continue to update and optimize the design over time to make it more robust and extensible.

For now, consider this as a good starting point to understand the Parking Lot LLD in Java. It demonstrates the core concepts and relationships clearly, while leaving room for enhancements and refinements.

Summary: Good vs Bad Approaches

✅ What Makes This Solution Strong:

Clear Separation of Concerns: Each class has a single responsibility
Proper Abstraction: Abstract classes and interfaces used appropriately
Thread Safety: Comprehensive concurrency handling
Design Patterns: Multiple patterns used correctly (Strategy, Factory, Singleton, Observer)
Extensibility: Easy to add new features without breaking existing code
Error Handling: Graceful handling of edge cases
Type Safety: Enums prevent invalid states and types

🚩 Common Red Flags to Avoid:

God Class Anti-pattern: Single class doing everything
Primitive Obsession: Using strings/ints instead of proper types
No Thread Safety: Ignoring concurrent access issues
Tight Coupling: Classes knowing too much about each other
No Error Handling: Not handling edge cases
Hard-coded Values: No flexibility for configuration
Missing Abstractions: Not using inheritance where appropriate
Poor Naming: Unclear or misleading class/method names

References & Credits

AI tools were used to assist in research and writing but final content was reviewed and verified by the author.

Transactions : Explained

AnkitDevCode — Wed, 27 Aug 2025 15:27:54 +0000

What is a transaction?

A transaction defines a logical unit of work that either completely succeeds or produces no result at all. There are two types of transactions - local and distributed transaction.

Why we need transaction management?

A database transaction, by definition, must be atomic. In order to maintain consistency in a database, before and after the transaction, few properties are followed. These are called ACID properties.

Atomicity- It ensures that either all or none of the operations needs to be performed.
Consistency- It ensures that either all operations are rolled back and set to the state back from where the transaction was started or the changes were successfully made and reflected.
Isolation- It ensures that transactions performed are only reflected after a commit.
Durability- It ensures that the committed transactions are persisted.

What are Transactional databases?

A transactional database is a DBMS that provides the ACID properties. Not having ACID properties means that the database works well on clusters because they are horizontally scalable. NoSQL follows a model known as the BASE (Basically Available, Soft state, Eventual consistency).

Types of Transactions

Local Transaction
Distributed Transaction

1. Local Transaction:

Local transactions are those that affect only one transaction resource.

JDBC API is auto-commit by default. To enable the transaction, set auto-commit to false. Transactions are managed at the connection level.

Local transaction in hibernate
In hibernate, a transaction is associated with a Session and is usually instantiated by a call to Session.beginTransaction(). A single session might span multiple transactions. However, it is intended that there be at most one uncommitted Transaction associated with a particular Session at any time.

Local transaction in spring

Spring declarative transaction model uses AOP proxy. in spring by default propagation level is REQUIRED which means the inner transaction will be part of the same outer transaction, hence if the inner transaction fails the whole transaction will get rollback. it's important to know that Rollback works for only Runtime exceptions by default. For checked Exceptions, we have to specify that explicitly @Transcational(rollbackFor = Exception.class) Mixing the database I/O with other types of I/O like web service call , in a transactional context is a code smell and may lead to connection exhaust.

Note : Spring supports distributed JTA transactions across multiple XA resources by using Transaction Manager like Atomikos, JBossTS or Bitronix etc. JTA transactions are also supported when deploying to a suitable Java EE Application Server. we will cover it in distributed transaction section.

GitHub repo link

Before getting into the distributed transactions details, let's understand JTA-

JTA (Java transaction API) :
JTA defines a high-level transaction management interface intended for resource managers and transactional applications in DTP (distributed transaction processing) environments.

It allows applications to perform distributed transactions, that is, transactions that access and update data on two or more networked computer resources. The JTA specifies standard Java interfaces between a transaction manager and the parties involved in a distributed transaction system.

1-UserTransaction— The javax.transaction.UserTransaction interface provides the application the ability to control transaction boundaries programmatically.

2—Transaction Manager— The javax.transaction.TransactionManager interface allows the application server to control transaction boundaries on behalf of the application being managed.

3—XAResource—The javax.transaction.xa.XAResource interface is a Java mapping of the industry standard XA interface based on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).

XA Protocol :
The XA interface specifies communication between a transaction manager (TM) and a resource manager (RM). To communicate with the transactional resources, the transaction monitor must speak a common protocol with transactional resources. Usually, this protocol is a specification called XA.

Note : Java EE application servers support JTA out of the box, and there are third party, standalone implementations of JTA that you can use to avoid being trapped on a Java EE application server.

2. Distributed Transaction:

Global transactions are those that span one or more transactional resources, and enlist them all in a single transaction. Therefore, it must be coordinated among those resources.

There are two popular approaches for distributed transactions:
Two Phase Commit Protocol and Eventual Consistency and Compensation also known as Saga pattern.

Problem :
In a monolithic system, we have a database system to ensure ACID properties. however, The microservice-based system does not have a global transaction coordinator by default. how do we manage transaction in micro service architecture?

Possible solutions:

1.Two-Phase Commit Protocol

This mechanism is designed initially for distributed systems. 2pc is widely used in database systems. As Microservices architecture inherently distributed systems in nature, we can use the Two-phase commit protocol (or 2PC) as one of the approaches. Primary drivers in a distributed transaction management are the message broker/transaction coordinator.

The distributed transaction contains two steps:

Prepare phase

Commit or Rollback phase
Prepare Phase:

All the participants of a transaction in this phase will be prepared for the commit and inform the transaction coordinator/message broker that they are ready for completing the transaction. it guarantee that the transaction is atomic.

Commit or Rollback phase:

In this phase, transaction coordinator will issue one of the commands they are a commit or a rollback to all the participants.

Benefits of using 2pc

2pc is a very strong consistency protocol and mainly used in DBMS system.
2pc allows read-write isolation. This means the changes on a field are not visible until the coordinator commits the changes.

Disadvantages of using 2pc

The main issue with the 2PC approach is that it is a bit slow compared to the time for the operation on a single Microservice because it has to coordinate the transaction between services even if all the microservices are on the same network, still operation will be slow. So we need to be careful while implementing this for high demand services.
It is not really recommended for many microservice-based systems because 2pc is synchronous (blocking).
Requires remote communication to each participating system.
Requires each participating system to support two-phase commit.

2. Eventual Consistency and Compensation (SAGA)

Eventual Consistency can be achieved by sagas. SAGA is one of the best way to ensure the consistency of the data in a distributed architecture without having a single ACID transaction. it maintains consistency (but not atomicity) across multiple services without requiring a transaction manager system.. A series of local transactions is SAGA. Saga pattern is an alternative to XA when resources are not XA capable or XA is undesired

Advantages of SAGA

Maintains consistency (but not atomicity) across multiple services without requiring a transaction manager system.
Uses a sequence of local TXs
Failure of a local TX executes a series of compensating transactions to undo the previous successful TXs

There are two types of sagas:

Choreography : each local transaction publishes domain events that trigger local transactions in other services.
Orchestration : an orchestrator (object) tells the participants what local transactions to execute.

Choreography-Based Saga
In this approach, there is no central orchestrator. Each service participating in the Saga performs their transaction and publish events. The other services act upon those events and perform their transactions. Also, they may or not publish other events based on the situation.

Orchestration-Based Saga
In this approach, there is a Saga orchestrator that manages all the transactions and directs the participant services to execute local transactions based on events. This orchestrator can also be though of as a Saga Manager.

Summary of advanced topics in distributed transactions

CAP Theorem – trade-offs between consistency, availability, partition tolerance.
Two-Phase Commit (2PC) – classic XA transactions, but heavy & blocking.
Saga Pattern – break into steps with compensating actions (choreography/orchestration).
TCC (Try-Confirm-Cancel) – reserve → confirm → cancel, used in payments.
Idempotency & Retries – ensure safe retries in distributed systems.
Consensus Protocols – Paxos, Raft, ZAB for agreement in clusters.
Distributed Locking – Redis RedLock, ZooKeeper, DB locks.
Modern Tools – Seata, Temporal.io, Camunda, Kafka transactions.

Getting Started with PL/SQL Blocks and Calling Them from Spring Boot JPA

AnkitDevCode — Wed, 27 Aug 2025 14:57:14 +0000

Prerequisites

Before we begin, here are the requirements for following along with this guide:

Database: Oracle Database (since PL/SQL is Oracle-specific).

The syntax, examples, and stored procedures/functions in this tutorial are based on Oracle PL/SQL only.

Other databases (e.g., MySQL, PostgreSQL) have different procedural languages and syntax.

Introduction

PL/SQL (Procedural Language / SQL) is Oracle’s extension of SQL.
It adds programming features (like loops, conditions, procedures, and error handling) on top of SQL. It allows you to combine SQL statements with procedural logic.

PL/SQL Block

A block is a basic unit of code (procedures, functions, and anonymous blocks) that make up the PL/SQL program logical. A PL/SQL block includes three sections: declaration, executable, and exception-handling sections. The executable section is mandatory, while others are optional.

Types of PL/SQL Blocks

Anonymous Blocks
- Not stored in the database.
- Written and executed directly (like test scripts).
Named Blocks
- Stored in the database for reuse.
- Examples: Procedures, Functions, Packages, Triggers.

An anonymous block

A block without a name is an anonymous block. An anonymous block is not saved in the Oracle Database server, so it is just for one-time use. However, PL/SQL anonymous blocks can be useful for testing purposes.

Example

SET SERVEROUTPUT ON;
declare
p_emp table_emp%rowtype;
begin
select * into p_emp from table_emp where emp_id='123456';  
dbms_output.put_line('Result:'|| p_emp.name || p_emp.emp_id);
exception
when NO_DATA_FOUND
then 
dbms_output.put_line('No Result:');
end;

/
The slash (/) executes the block.

Functions or Procedures (named Block)

Functions or Procedures is an example of a named block. A named block is stored in the Oracle Database server and can be reused later.

Create Procedure Example

create or replace procedure getEmpById(id in varchar2)    
AS 
p_emp table_emp%rowtype;
begin    
select * into p_emp from table_emp where emp_id=id;  
dbms_output.put_line('Result:'|| p_emp.name || p_emp.emp_id);
end ;

Execute procedure

begin
getEmpById('12345');
end;

exec getEmpById('12345');

Delete procedure

drop procedure getEmpById;

Create Function Example

 create or replace function getEmpById(id in varchar2) 
   return varchar2 
   IS
   p_name varchar2(255);
   begin 
     select name into p_name from table_emp where emp_id=id;  
      return(p_name); 
    end;

Execute function

select getEmpById('123456') from dual;

declare
num number := &emp_id;
e_name varchar2(255);
begin
e_name := getEmpById(num);
 dbms_output.put_line('the employee name '|| e_name);
end;
/

Delete function

drop function getEmpById;

Calling a Stored Procedure with Spring Data JPA

Stored procedures with Spring Data JPA (or any framework) come with pros and cons. Here’s a balanced view:

@Procedure Annotation

public interface EmployeeRepository extends JpaRepository<Employee, Long> {

    @Procedure(procedureName = "increase_salary")
    void increaseSalary(@Param("p_emp_id") Long empId, @Param("p_percent") Double percent);
}

@NamedStoredProcedureQuery

@Entity
@NamedStoredProcedureQuery(
    name = "Employee.increaseSalary",
    procedureName = "increase_salary",
    parameters = {
        @StoredProcedureParameter(mode = ParameterMode.IN, name = "p_emp_id", type = Long.class),
        @StoredProcedureParameter(mode = ParameterMode.IN, name = "p_percent", type = Double.class)
    }
)
public class Employee {
    @Id
    private Long empId;
    private String name;
}

Repository:

public interface EmployeeRepository extends JpaRepository<Employee, Long> {
    @Procedure(name = "Employee.increaseSalary")
    void increaseSalary(@Param("p_emp_id") Long empId, @Param("p_percent") Double percent);
}

Main Use Cases of PL/SQL Blocks

Data Processing – update/modify data in bulk.
Business Logic & Validation – enforce rules beyond SQL constraints.
Error Handling – gracefully manage runtime errors.
Automation via triggers – run logic on INSERT/UPDATE/DELETE.
Reusable Code – stored procedures & functions.
Batch Jobs & Scheduling – cleanup, reporting, automation tasks.
Complex Transactions – ensure atomic operations (commit/rollback).

Rule of thumb:

Use stored procedures for heavy DB operations, bulk processing, and centralized business rules.
Use JPA queries for simple, CRUD-like operations and portability.

[Boost]

AnkitDevCode — Tue, 26 Aug 2025 18:22:35 +0000

Observability Part 2 – Metrics & Dashboards with Prometheus and Grafana - DEV Community

Introduction Quick recap of previous article: Showed how to use OpenTelemetry &...

dev.to

DEV Community: AnkitDevCode

JPA Mapping with Hibernate- Many-to-Many Relationship

Table of Contents

1. Introduction

2. The Relational Model Behind @ManyToMany

3. Unidirectional @ManyToMany — Simplest Form

3.1 Mapping

4. Bidirectional @ManyToMany

4.1 Mapping

4.2 Keeping Both Sides in Sync

5. equals() and hashCode() — The Critical Foundation

5.1 Correct Implementation (Business Key or UUID)

6. Intermediate Entity for Join Table With Extra Columns

6.1 Composite Key Class

6.2 Enrollment (Intermediate) Entity

6.3 Parent Entities

7. Fetch Strategies & The N+1 Problem

7.1 Always Use LAZY — Never EAGER

7.2 Solving N+1 With JOIN FETCH

7.3 Using @BatchSize as a Middle Ground

8. Cascade Types — What to Use and When

8.1 Recommended Cascade Matrix

9. Serialization — Avoiding Infinite Recursion

9.1 Jackson Annotations

9.2 Better: Use DTOs (Recommended)

10. Performance Best Practices

10.1 Projections and DTO Queries

10.2 Pagination — Never Paginate With JOIN FETCH

10.3 Use @Transactional on Service, Not Repository

11. Quick Reference — Best Practices vs Pitfalls

12. Conclusion

JPA Mapping with Hibernate- One-to-Many and Many-to-One Relationship

Table of Contents

1. What Are These Relationships?

Key Terminology

Database Representation

2. Setting Up a Bidirectional Relationship

The Parent (One Side)

The Child (Many Side)

3. Unidirectional @OneToMany — Avoid It

4. Best Practices

1. Always Use Lazy Fetching

2. Use List Instead of Set

3. Keep Both Sides in Sync

4. Use orphanRemoval for Parent-Owned Children

5. Never Cascade on @ManyToOne

6. Override equals and hashCode

5. Common Pitfalls

The N+1 Query Problem

LazyInitializationException

Out-of-Sync Bidirectional State

CascadeType.REMOVE + orphanRemoval Redundancy

6. Cascade Types Reference

7. Quick Reference Table

8. Summary

Code

JPA Mapping with Hibernate-One-to-One Relationship

Table of Contents

1. What is JPA?

2. What is Hibernate?

3. JPA vs Hibernate — Key Differences

4. Relationship Mapping in JPA — Quick Reference

5. What is a One-to-One Relationship?

Unidirectional vs Bidirectional

How to Identify Owner, FK Side, and Child

JPA Annotation Summary

6. Bidirectional One-to-One — Standard Mapping

The Child Entity (Owning Side)

The Parent Entity (Inverse Side)

7. The Lazy Loading Problem on the Inverse Side

Why the Extra Query Fires

8. Solutions to the Inverse-Side Probe Query

Option 1 — @LazyToOne Bytecode Instrumentation

Option 2 — JOIN FETCH Query

Option 3 — @NamedEntityGraph

Option 4 — @MapsId Shared Primary Key (Best & Simplest)

9. Deep Dive — @MapsId

Key Differences Per Entity

Advantages of @MapsId

Downsides of @MapsId

2. Use `List` Instead of `Set`

4. Use `orphanRemoval` for Parent-Owned Children

5. Never Cascade on `@ManyToOne`

6. Override `equals` and `hashCode`

`LazyInitializationException`

`CascadeType.REMOVE` + `orphanRemoval` Redundancy

What `virtual-threads-enabled: true` Actually Does in Spring

`synchronized` pins carrier threads