The Java EE 6 Tutorial, Volume I

Embeddable Classes in Entities

Embeddable classes are used to represent the state of an entity, but don't have a persistent identity of their own, unlike entity classes. Instances of an embeddable class share the identity of the entity that owns it. Embeddable classes only exist as the state of another entity. An entity may have single-valued or collection-valued embeddable class attributes.

Embeddable classes have the same rules as entity classes, except that they are annotated with the javax.persistence.Embeddable annotation instead of @Entity.

Example 19–3 Embeddable Class Example

The following embeddable class, ZipCode has two fields, zip and plusFour.

public class ZipCode {
  String zip;
  String plusFour;

This embeddable class is used by the Address entity.

public class Address {
  protected long id
  String street1;
  String street2;
  String city;
  String province;
  ZipCode zipCode;
  String country;

Entities that own embeddable classes as part of their persistent state may annotate the field or property with the javax.persitence.Embedded annotation, but are not required to do so.

Embeddable classes may themselves use other embeddable classes to represent their state. They may also contain collections of basic Java programming language types, or other embeddable classes. Embeddable classes may also contain relationships to other entities or collections of entities. If the embeddable class has such a relationship, the relationship is from the target entity or collection of entities to the entity that owns the embeddable class.