[hibernate-commits] Hibernate SVN: r19782 - core/trunk/documentation/manual/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Jun 22 12:36:46 EDT 2010
Author: hardy.ferentschik
Date: 2010-06-22 12:36:45 -0400 (Tue, 22 Jun 2010)
New Revision: 19782
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
core/trunk/documentation/manual/src/main/docbook/en-US/content/collection_mapping.xml
Log:
HHH-5149
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml 2010-06-22 16:30:24 UTC (rev 19781)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml 2010-06-22 16:36:45 UTC (rev 19782)
@@ -5198,7 +5198,7 @@
</section>
<section id="mapping-declaration-key">
- <title>Key</title>
+ <title id="section.key">Key</title>
<para>The <literal><key></literal> element is featured a few
times within this guide. It appears anywhere the parent mapping
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/collection_mapping.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/collection_mapping.xml 2010-06-22 16:30:24 UTC (rev 19781)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/collection_mapping.xml 2010-06-22 16:36:45 UTC (rev 19782)
@@ -33,34 +33,20 @@
<section id="collections-persistent" revision="3">
<title>Persistent collections</title>
- <para>Of course Hibernate also allows to persist collections. These
+ <para>Naturally Hibernate also allows to persist collections. These
persistent collections can contain almost any other Hibernate type,
including: basic types, custom types, components and references to other
- entities. This is an important distinction. An object in a collection
- might be handled with "value" semantics (its life cycle fully depends on
- the collection owner), or it might be a reference to another entity with
- its own life cycle. In the latter case, only the "link" between the two
- objects is considered to be a state held by the collection.</para>
+ entities. The distinction between value and reference semantics is in this
+ context very important. An object in a collection might be handled with
+ "value" semantics (its life cycle fully depends on the collection owner),
+ or it might be a reference to another entity with its own life cycle. In
+ the latter case, only the "link" between the two objects is considered to
+ be a state held by the collection.</para>
<para>As a requirement persistent collection-valued fields must be
- declared as an interface type. For example:</para>
-
- <example id="example-collection-values-field">
- <title>Persistent collection-valued fields must be interfaces</title>
-
- <programlisting role="JAVA">public class Product {
- private String serialNumber;
- private Set parts = new HashSet();
-
- public Set getParts() { return parts; }
- void setParts(Set parts) { this.parts = parts; }
-
- public String getSerialNumber() { return serialNumber; }
- void setSerialNumber(String sn) { serialNumber = sn; }
-}</programlisting>
- </example>
-
- <para>The actual interface might be <literal>java.util.Set</literal>,
+ declared as an interface type (see <xref
+ linkend="example.collection.mapping.annotations" />). The actual interface
+ might be <literal>java.util.Set</literal>,
<literal>java.util.Collection</literal>,
<literal>java.util.List</literal>, <literal>java.util.Map</literal>,
<literal>java.util.SortedSet</literal>,
@@ -68,15 +54,15 @@
like" means you will have to write an implementation of
<literal>org.hibernate.usertype.UserCollectionType</literal>).</para>
- <para>Notice how in <xref linkend="example-collection-values-field" /> the
- instance variable <literal>parts</literal> was initialized with an
- instance of <literal>HashSet</literal>. This is the best way to initialize
- collection valued properties of newly instantiated (non-persistent)
- instances. When you make the instance persistent, by calling
- <literal>persist()</literal>, Hibernate will actually replace the
- <literal>HashSet</literal> with an instance of Hibernate's own
- implementation of <literal>Set</literal>. Be aware of the following
- error:</para>
+ <para>Notice how in <xref
+ linkend="example.collection.mapping.annotations" /> the instance variable
+ <literal>parts</literal> was initialized with an instance of
+ <literal>HashSet</literal>. This is the best way to initialize collection
+ valued properties of newly instantiated (non-persistent) instances. When
+ you make the instance persistent, by calling <literal>persist()</literal>,
+ Hibernate will actually replace the <literal>HashSet</literal> with an
+ instance of Hibernate's own implementation of <literal>Set</literal>. Be
+ aware of the following error:</para>
<example>
<title>Hibernate uses its own collection implementations</title>
@@ -108,23 +94,25 @@
Hibernate does not distinguish between a null collection reference and an
empty collection.</para>
- <para>Use persistent collections the same way you use ordinary Java
- collections. However, please ensure you understand the semantics of
- bidirectional associations (see <xref
- linkend="collections-bidirectional" />).</para>
+ <note>
+ <para>Use persistent collections the same way you use ordinary Java
+ collections. However, ensure you understand the semantics of
+ bidirectional associations (see <xref
+ linkend="collections-bidirectional" />).</para>
+ </note>
</section>
<section id="collections-mapping" revision="4">
- <title>Collection mappings</title>
+ <title>How to map collections</title>
<para>Using annotations you can map <classname>Collection</classname>s,
- <classname>Lists</classname>, <classname>Maps</classname> and
- <classname>Sets</classname> of associated entities using @OneToMany and
+ <classname>List</classname>s, <classname>Map</classname>s and
+ <classname>Set</classname>s of associated entities using @OneToMany and
@ManyToMany. For collections of a basic or embeddable type use
@ElementCollection. In the simplest case a collection mapping looks like
this:</para>
- <example>
+ <example id="example.collection.mapping.annotations">
<title>Collection mapping using annotations</title>
<programlisting role="JAVA">@Entity
@@ -149,14 +137,11 @@
}</programlisting>
</example>
- <para>The <literal>@OneToMany</literal> and <literal>@ManyToOne</literal>
- annotations have several options and there are other annotations which can
- be used in in combination with these annotations. But lets first see how
- collections are mapped using Hibernate mapping files. Here the situation
- is more complex than in the annotation case, since the mapping element
- used for mapping a collection depends upon the type of interface. For
- example, a <literal><set></literal> element is used for mapping
- properties of type <literal>Set</literal>.</para>
+ <para>Lets have a look how collections are mapped using Hibernate mapping
+ files. Here the first step is to chose the right mapping element, because
+ it depends on the type of interface. For example, a
+ <literal><set></literal> element is used for mapping properties of
+ type <literal>Set</literal>.</para>
<example floatstyle="" id="example.collections.set">
<title>Mapping a Set using <set></title>
@@ -189,11 +174,11 @@
</listitem>
</itemizedlist>
- <para>The <literal><one-to-many></literal> tag has the following
- options.</para>
+ <para>Looking closer at the used <literal><one-to-many></literal>
+ tag we see that it has the following options.</para>
<example>
- <title>options of <one-to-many> tag</title>
+ <title>options of <one-to-many> element</title>
<programlistingco role="XML">
<areaspec>
@@ -246,8 +231,8 @@
<literal><key></literal> mapping
<literal>not-null="true"</literal> or <emphasis>use a bidirectional
association</emphasis> with the collection mapping marked
- <literal>inverse="true"</literal>. See the discussion of bidirectional
- associations later in this chapter for more information.</para>
+ <literal>inverse="true"</literal>. See <xref
+ linkend="collections-bidirectional" />.</para>
</warning>
<para>Apart from the <literal><set> </literal>tag as shown in <xref
@@ -411,12 +396,16 @@
</programlistingco>
</example>
+ <para>After exploring the basic mapping of collections in the preceding
+ paragraphs we will now focus details like physical mapping considerations,
+ indexed collections and collections of value types.</para>
+
<section id="collections-foreignkeys">
<title>Collection foreign keys</title>
- <para>Collection instances are distinguished in the database by the
- foreign key of the entity that owns the collection. This foreign key is
- referred to as the <emphasis>collection key column</emphasis>, or
+ <para>On the database level collection instances are distinguished by
+ the foreign key of the entity that owns the collection. This foreign key
+ is referred to as the <emphasis>collection key column</emphasis>, or
columns, of the collection table. The collection key column is mapped by
the <literal>@JoinColumn</literal> annotation respectively the
<literal><key></literal> XML element.</para>
@@ -442,8 +431,8 @@
<programlisting role="Java">@OnDelete(action=OnDeleteAction.CASCADE)</programlisting>
- <para>See <xref linkend="section-key" /> for more information about the
- <literal><key></literal> element.</para>
+ <para>See <xref lang="" linkend="section.key" /> for more information
+ about the <literal><key></literal> element.</para>
</section>
<section id="collections-indexed">
More information about the hibernate-commits
mailing list