Chapter 4. Compositions

Historically Hibernate called these components. JPA calls them embeddables. Either way the concept is the same: a composition of values. For example we might have a Name class that is a composition of first-name and last-name, or an Address class that is a composition of street, city, postal code, etc.

Example 4.1. Simple composition example

@Embeddable
public class Name {
	private String firstName;
	private String middleName;
	private String lastName;
	...
}

@Embeddable
public class Address {
	private String line1;
	private String line2;
	@Embedded
	private ZipCode zipCode;
	...

	@Embeddable
	public static class Zip {
		private String postalCode;
		private String plus4;
		...
	}
}

A composition is another form of value type. The lifecycle of a composition is defined by the thing that contains it.

A composition inherits the attribute access of its parent. For details on attribute access, see ???.

Compositions can be made up of basic values as well as associations, with the caveat that compositions which are used as collection elements cannot themselves define collections.

4.1. Component / Embedded

This is the form of composition you will see most often. Here an entity or another composition is the container.

Example 4.2. Simple Embedded

@Entity
public class Person {
	@Id
	private Integer id;
	@Embedded
	private Name name;
	...
}

Note

Notice that JPA defines 2 terms for composition: Embeddable and Embedded. Embeddable is used to describe the composition class itself (Name). Embedded is used to describe a usage of that composition (Person.name).

The composition here is the Name type related to Person.name.

Example 4.3. Person table

create table Person (
    id integer not null,
    firstName VARCHAR,
    middleName VARCHAR,
    lastName VARCHAR,
    ...
)

The composed values are mapped to the same table as the parent table. Composition is part of good OO data modeling (idiomatic java). In fact that table could also be mapped by the following entity instead.

Example 4.4. Alternative to composition

@Entity
public class Person {
	@Id
	private Integer id;
	private String firstName;
	private String middleName;
	private String lastName;
	...
}

The composition form is certainly more OO. And that becomes more evident as we work with multiple compositions.

4.2. Multiple compositions

Example 4.5. Multiple compositions

@Entity
public class Contact {
	@Id
	private Integer id;
	@Embedded
	private Name name;
	@Embedded
	private Address homeAddress;
	@Embedded
	private Address mailingAddress;
	@Embedded
	private Address workAddress;
	...
}

It is certainly more convenient to work with the compositions. However, an interesting thing happens in this particular example. By default, this mapping actually will not work as-is. The problem is in how JPA defines implicit naming rules for columns that are part of a composition, which say that all of the Address compositions would map to the same implicit column names.

This occurs any time we have multiple compositions based on the same embeddable in a given parent. We have a few options to handle this issue.

4.2.1. JPA's AttributeOverride

The JPA-defined way to handle this situation is through the use of its AttributeOverride annotation.

Example 4.6. JPA's AttributeOverride

@Entity
public class Contact {
	@Id
	private Integer id;
	@Embedded
	private Name name;
	@Embedded
	@AttributeOverrides(
			@AttributeOverride(
					name="line1",
					column = @Column(name = "home_address_line1"),
			),
			@AttributeOverride(
					name="line2",
					column = @Column(name = "home_address_line2")
			),
			@AttributeOverride(
					name="zipCode.postalCode",
					column = @Column(name = "home_address_postal_cd")
			),
			@AttributeOverride(
					name="zipCode.plus4",
					column = @Column(name = "home_address_postal_plus4")
			)
	)
	private Address homeAddress;
	@Embedded
	@AttributeOverrides(
			@AttributeOverride(
					name="line1",
					column = @Column(name = "mailing_address_line1"),
			),
			@AttributeOverride(
					name="line2",
					column = @Column(name = "mailing_address_line2")
			),
			@AttributeOverride(
					name="zipCode.postalCode",
					column = @Column(name = "mailing_address_postal_cd")
			),
			@AttributeOverride(
					name="zipCode.plus4",
					column = @Column(name = "mailing_address_postal_plus4")
			)
	)
	private Address mailingAddress;
	@Embedded
	@AttributeOverrides(
			@AttributeOverride(
					name="line1",
					column = @Column(name = "work_address_line1"),
			),
			@AttributeOverride(
					name="line2",
					column = @Column(name = "work_address_line2")
			),
			@AttributeOverride(
					name="zipCode.postalCode",
					column = @Column(name = "work_address_postal_cd")
			),
			@AttributeOverride(
					name="zipCode.plus4",
					column = @Column(name = "work_address_postal_plus4")
			)
	)
	private Address workAddress;
	...
}

Now, essentially there are no implicit column names in the Address compositions. We have explicitly named them.

4.2.2. ImplicitNamingStrategy

Note

This is a Hibernate specific feature. Users concerned with JPA provider portability should instead prefer explicit column naming with AttributeOverride as per Section 4.2.1, “JPA's AttributeOverride”

Hibernate naming strategies are covered in detail in ???. However, for the purposes of this discussion, Hibernate has the capability to interpret implicit column names in a way that is safe for use with multiple compositions.

Example 4.7. Enabling composition-safe implicit naming

MetadataSources sources = ...;
sources.addAnnotatedClass( Address.class );
sources.addAnnotatedClass( Name.class );
sources.addAnnotatedClass( Contact.class );

Metadata metadata = sources.getMetadataBuilder()
		.applyImplicitNamingStrategy( ImplicitNamingStrategyComponentPathImpl.INSTANCE )
		...
		.build();

Now the "path" to attributes are used in the implicit column naming.

Example 4.8. Enabling composition-safe implicit naming

create table Contact(
	id integer not null,
	name_firstName VARCHAR,
	name_middleName VARCHAR,
	name_lastName VARCHAR,
	homeAddress_line1 VARCHAR,
	homeAddress_line2 VARCHAR,
	homeAddress_zipCode_postalCode VARCHAR,
	homeAddress_zipCode_plus4 VARCHAR,
	mailingAddress_line1 VARCHAR,
	mailingAddress_line2 VARCHAR,
	mailingAddress_zipCode_postalCode VARCHAR,
	mailingAddress_zipCode_plus4 VARCHAR,
	workAddress_line1 VARCHAR,
	workAddress_line2 VARCHAR,
	workAddress_zipCode_postalCode VARCHAR,
	workAddress_zipCode_plus4 VARCHAR,
	...
)

You could even develop your own to do special implicit naming.