@MappedSuperclass marks a class whose persistent properties are inherited by mapped subclasses. The superclass is not mapped to its own table; each concrete entity stores inherited properties in its table. Without the annotation, superclass properties are ignored by default. section 7.1
Use a mapped superclass when a hierarchy shares state but does not require a persistent superclass entity.
- Declare shared identifiers and fields, such as id and owner, in the superclass; subclasses inherit their persistence mappings. section 7.1
- Map concrete subclasses with @Entity, producing independent tables that contain both local and inherited columns. section 7.1
- Override inherited column mappings with @AttributeOverride; JPA 2.2 permits repeated annotations, while earlier versions require @AttributeOverrides. section 7.1
- Reuse repository behavior through a generic base Spring Data JPA repository marked @NoRepositoryBean, then specialize repositories for each entity. section 7.1
- Avoid it when a polymorphic association or collection must target the superclass; that hierarchy must use @Entity and @Inheritance instead. section 7.8.2
Billing details hierarchy
Annotate abstract BillingDetails with @MappedSuperclass and place its generated id and owner there. CreditCard and BankAccount become @Entity classes with their own columns and tables; CreditCard can rename owner to CC_OWNER. A shared BillingDetailsRepository<T extends BillingDetails, ID> supplies findByOwner while concrete repositories add subtype-specific queries.
Mapped superclass for embeddables
Hibernate also permits an embeddable class to inherit persistent properties from a mapped superclass. Dimensions and Weight extend Measurement, inherit name and symbol, and override their column names so an Item can embed both without conflicts. An abstract Measurement property cannot be embedded polymorphically because no discriminator identifies the concrete subtype. section 7.6
