From 89b2659331050749226e427cc12f6426ab2ffbef Mon Sep 17 00:00:00 2001 From: Emmanuel Bernard Date: Wed, 26 May 2010 16:20:43 +0000 Subject: [PATCH] HHH-5149 Merge embedded object / component documentations git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@19619 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../docbook/en-US/content/basic_mapping.xml | 116 ++++++++++++++++-- 1 file changed, 109 insertions(+), 7 deletions(-) diff --git a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml index 876735e0ee..7087b19096 100644 --- a/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml +++ b/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml @@ -4572,13 +4572,114 @@ List results = s.createCriteria( Citizen.class ) -
- Component and dynamic-component +
+ Embedded objects (aka components) - The <component> element maps properties - of a child object to columns of the table of a parent class. Components - can, in turn, declare their own properties, components or collections. - See the "Component" examples below: + Embeddable objects (or components) are objects whose properties + are mapped to the same table as the owning entity's table. Components + can, in turn, declare their own properties, components or + collections + + It is possible to declare an embedded component inside an entity + and even override its column mapping. Component classes have to be + annotated at the class level with the @Embeddable + annotation. It is possible to override the column mapping of an embedded + object for a particular entity using the @Embedded + and @AttributeOverride annotation in the associated + property: + + @Entity +public class Person implements Serializable { + + // Persistent component using defaults + Address homeAddress; + + @Embedded + @AttributeOverrides( { + @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ), + @AttributeOverride(name="name", column = @Column(name="bornCountryName") ) + } ) + Country bornIn; + ... +} + + @Embeddable +public class Address implements Serializable { + String city; + Country nationality; //no overriding here +} + + @Embeddable +public class Country implements Serializable { + private String iso2; + @Column(name="countryName") private String name; + + public String getIso2() { return iso2; } + public void setIso2(String iso2) { this.iso2 = iso2; } + + + public String getName() { return name; } + public void setName(String name) { this.name = name; } + ... +} + + An embeddable object inherits the access type of its owning entity + (note that you can override that using the @Access + annotation). + + The Person entity has two component properties, + homeAddress and bornIn. + homeAddress property has not been annotated, but + Hibernate will guess that it is a persistent component by looking for + the @Embeddable annotation in the Address class. We + also override the mapping of a column name (to + bornCountryName) with the + @Embedded and @AttributeOverride + annotations for each mapped attribute of + Country. As you can see, Country + is also a nested component of Address, + again using auto-detection by Hibernate and JPA defaults. Overriding + columns of embedded objects of embedded objects is through dotted + expressions. + + @Embedded + @AttributeOverrides( { + @AttributeOverride(name="city", column = @Column(name="fld_city") ), + @AttributeOverride(name="nationality.iso2", column = @Column(name="nat_Iso2") ), + @AttributeOverride(name="nationality.name", column = @Column(name="nat_CountryName") ) + //nationality columns in homeAddress are overridden + } ) + Address homeAddress; + + Hibernate Annotations supports something that is not explicitly + supported by the JPA specification. You can annotate a embedded object + with the @MappedSuperclass annotation to make the + superclass properties persistent (see + @MappedSuperclass for more informations). + + You can also use association annotations in an embeddable object + (ie @OneToOne, @ManyToOne, + @OneToMany or @ManyToMany). To + override the association columns you can use + @AssociationOverride. + + If you want to have the same embeddable object type twice in the + same entity, the column name defaulting will not work as several + embedded objects would share the same set of columns. In plain JPA, you + need to override at least one set of columns. Hibernate, however, allows + you to enhance the default naming mechanism through the + NamingStrategy interface. You can write a + strategy that prevent name clashing in such a situation. + DefaultComponentSafeNamingStrategy is an example + of this. + + If a property of the embedded object points back to the owning + entity, annotate it with the @Parent annotation. + Hibernate will make sure this property is properly loaded with the + entity reference. + + In XML, use the <component> + element. @@ -4676,7 +4777,8 @@ List results = s.createCriteria( Citizen.class ) The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map. See for more information. + linkend="components-dynamic" /> for more information. This feature is + not supported in annotations.