From hibernate-commits at lists.jboss.org Wed Jun 30 07:50:41 2010 Content-Type: multipart/mixed; boundary="===============1294347123335428389==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r19859 - core/trunk/documentation/manual/src/main/docbook/en-US/content. Date: Wed, 30 Jun 2010 07:50:41 -0400 Message-ID: <201006301150.o5UBofT3027949@svn01.web.mwc.hst.phx2.redhat.com> --===============1294347123335428389== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: hardy.ferentschik Date: 2010-06-30 07:50:41 -0400 (Wed, 30 Jun 2010) New Revision: 19859 Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/collectio= n_mapping.xml Log: HHH-5149 Reviewing the collection mapping chapter Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/co= llection_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/collecti= on_mapping.xml 2010-06-29 17:53:40 UTC (rev 19858) +++ core/trunk/documentation/manual/src/main/docbook/en-US/content/collecti= on_mapping.xml 2010-06-30 11:50:41 UTC (rev 19859) @@ -113,7 +113,7 @@ this: = - Collection mapping using annotations + Collection mapping using @OneToMany and @JoinColumn = @Entity public class Product { @@ -126,6 +126,7 @@ void setSerialNumber(String sn) { serialNumber =3D sn; } = @OneToMany + @JoinColumn(name=3D"PART_ID") public Set<Part> getParts() { return parts; } void setParts(Set parts) { this.parts =3D parts; } } @@ -137,9 +138,56 @@ } = - Lets have a look how collections are mapped using Hibernate mapp= ing - files. Here the first step is to chose the right mapping element, beca= use - it depends on the type of interface. For example, a + Product describes a unidirectional relationship with Part using = the + join column PART_ID. In this unidirectional one to many scenario you c= an + also use a join table as seen in . + + + Collection mapping= using + @OneToMany and @JoinTable + + @Entity +public class Product { + + private String serialNumber; + private Set<Part> parts =3D new HashSet<Part>(); + + @Id + public String getSerialNumber() { return serialNumber; } + void setSerialNumber(String sn) { serialNumber =3D sn; } + = + @OneToMany + @JoinTable( + name=3D"PRODUCT_PARTS", + joinColumns =3D @JoinColumn( name=3D"PRODUCT_ID"), + inverseJoinColumns =3D @JoinColumn( name=3D"PART_ID") + ) + public Set<Part> getParts() { return parts; } + void setParts(Set parts) { this.parts =3D parts; } +} + + +(a)Entity +public class Part { + ... +} + + + Without describing any physical mapping (no + @JoinColumn or @JoinTable), + a unidirectional one to many with join table is used. The table name is + the concatenation of the owner table name, _, and the other side table + name. The foreign key name(s) referencing the owner table is the + concatenation of the owner table, _, and the owner primary key column(= s) + name. The foreign key name(s) referencing the other side is the + concatenation of the owner property name, _, and the other side primary + key column(s) name. A unique constraint is added to the foreign key + referencing the other side table to reflect the one to many. + + Lets have a look now how collections are mapped using Hibernate + mapping files. In this case the first step is to chose the right mappi= ng + element. It depends on the type of interface. For example, a <set> element is used for mapping properties = of type Set. = @@ -438,6 +486,10 @@
Indexed collections = + In the following paragraphs we have a closer at the indexed + collections List and Map + how the their index can be mapped in Hibernate. +
Lists = @@ -458,7 +510,7 @@ To order lists in memory, add @javax.persistence.OrderBy to your property. Th= is annotation takes as parameter a list of comma separated properties= (of - the target entity) and order the collection accordingly (eg + the target entity) and orders the collection accordingly (eg firstname asc, age desc), if the string is empty, the collection will be ordered by the primary key of the target entity. @@ -516,7 +568,7 @@ orders_ORDER). = - Additional index column using + <title>Explicit index column using <classname>@OrderColumn</classname> = @Entity @@ -569,11 +621,11 @@ is 0 like in Java. = - Using mapping files the index of an array or list is always = of - type integer and is mapped using the - <list-index> element. The mapped column - contains sequential integers that are numbered from zero by - default. + Looking again at the Hibernate mapping file equivalent, the + index of an array or list is always of type integer + and is mapped using the <list-index> elem= ent. + The mapped column contains sequential integers that are numbered f= rom + zero by default. = index-list element for indexed collections in xml @@ -615,20 +667,21 @@ <section> <title>Maps = - Maps can borrow their keys from one of the associated entity - properties or have dedicated columns to store an explicit key. + The question with Maps is where the k= ey + value is stored. There are everal options. Maps can borrow their k= eys + from one of the associated entity properties or have dedicated col= umns + to store an explicit key. = To use one of the target entity property as a key of the map, - use @MapKey(name=3D"myProperty") - (myProperty is a property name in the target - entity). When using @MapKey (without property - name), the target entity primary key is used. The map key uses the - same column as the property pointed out: there is no additional co= lumn - defined to hold the map key, and it does make sense since the map = key - actually represent a target property. Be aware that once loaded, t= he - key is no longer kept in sync with the property, in other words, if - you change the property value, the key will not change automatical= ly - in your Java model. + use @MapKey(name=3D"myProperty"), where + myProperty is a property name in the target ent= ity. + When using @MapKey without the name attribuate,= the + target entity primary key is used. The map key uses the same colum= n as + the property pointed out. There is no additional column defined to + hold the map key, because the map key represent a target property.= Be + aware that once loaded, the key is no longer kept in sync with the + property. In other words, if you change the property value, the key + will not change automatically in your Java model. = Use of target entity property as map key via @@ -673,14 +726,14 @@ |-------------|</programlisting> </example> = - <para>Otherwise, the map key is mapped to a dedicated column or + <para>Alternatively the map key is mapped to a dedicated column or columns. In order to customize the mapping use one of the following annotations:</para> = <itemizedlist> <listitem> <para>@<classname>MapKeyColumn</classname> if the map key is a - basic type, if you don't specify the column name, the name of = the + basic type. If you don't specify the column name, the name of = the property followed by underscore followed by <literal>KEY</lite= ral> is used (for example <literal>orders_KEY</literal>).</para> </listitem> @@ -757,11 +810,11 @@ the new standard approach described above</para> </note> = - <para>Using Hibernate mapping files there exists similar concepts - using <literal><map-key></literal>, + <para>Using Hibernate mapping files there exists equivalent concep= ts + to the descibed annotations. You have to use + <literal><map-key></literal>, <literal><map-key-many-to-many></literal> and - <literal><composite-map-key></literal> which are even a litt= le - more flexible since SQL expressions can be used to define the map = key. + <literal><composite-map-key></literal>. <literal><map-key></literal> is used for any basic type, <literal><map-key-many-to-many></literal> for an entity reference and <literal><composite-map-key></literal> for a @@ -845,11 +898,11 @@ </section> = <section id=3D"collections-ofvalues" revision=3D"2"> - <title>Collections of values + Collections of basic types and embeddable objects = In some situations you don't need to associate two entities but simply create a collection of basic types or embeddable objects. Use= the - @ElementCollection in this case. + @ElementCollection for this case. = Collection of basic types mapped via @@ -869,7 +922,7 @@ = <para>The collection table holding the collection data is set using = the <classname>@CollectionTable</classname> annotation. If omitted the - collection table name default to the concatenation of the name of the + collection table name defaults to the concatenation of the name of t= he containing entity and the name of the collection attribute, separate= d by an underscore. In our example, it would be <literal>User_nicknames</literal>.</para> @@ -992,9 +1045,9 @@ <para>Hibernate supports collections implementing <literal>java.util.SortedMap</literal> and <literal>java.util.SortedSet</literal>. With annotations you declare= a - sort comparator using <literal>@Sort</literal>. You between the + sort comparator using <literal>@Sort</literal>. You chose between the comparator types unsorted, natural or custom. If you want to use your - own comparator implementation, you'll also have to express the + own comparator implementation, you'll also have to specify the implementation class using the <literal>comparator</literal> attribu= te. Note that you need to use either a <classname>SortedSet</classname> = or a <classname>SortedMap</classname> interface.</para> @@ -1005,8 +1058,6 @@ <programlisting language=3D"JAVA" role=3D"JAVA">@OneToMany(cascade= =3DCascadeType.ALL, fetch=3DFetchType.EAGER) @JoinColumn(name=3D"CUST_ID") @Sort(type =3D SortType.COMPARATOR, comparator =3D TicketComparator.class) -(a)Where(clause=3D"1=3D1") -(a)OnDelete(action=3DOnDeleteAction.CASCADE) public SortedSet<Ticket> getTickets() { return tickets; }</programlisting> @@ -1036,17 +1087,18 @@ <literal>unsorted</literal>, <literal>natural</literal> and the name= of a class implementing <literal>java.util.Comparator</literal>.</para> = - <para>Sorted collections actually behave like - <literal>java.util.TreeSet</literal> or - <literal>java.util.TreeMap</literal>.</para> + <tip> + <para>Sorted collections actually behave like + <literal>java.util.TreeSet</literal> or + <literal>java.util.TreeMap</literal>.</para> + </tip> = <para>If you want the database itself to order the collection elemen= ts, use the <literal>order-by</literal> attribute of <literal>set</liter= al>, <literal>bag</literal> or <literal>map</literal> mappings. This solu= tion - is only available under JDK 1.4 or higher and is implemented using - <literal>LinkedHashSet</literal> or <literal>LinkedHashMap</literal>. - This performs the ordering in the SQL query and not in the - memory.</para> + is implemented using <literal>LinkedHashSet</literal> or + <literal>LinkedHashMap</literal> and performs the ordering in the SQL + query and not in the memory.</para> = <example> <title>Sorting in database using order-by @@ -1161,10 +1213,11 @@ } = - Again a look at the maping file approach. There you can define= a - bidirectional one-to-many association by mapping a one-to-many - association to the same table column(s) as a many-to-one association= and - declaring the many-valued end inverse=3D"true". + How does the mappping of a bidirectional mapping look like in + Hibernate mapping xml? There you define a bidirectional one-to-many + association by mapping a one-to-many association to the same table + column(s) as a many-to-one association and declaring the many-valued= end + inverse=3D"true". = Bidirectional one to many via Hibernate mapping files</titl= e> @@ -1233,9 +1286,7 @@ } </programlisting> </example> = - <para>We've already shown the many declarations and the detailed - attributes for associations. We'll go deeper in the - <literal>@JoinTable</literal> description, it defines a + <para>In this example <classname>@JoinTable</classname> defines a <literal>name</literal>, an array of join columns, and an array of inverse join columns. The latter ones are the columns of the associa= tion table which refer to the <classname>Employee</classname> primary key @@ -1323,11 +1374,12 @@ <para>You cannot select an indexed collection.</para> </note></para> = - <para>Here is an example of a bidirectional many-to-many association - that illustrates how each category can have many items and each item= can - be in many categories:</para> + <para><xref linkend=3D"example-many-to-many-mapping-file" /> shows a + bidirectional many-to-many association that illustrates how each + category can have many items and each item can be in many + categories:</para> = - <example> + <example id=3D"example-many-to-many-mapping-file"> <title>Many to many association using Hibernate mapping files</tit= le> = <programlisting role=3D"XML"><class name=3D"Category"> @@ -1376,15 +1428,11 @@ <section id=3D"collections-indexedbidirectional"> <title>Bidirectional associations with indexed collections = - Here are some additional consideration for bidirectional mappi= ngs - with indexed collections using Hibernate mapping files. Refer also to - and . - - A bidirectional association where one end is represented as a - <list> or <map>, - requires special consideration. If there is a property of the child - class that maps to the index column you can use + There are some additional considerations for bidirectional + mappings with indexed collections (where one end is represented as a + <list> or <map>) w= hen + using Hibernate mapping files. If there is a property of the child c= lass + that maps to the index column you can use inverse=3D"true" on the collection mapping: = @@ -1491,12 +1539,12 @@ = The majority of the many-to-many associations and collections = of values shown previously all map to tables with composite keys, even - though it has been have suggested that entities should have synthetic + though it has been suggested that entities should have synthetic identifiers (surrogate keys). A pure association table does not seem= to benefit much from a surrogate key, although a collection of composite - values might. It is for this reason Hibernate - provides a feature that allows you to map many-to-many associations = and - collections of values to a table with a surrogate key. + values might. For this reason Hibernate provide= s a + feature that allows you to map many-to-many associations and collect= ions + of values to a table with a surrogate key. = The <idbag> element lets you map a List (or Collection) with bag --===============1294347123335428389==--