From hibernate-commits at lists.jboss.org Wed May 26 12:20:44 2010 Content-Type: multipart/mixed; boundary="===============8224033008522862064==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r19619 - core/trunk/documentation/manual/src/main/docbook/en-US/content. Date: Wed, 26 May 2010 12:20:44 -0400 Message-ID: <201005261620.o4QGKiQp022999@svn01.web.mwc.hst.phx2.redhat.com> --===============8224033008522862064== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: epbernard Date: 2010-05-26 12:20:43 -0400 (Wed, 26 May 2010) New Revision: 19619 Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_map= ping.xml Log: HHH-5149 Merge embedded object / component documentations Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/ba= sic_mapping.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma= pping.xml 2010-05-26 16:20:08 UTC (rev 19618) +++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma= pping.xml 2010-05-26 16:20:43 UTC (rev 19619) @@ -4572,14 +4572,115 @@ = -
- Component and dynamic-component +
+ Embedded objects (aka components) = - The <component> element maps properti= es - of a child object to columns of the table of a parent class. Compone= nts - can, in turn, declare their own properties, components or collection= s. - 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 enti= ty + 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 embe= dded + object for a particular entity using the @Embedded + and @AttributeOverride annotation in the associat= ed + property: + + @Entity +public class Person implements Serializable { + + // Persistent component using defaults + Address homeAddress; + + @Embedded + @AttributeOverrides( { + @AttributeOverride(name=3D"iso2", column =3D @Column(name=3D"b= ornIso2") ), + @AttributeOverride(name=3D"name", column =3D @Column(name=3D"b= ornCountryName") ) + } ) + 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=3D"countryName") private String name; + + public String getIso2() { return iso2; } + public void setIso2(String iso2) { this.iso2 =3D iso2; } + + = + public String getName() { return name; } + public void setName(String name) { this.name =3D name; } + ... +} + + An embeddable object inherits the access type of its owning en= tity + (note that you can override that using the @Access + annotation). + + The Person entity has two component propert= ies, + 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=3D"city", column =3D @Column(name=3D"f= ld_city") ), + @AttributeOverride(name=3D"nationality.iso2", column =3D @Colu= mn(name=3D"nat_Iso2") ), + @AttributeOverride(name=3D"nationality.name", column =3D @Colu= mn(name=3D"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 obje= ct + with the @MappedSuperclass annotation to make the + superclass properties persistent (see + @MappedSuperclass for more informations). + + You can also use association annotations in an embeddable obje= ct + (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 t= he + 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, al= lows + 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 exam= ple + of this. + + If a property of the embedded object points back to the owning + entity, annotate it with the @Parent annotati= on. + Hibernate will make sure this property is properly loaded with the + entity reference. + + In XML, use the <component> + element. + @@ -4676,7 +4777,8 @@ The <dynamic-component> element allow= s a Map to be mapped as a component, where the proper= ty names refer to keys of the map. See for more information. + linkend=3D"components-dynamic" /> for more information. This feature= is + not supported in annotations.
=
--===============8224033008522862064==--