Mastering @ManyToMany Relationships with Join Tables in JPA/Hibernate

Table of Contents

Article

In relational databases, a Many-to-Many relationship occurs when multiple records in one table are associated with multiple records in another table. The JPA specification provides the @ManyToMany annotation to model this relationship, which always requires a join table (junction table) to manage the associations. This article explores how to properly implement and use @ManyToMany relationships in Java with JPA and Hibernate.

Understanding the Database Schema

In a typical Many-to-Many scenario, three tables are involved:

Table A (e.g., students)
Table B (e.g., courses)
Join Table (e.g., student_courses) containing foreign keys to both tables

Example Schema:

CREATE TABLE students (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100) NOT NULL
);
CREATE TABLE courses (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
title VARCHAR(100) NOT NULL,
code VARCHAR(20) UNIQUE NOT NULL
);
CREATE TABLE student_courses (
student_id BIGINT,
course_id BIGINT,
enrolled_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (student_id, course_id),
FOREIGN KEY (student_id) REFERENCES students(id) ON DELETE CASCADE,
FOREIGN KEY (course_id) REFERENCES courses(id) ON DELETE CASCADE
);

Basic @ManyToMany Implementation

Entity Classes

Student Entity (Owning Side):

@Entity
@Table(name = "students")
public class Student {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false)
private String name;
@ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@JoinTable(
name = "student_courses",
joinColumns = @JoinColumn(name = "student_id"),
inverseJoinColumns = @JoinColumn(name = "course_id")
)
private Set<Course> courses = new HashSet<>();
// Constructors, getters, setters
public Student() {}
public Student(String name) {
this.name = name;
}
// Helper methods for managing relationships
public void addCourse(Course course) {
this.courses.add(course);
course.getStudents().add(this);
}
public void removeCourse(Course course) {
this.courses.remove(course);
course.getStudents().remove(this);
}
// Getters and setters
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Set<Course> getCourses() { return courses; }
public void setCourses(Set<Course> courses) { this.courses = courses; }
}

Course Entity (Inverse Side):

@Entity
@Table(name = "courses")
public class Course {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(nullable = false)
private String title;
@Column(nullable = false, unique = true)
private String code;
@ManyToMany(mappedBy = "courses")
private Set<Student> students = new HashSet<>();
// Constructors, getters, setters
public Course() {}
public Course(String title, String code) {
this.title = title;
this.code = code;
}
// Getters and setters
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getTitle() { return title; }
public void setTitle(String title) { this.title = title; }
public String getCode() { return code; }
public void setCode(String code) { this.code = code; }
public Set<Student> getStudents() { return students; }
public void setStudents(Set<Student> students) { this.students = students; }
}

Key Annotations Explained

@ManyToMany

Defines the many-to-many relationship between entities
Can be configured with cascade types and fetch strategies

@JoinTable

Specifies the join table details (only on one side)
name: The name of the join table
joinColumns: Foreign key column pointing to the owning entity
inverseJoinColumns: Foreign key column pointing to the inverse entity

mappedBy

Used on the non-owning side to indicate the field that owns the relationship
The value should match the field name on the owning side

Advanced: Join Table with Additional Columns

When you need to store additional information about the relationship (like enrollment date, grade, etc.), you must create an intermediate entity.

Intermediate Entity Approach

Enrollment Entity (Replaces the simple join table):

@Entity
@Table(name = "student_courses")
public class Enrollment {
@EmbeddedId
private EnrollmentId id = new EnrollmentId();
@ManyToOne
@MapsId("studentId")
@JoinColumn(name = "student_id")
private Student student;
@ManyToOne
@MapsId("courseId")
@JoinColumn(name = "course_id")
private Course course;
@Column(name = "enrolled_at")
private LocalDateTime enrolledAt;
private String grade;
// Constructors, getters, setters
public Enrollment() {}
public Enrollment(Student student, Course course) {
this.student = student;
this.course = course;
this.enrolledAt = LocalDateTime.now();
this.id = new EnrollmentId(student.getId(), course.getId());
}
}
@Embeddable
public class EnrollmentId implements Serializable {
private Long studentId;
private Long courseId;
// Default constructor, getters, setters
public EnrollmentId() {}
public EnrollmentId(Long studentId, Long courseId) {
this.studentId = studentId;
this.courseId = courseId;
}
// Getters and setters
public Long getStudentId() { return studentId; }
public void setStudentId(Long studentId) { this.studentId = studentId; }
public Long getCourseId() { return courseId; }
public void setCourseId(Long courseId) { this.courseId = courseId; }
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof EnrollmentId)) return false;
EnrollmentId that = (EnrollmentId) o;
return Objects.equals(studentId, that.studentId) &&
Objects.equals(courseId, that.courseId);
}
@Override
public int hashCode() {
return Objects.hash(studentId, courseId);
}
}

Updated Student Entity:

@Entity
@Table(name = "students")
public class Student {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name;
@OneToMany(mappedBy = "student", cascade = CascadeType.ALL, orphanRemoval = true)
private Set<Enrollment> enrollments = new HashSet<>();
// Helper method
public void enrollInCourse(Course course) {
Enrollment enrollment = new Enrollment(this, course);
enrollments.add(enrollment);
course.getEnrollments().add(enrollment);
}
// Getters and setters
public Set<Enrollment> getEnrollments() { return enrollments; }
// ... other getters/setters
}

Repository and Usage Examples

StudentRepository:

@Repository
public interface StudentRepository extends JpaRepository<Student, Long> {
@Query("SELECT s FROM Student s JOIN s.courses c WHERE c.code = :courseCode")
List<Student> findStudentsByCourseCode(@Param("courseCode") String courseCode);
@Query("SELECT s FROM Student s WHERE SIZE(s.courses) > :minCourses")
List<Student> findStudentsWithMoreThanCourses(@Param("minCourses") int minCourses);
}

Usage in Service Class:

@Service
@Transactional
public class UniversityService {
@Autowired
private StudentRepository studentRepository;
@Autowired
private CourseRepository courseRepository;
public void enrollStudentInCourse(Long studentId, Long courseId) {
Student student = studentRepository.findById(studentId)
.orElseThrow(() -> new RuntimeException("Student not found"));
Course course = courseRepository.findById(courseId)
.orElseThrow(() -> new RuntimeException("Course not found"));
student.addCourse(course);
// No need to call save() - changes are persisted automatically due to @Transactional
}
public List<Student> getStudentsInCourse(String courseCode) {
return studentRepository.findStudentsByCourseCode(courseCode);
}
}

Best Practices and Common Pitfalls

Use Sets Instead of Lists: Prefer Set to avoid duplicate entries and potential Hibernate performance issues.
Helper Methods: Always provide helper methods (addCourse(), removeCourse()) to manage both sides of the relationship.
Cascade Carefully: Avoid CascadeType.ALL as it may delete more than intended. Use {CascadeType.PERSIST, CascadeType.MERGE} instead.
Lazy Loading: By default, @ManyToMany uses lazy loading, which is generally preferred for performance.
Bidirectional vs Unidirectional: Consider if you need bidirectional access. If not, make it unidirectional to simplify your model.
Fetch Strategies: Use @ManyToMany(fetch = FetchType.LAZY) explicitly for large collections to avoid N+1 query problems.

Conclusion

The @ManyToMany relationship with a join table is a powerful feature in JPA for modeling complex relationships between entities. While the basic implementation is straightforward, understanding how to handle additional attributes in the relationship through an intermediate entity is crucial for real-world applications. By following these patterns and best practices, you can create efficient and maintainable data models that accurately represent your domain relationships.