Mapping Basics

Hibernate Mapping is the process of defining how Java entity classes correspond to database tables, and how their fields map to columns. It is foundational to Hibernate's ORM functionality: without accurate mappings, Hibernate cannot generate correct SQL or maintain object state.

Why it is important:

1. Eliminates hand-written SQL for CRUD — Once mapping is defined, Hibernate generates INSERT, SELECT, UPDATE, and DELETE statements automatically.
2. Object-relational impedance mismatch — Relational databases think in tables and rows; Java thinks in objects and references. Mapping bridges this gap (inheritance hierarchies, collections, embedded types).
3. Database portability — Mappings are database-agnostic. Switching from MySQL to PostgreSQL requires only a dialect change, not query rewrites.
4. Type safety — Working with Java types rather than raw SQL strings catches many errors at compile time.

Two ways to define mappings in Hibernate 6:

1. Annotation-based (standard, preferred):

import jakarta.persistence.*;

@Entity
@Table(name = "product")
public class Product {

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

    @Column(name = "product_name", nullable = false, length = 200)
    private String name;

    @Column(precision = 10, scale = 2)
    private BigDecimal price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id")
    private Category category;

    // getters and setters
}

2. XML mapping files (.hbm.xml): Legacy approach, still supported but rarely used in new projects.

Key mapping annotations (all from jakarta.persistence):

• @Entity, @Table — class-to-table
• @Id, @GeneratedValue — primary key
• @Column — field-to-column customisation
• @OneToOne, @OneToMany, @ManyToOne, @ManyToMany — relationships
• @Embedded, @Embeddable — value types
• @Inheritance — hierarchy mapping strategies

Hibernate maps a Java class to a database table through annotations placed directly on the class and its fields. The mapping instructs Hibernate which table to query, which column each field corresponds to, and how to generate/manage primary keys.

Minimal annotation-based mapping:

import jakarta.persistence.*;

@Entity                          // marks this class as a managed entity
@Table(name = "customer")        // maps to the "customer" table (optional if name matches)
public class Customer {

    @Id                          // marks the primary key field
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // auto-increment
    private Long id;

    @Column(name = "full_name", nullable = false, length = 150)
    private String name;

    @Column(unique = true, nullable = false)
    private String email;

    @Column(name = "created_at")
    private LocalDateTime createdAt;
}

@GeneratedValue strategies:

Field-level conventions:

• If @Column is omitted, the column name defaults to the field name (or snake_case with Spring Boot's spring.jpa.hibernate.naming.physical-strategy).
• If @Table is omitted, the table name defaults to the class name.
• Fields annotated @Transient are not persisted.

XML alternative (legacy): Older projects used .hbm.xml files (``). Modern projects use annotations exclusively; XML support remains but is discouraged in new code.

Hibernate 6 note: The @Entity annotation must come from jakarta.persistence (not javax.persistence). Using javax.persistence with Spring Boot 3 / Hibernate 6 causes ClassNotFoundException at startup.

Inheritance Mapping in Hibernate allows you to persist a Java class hierarchy — a superclass and its subclasses — into a relational database, which has no native concept of inheritance. Hibernate provides three strategies, each a different trade-off between normalisation and performance.

1. SINGLE_TABLE (default)

All classes in the hierarchy share one table. A discriminator column identifies which subclass a row represents.

import jakarta.persistence.*;

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "vehicle_type")
public abstract class Vehicle {
    @Id @GeneratedValue private Long id;
    private String manufacturer;
}

@Entity
@DiscriminatorValue("CAR")
public class Car extends Vehicle {
    private int numDoors;
}

@Entity
@DiscriminatorValue("TRUCK")
public class Truck extends Vehicle {
    private double payloadTons;
}

• Pros: Best query performance (single SELECT); no joins.
• Cons: Subclass-specific columns are nullable; table grows wide with many subclasses.

2. JOINED

Each class has its own table. The subclass table contains only its own columns plus a foreign key to the parent table.

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class Vehicle { ... }

@Entity
@PrimaryKeyJoinColumn(name = "car_id")
public class Car extends Vehicle { private int numDoors; }

• Pros: Fully normalised; no nullable columns.
• Cons: Requires JOIN for every query on a subclass; more SQL overhead.

3. TABLE_PER_CLASS

Each concrete class has a standalone table containing all inherited columns too.

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public abstract class Vehicle { ... }

• Pros: No joins for single-type queries.
• Cons: Polymorphic queries (e.g., SELECT v FROM Vehicle v) require UNION ALL; no shared sequence for IDs (must use TABLE or UUID strategy).

Interview follow-up: SINGLE_TABLE is the default and usually the best performer. Use JOINED when strict normalisation and data integrity matter. Avoid TABLE_PER_CLASS unless polymorphic queries are rare.

Associations in Hibernate mapping define relationships between entity classes and instruct Hibernate how to join the corresponding database tables. All association annotations come from jakarta.persistence.

Four association types:

1. @ManyToOne (most common)

import jakarta.persistence.*;

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

    @ManyToOne(fetch = FetchType.LAZY)  // always use LAZY for @ManyToOne
    @JoinColumn(name = "customer_id")
    private Customer customer;
}

2. @OneToMany (bidirectional with @ManyToOne)

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

    @OneToMany(mappedBy = "customer", cascade = CascadeType.ALL, orphanRemoval = true)
    private List orders = new ArrayList<>();
}

mappedBy points to the field name in Order that owns the foreign key. The Customer side does not own the join column.

3. @OneToOne

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

    @OneToOne(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    @JoinColumn(name = "profile_id", unique = true)
    private UserProfile profile;
}

4. @ManyToMany

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

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

Key concepts:

• Owning side vs. inverse side — The side with @JoinColumn or @JoinTable owns the relationship. mappedBy marks the inverse side. Only the owning side updates the foreign key column.
• Cascade types — CascadeType.ALL, PERSIST, MERGE, REMOVE, REFRESH, DETACH control which operations propagate from parent to child.
• orphanRemoval = true — Automatically deletes child entities removed from the parent collection.
• fetch = FetchType.LAZY — Default for @OneToMany and @ManyToMany; should also be set explicitly for @ManyToOne and @OneToOne.

A composite primary key uses two or more columns together to uniquely identify a row. Hibernate provides two approaches: @EmbeddedId and @IdClass.

Approach 1: @EmbeddedId (preferred)

Create a separate class annotated @Embeddable to represent the composite key:

import jakarta.persistence.*;
import java.io.Serializable;
import java.util.Objects;

@Embeddable
public class OrderLineId implements Serializable {
    private Long orderId;
    private Long productId;

    // required: no-arg constructor, equals(), hashCode()
    public OrderLineId() {}

    public OrderLineId(Long orderId, Long productId) {
        this.orderId = orderId;
        this.productId = productId;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderLineId that)) return false;
        return Objects.equals(orderId, that.orderId) &&
               Objects.equals(productId, that.productId);
    }

    @Override
    public int hashCode() { return Objects.hash(orderId, productId); }
}

@Entity
public class OrderLine {
    @EmbeddedId
    private OrderLineId id;

    private int quantity;
    private BigDecimal unitPrice;
}

Approach 2: @IdClass

Keep the fields on the entity and reference a separate ID class:

@IdClass(OrderLineId.class)
@Entity
public class OrderLine {
    @Id private Long orderId;
    @Id private Long productId;
    private int quantity;
}

OrderLineId here is a plain class with matching field names (no @Embeddable required), but must still implement Serializable and override equals/hashCode.

Using composite keys:

OrderLineId key = new OrderLineId(1L, 42L);
OrderLine line = em.find(OrderLine.class, key);

Rules for the ID class (both approaches):

• Must implement Serializable
• Must override equals() and hashCode() — failure here causes incorrect caching and incorrect identity comparison
• Must have a public no-argument constructor

When to prefer @EmbeddedId: When the composite key is a meaningful value object (e.g., OrderLineId) that you reference in queries. @IdClass is simpler but less object-oriented.