Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 39 ยท Entity Mapping

Embeddables and Value Objects

Group columns into value objects with @Embeddable and @Embedded, override column names with @AttributeOverride, reuse an address twice and flatten rows in a runnable stand-in.

Some groups of fields belong together but are not entities: an address, a money amount, a date range. They have no identity of their own and live and die with their owner. In Java they are small value classes; in the database they are just several columns of the owner's table. Hibernate's @Embeddable connects the two.

Real Hibernate code is read-only; the runnable programs are plain-Java stand-ins.

An embeddable address

Java
@Embeddable
public class Address {
    private String street;
    private String city;
    private String postalCode;

    protected Address() { }
    public Address(String street, String city, String postalCode) { ... }
    // getters
}

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

    @Embedded
    private Address address;
}

The customer table has columns id, name, street, city, postal_code. One row, no join. The Address has no @Id and no table. @Embedded on the field is optional when the class carries @Embeddable, but it documents intent.

Reusing an embeddable twice

A customer may have a billing and a shipping address. Both map the same columns, so one needs renaming:

Java
@Embedded
private Address billing;

@Embedded
@AttributeOverrides({
    @AttributeOverride(name = "street",     column = @Column(name = "ship_street")),
    @AttributeOverride(name = "city",       column = @Column(name = "ship_city")),
    @AttributeOverride(name = "postalCode", column = @Column(name = "ship_postal_code"))
})
private Address shipping;

@AttributeOverride replaces the column of one attribute of the embedded class for this owner only.

Embeddables as value objects

Treat embeddables as immutable value objects: build a new Address instead of changing one, and implement equals/hashCode over all fields. Since Hibernate 6.2, Java records can be embeddables:

Java
@Embeddable
public record Money(BigDecimal amount, String currency) { }

Records fit well because they are immutable and have value-based equals already.

Null embeddables

When all columns of an embedded object are NULL, Hibernate loads the field as null, not as an empty Address. Remember this when you call customer.getAddress().getCity(): the address itself may be null. If you need a non-null object, return a default from the getter, or avoid the problem by validating that at least one column is required.

Embeddables inside embeddables, and collections

An embeddable can contain another embeddable (for example Address containing GeoPoint). A list of embeddables is stored in a separate table, which is the topic of the next lesson. Embeddables can also be used as composite ids, see identifiers.

Embeddable versus entity

Embeddable Entity
Identity None @Id
Table Owner's table Own table
Lifecycle Same as owner Independent
Shared between owners No (each owner has its own copy) Yes

If two customers share one address row and you want a change to appear for both, it is an entity with a relationship, not an embeddable.

Stand-in: flatten and rebuild

Java Stand-in: embedding as flattened columns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Stand-in: all-null embeddable loads as null

Java Stand-in: null embedded object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where are the columns of an @Embeddable stored?

    An embeddable has no table; its columns belong to the owner's table.
  2. 2. How do you map the same embeddable twice in one entity?

    The overrides give each use its own column names.
  3. 3. What does Hibernate load when every column of an embedded object is NULL?

    An all-null embeddable is represented by null.
  4. 4. When should you use an entity instead of an embeddable?

    Shared, independently changing data needs identity and its own table.

Summary

  • @Embeddable groups fields into a value class stored in the owner's table.
  • @AttributeOverride lets one class be embedded several times.
  • Make embeddables immutable with value-based equals/hashCode; records work in modern Hibernate.
  • All-null columns load as a null embedded object.
  • Here, real Hibernate code is read-only; the runnable programs are plain-Java stand-ins.

Next: Element Collections and Maps