One-to-Many and Many-to-Many in Hibernate

package io.thecodeforge.entities;

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;

/**
 * io.thecodeforge — One-to-Many Bidirectional Mapping
 *
 * Author is the inverse side of the Author <-> Book relationship.
 * mappedBy = "author" tells Hibernate: "the 'author' field on the Book entity
 * owns this relationship — look there for the FK column, not here."
 *
 * Author never writes to the database based on its 'books' collection.
 * Book writes to the 'author_id' column based on its 'author' field.
 *
 * Key design decisions:
 *   - FetchType.LAZY: books are loaded on demand, not on every Author query
 *   - CascadeType.ALL: safe here because Book's lifecycle depends on Author
 *   - orphanRemoval = true: removing a Book from the collection deletes the row
 *   - Helper methods: the ONLY correct way to update this relationship in memory
 */
@Entity
@Table(name = "forge_authors")
public class Author {

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

    @Column(nullable = false)
    private String name;

    // mappedBy = "author" — this field is the INVERSE side
    // Hibernate ignores this collection during flush; the Book.author field drives the FK
    @OneToMany(
        mappedBy = "author",
        cascade = CascadeType.ALL,
        orphanRemoval = true,
        fetch = FetchType.LAZY
    )
    private List<Book> books = new ArrayList<>();

    /**
     * Helper method: the correct way to add a Book to an Author.
     *
     * You MUST call book.setAuthor(this) — otherwise the owning side (Book.author)
     * is never updated, and Hibernate generates no SQL to set author_id.
     * In-memory, the Author's books collection looks correct. In the database,
     * the books.author_id column is NULL. The bug is invisible until the session flushes.
     *
     * Always manage both sides. Always use the helper method. Never call
     * books.add(book) directly from outside the entity.
     */
    public void addBook(Book book) {
        books.add(book);
        book.setAuthor(this);
    }

    public void removeBook(Book book) {
        books.remove(book);
        book.setAuthor(null);
    }

    // Standard getters and setters omitted for brevity
    public Long getId() { return id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public List<Book> getBooks() { return books; }
}


/**
 * Book is the OWNING side of the Author <-> Book relationship.
 * The @JoinColumn annotation here defines the actual FK column name
 * in the forge_books table that Hibernate reads and writes.
 *
 * When book.setAuthor(author) is called, Hibernate will UPDATE
 * forge_books SET author_id = ? WHERE id = ?  at flush time.
 */
@Entity
@Table(name = "forge_books")
class Book {

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

    @Column(nullable = false)
    private String title;

    // OWNING SIDE — this field controls the author_id column in forge_books
    // @JoinColumn is optional here; without it Hibernate derives the column name
    // from the field name (author_id). Explicit is better in production code.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "author_id", nullable = false)
    private Author author;

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public Author getAuthor() { return author; }
    public void setAuthor(Author author) { this.author = author; }
}

/*
 * Hibernate DDL output:
 *
 * CREATE TABLE forge_authors (
 *   id      BIGINT NOT NULL AUTO_INCREMENT,
 *   name    VARCHAR(255) NOT NULL,
 *   PRIMARY KEY (id)
 * );
 *
 * CREATE TABLE forge_books (
 *   id        BIGINT NOT NULL AUTO_INCREMENT,
 *   title     VARCHAR(255) NOT NULL,
 *   author_id BIGINT NOT NULL,
 *   PRIMARY KEY (id),
 *   FOREIGN KEY (author_id) REFERENCES forge_authors(id)
 * );
 *
 * Note: no FK column on forge_authors — Author is the inverse side.
 * The entire relationship lives in the forge_books.author_id column.
 */

package io.thecodeforge.entities;

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Objects;
import java.util.Set;

/**
 * io.thecodeforge — Many-to-Many Mapping with Production-Grade Safeguards
 *
 * Student is the OWNING side — it defines the @JoinTable.
 * Course is the INVERSE side — it uses mappedBy = "courses".
 *
 * Key decisions and their justifications:
 *
 * 1. Set<Course> not List<Course>
 *    List triggers delete-all-reinsert on every update.
 *    Set enables targeted INSERT/DELETE via equals/hashCode.
 *
 * 2. CascadeType.PERSIST + CascadeType.MERGE only — no REMOVE, no ALL
 *    PERSIST: saving a new Student with new Courses saves the Courses too.
 *    MERGE: merging a detached Student also merges its Courses.
 *    REMOVE is excluded: deleting a Student must NOT delete the Courses.
 *    Courses are shared entities — their lifecycle is independent of any Student.
 *
 * 3. equals/hashCode based on entity ID
 *    Using getClass().hashCode() as the base ensures subclass safety.
 *    Null check on ID handles transient (pre-persist) entities correctly.
 *    Without this, Set<Course> cannot detect that two Course instances
 *    loaded from different sessions represent the same database row.
 */
@Entity
@Table(name = "forge_students")
public class Student {

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

    @Column(nullable = false)
    private String name;

    @ManyToMany(
        cascade = {CascadeType.PERSIST, CascadeType.MERGE},
        fetch = FetchType.LAZY
    )
    @JoinTable(
        name = "forge_student_courses",
        joinColumns = @JoinColumn(name = "student_id"),
        inverseJoinColumns = @JoinColumn(name = "course_id")
    )
    private Set<Course> courses = new HashSet<>();

    /**
     * Enrollment helper — updates both sides of the relationship.
     *
     * course.getStudents().add(this) keeps the inverse side in sync
     * for the duration of this session. Without it, reading
     * course.getStudents() in the same transaction returns stale data
     * that does not include this student.
     *
     * Note: only Student.courses drives SQL (owning side).
     * Course.students is a navigational convenience — Hibernate ignores it at flush.
     */
    public void enrollIn(Course course) {
        this.courses.add(course);
        course.getStudents().add(this);
    }

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

    /**
     * equals/hashCode based on entity ID.
     *
     * Why id != null check matters:
     *   A transient (new) entity before persist has id = null.
     *   Two different new Student instances would both have id = null
     *   and would be considered equal — incorrect for a Set.
     *   The id != null guard ensures transient entities use reference equality
     *   until they are assigned an ID by the database.
     *
     * Why getClass().hashCode() and not Objects.hash(id):
     *   hashCode must be stable — it cannot change after an object is added to a Set.
     *   If we used Objects.hash(id), a transient entity has hashCode(null),
     *   then after persist the hashCode changes to hashCode(generatedId).
     *   The entity is now lost in the Set — it is stored in the wrong bucket.
     *   getClass().hashCode() is constant for all instances of the same class,
     *   which is safe even if the ID changes from null to a value.
     */
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Student other)) return false;
        return id != null && id.equals(other.id);
    }

    @Override
    public int hashCode() {
        // Constant per class — safe across ID assignment for transient entities
        return getClass().hashCode();
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public Set<Course> getCourses() { return courses; }
}


@Entity
@Table(name = "forge_courses")
class Course {

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

    @Column(nullable = false)
    private String title;

    // INVERSE side — mappedBy = "courses" means Student.courses owns the join table
    // Hibernate ignores this collection at flush time — it is for navigation only
    @ManyToMany(mappedBy = "courses")
    private Set<Student> students = new HashSet<>();

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

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

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public Set<Student> getStudents() { return students; }
}

/*
 * Hibernate DDL output:
 *
 * CREATE TABLE forge_students (
 *   id   BIGINT NOT NULL AUTO_INCREMENT,
 *   name VARCHAR(255) NOT NULL,
 *   PRIMARY KEY (id)
 * );
 *
 * CREATE TABLE forge_courses (
 *   id    BIGINT NOT NULL AUTO_INCREMENT,
 *   title VARCHAR(255) NOT NULL,
 *   PRIMARY KEY (id)
 * );
 *
 * CREATE TABLE forge_student_courses (
 *   student_id BIGINT NOT NULL,
 *   course_id  BIGINT NOT NULL,
 *   PRIMARY KEY (student_id, course_id),  -- composite PK prevents duplicate enrollments
 *   FOREIGN KEY (student_id) REFERENCES forge_students(id),
 *   FOREIGN KEY (course_id)  REFERENCES forge_courses(id)
 * );
 *
 * SQL behavior comparison — Student with 500 enrollments, adding 1 new Course:
 *
 *   With List<Course>:
 *     DELETE FROM forge_student_courses WHERE student_id = 42  -- 500 rows deleted
 *     INSERT INTO forge_student_courses (student_id, course_id) VALUES (42, 1)  -- x501
 *     Total: 501 DELETE + 501 INSERT = 1002 SQL statements
 *
 *   With Set<Course> + correct equals/hashCode:
 *     INSERT INTO forge_student_courses (student_id, course_id) VALUES (42, 501)
 *     Total: 1 INSERT statement
 */