Skip to content

Commit 7a67f39

Browse files
sebersolesebersole
committed
HHH-9998 - Continue documentation TLC - mapping compositions & collections
1 parent 9d22ed6 commit 7a67f39

File tree

16 files changed

+669
-7
lines changed

16 files changed

+669
-7
lines changed

‎documentation/src/main/docbook/integration/en-US/Hibernate_Integrations.xml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,11 @@
4444

4545
<xi:include href="Preface.xml" />
4646

47-
<xi:include href="chapters/services/Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
47+
<xi:include href="chapters/services/Services.xml" />
48+
49+
<!--
50+
<xi:include href="chapters/types/Custom_Types.xml" />
51+
-->
4852

4953
</book>
5054

‎documentation/src/main/docbook/manual/en-US/chapters/portability/Portability.xml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,4 +189,8 @@
189189
</section>
190190
-->
191191
</section>
192+
193+
JPA portability
194+
* HQL/JPQL differences
195+
* naming strategies
192196
</chapter>

‎documentation/src/main/docbook/mapping/en-US/Hibernate_Mapping.xml

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,20 @@
4646

4747
<xi:include href="chapters/categoizations/Data_Categorizations.xml" />
4848
<xi:include href="chapters/basic/Basic_Types.xml" />
49-
<!--
50-
<xi:include href="chapters/component/Component.xml" />
49+
<xi:include href="chapters/composition/Composition.xml" />
5150
<xi:include href="chapters/collection/Collection.xml" />
52-
<xi:include href="chapters/entity/Entity.xml" />
53-
<xi:include href="chapters/id/Identifiers.xml" />
54-
<xi:include href="chapters/association/Associations.xml" />
55-
-->
51+
52+
<!--
53+
<xi:include href="chapters/entity/Entity.xml" />
54+
<xi:include href="chapters/id/Identifiers.xml" />
55+
<xi:include href="chapters/association/Associations.xml" />
56+
<xi:include href="chapters/natural_id/Natural_Id.xml" />
57+
58+
<xi:include href="chapters/generation/Generated_attributes.xml" />
59+
<xi:include href="chapters/access/Attribute_Access.xml" />
60+
<xi:include href="chapters/overrides/Mapping_Overrides.xml" /> AttributeOverrides/AssociationOverrides
61+
<xi:include href="chapters/naming/Naming_Strategies.xml" />
62+
-->
5663

5764
<!-- appendices? -->
5865
<!-- biblio? -->

‎documentation/src/main/docbook/mapping/en-US/chapters/collection/Collection.xml

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Hibernate, Relational Persistence for Idiomatic Java
4+
~
5+
~ License: GNU Lesser General Public License (LGPL), version 2.1 or later.
6+
~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
7+
-->
8+
<chapter xml:id="collections"
9+
version="5.0"
10+
xml:lang="en"
11+
xmlns="http://docbook.org/ns/docbook"
12+
xmlns:xi="http://www.w3.org/2001/XInclude"
13+
>
14+
<title>Collections</title>
15+
16+
<section xml:id="collections-synopsis">
17+
<title>Collections as a value type</title>
18+
<para>
19+
discussions of what it means for them to be value types - lifecycle, opt-locking
20+
</para>
21+
<para>
22+
Collections have the usual behavior of value types. They are automatically persisted when referenced by
23+
a persistent object and are automatically deleted when unreferenced. If a collection is passed from one
24+
persistent object to another, its elements might be moved from one table to another. Two entities cannot
25+
share a reference to the same collection instance.
26+
</para>
27+
<para>
28+
Collection attributes do not support null value semantics; Hibernate does not distinguish between a null
29+
collection reference and an empty collection.
30+
</para>
31+
<para>
32+
It is important that collections be defined using the appropriate Java Collections Framework interface
33+
rather than a specific implementation. From a theoretical perspective, this just follows good design
34+
principles. From a practical perspective, Hibernate (really all persistence providers) will use
35+
their own collection implementations which conform to the Java Collections Framework interfaces.
36+
</para>
37+
</section>
38+
39+
<section xml:id="collections-value">
40+
<title>Collections of value types</title>
41+
<para>
42+
collection of values - elements can be of any value type except for collections (in fact even compositions as the element cannot contain collections)
43+
* basics
44+
* compositions
45+
</para>
46+
</section>
47+
48+
<section xml:id="collections-entity">
49+
<title>Collections of entities</title>
50+
<para>
51+
* one-to-many
52+
* many-to-many
53+
</para>
54+
</section>
55+
56+
<section xml:id="collections-list">
57+
<title>List - index</title>
58+
<para>
59+
<!-- todo : discuss mapping list index -->
60+
todo : discuss mapping list index
61+
</para>
62+
</section>
63+
64+
<section xml:id="collections-map">
65+
<title>Map - key</title>
66+
<para>
67+
<!-- todo : discuss mapping map key -->
68+
todo : discuss mapping map key
69+
</para>
70+
</section>
71+
72+
<section xml:id="collections-bag">
73+
<title>Bags</title>
74+
<para>
75+
<!-- todo : discuss mapping bags -->
76+
todo : discuss mapping bags
77+
</para>
78+
</section>
79+
80+
<section xml:id="collections-array">
81+
<title>Arrays</title>
82+
<para>
83+
<!-- todo : discuss mapping arrays -->
84+
todo : discuss mapping arrays
85+
</para>
86+
</section>
87+
88+
<section xml:id="collections-as-basic">
89+
<title>Collections as basic value type</title>
90+
<para>
91+
Notice how all the previous examples explicitly mark the collection attribute as either
92+
ElementCollection, OneToMany or ManyToMany. Collections not marked as such, or collections explicitly
93+
maked with @Basic are treated as JPA basic value. Meaning there value is stored into a single
94+
column in the containing table.
95+
</para>
96+
<para>
97+
This is sometimes beneficial. Consider a use-case such as a VARCHAR column that represents a
98+
delimited list or set of Strings.
99+
</para>
100+
<example>
101+
<title>Delimited set of tags</title>
102+
<programlisting role="JAVA"><xi:include href="extras/DelimitedStringTagsExample.java" parse="text" /></programlisting>
103+
</example>
104+
105+
<para>
106+
See the <citetitle>Hibernate Integrations Guide</citetitle> for more details on developing
107+
custom value type mappings.
108+
</para>
109+
</section>
110+
111+
</chapter>

‎documentation/src/main/docbook/mapping/en-US/chapters/collection/extras/DelimitedStringTagsExample.java

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
@Entity
2+
public static class Post {
3+
@Id
4+
public Integer id;
5+
@Basic
6+
@Type( type = "delimited_strings" )
7+
Set<String> tags;
8+
}
9+
10+
11+
public static class DelimitedStringsType extends AbstractSingleColumnStandardBasicType<Set> {
12+
public DelimitedStringsType() {
13+
super(
14+
VarcharTypeDescriptor.INSTANCE,
15+
new DelimitedStringsJavaTypeDescriptor()
16+
);
17+
}
18+
19+
@Override
20+
public String getName() {
21+
return "delimited_strings";
22+
}
23+
}
24+
25+
public static class DelimitedStringsJavaTypeDescriptor extends AbstractTypeDescriptor<Set> {
26+
public DelimitedStringsJavaTypeDescriptor() {
27+
super(
28+
Set.class,
29+
new MutableMutabilityPlan<Set>() {
30+
@Override
31+
protected Set deepCopyNotNull(Set value) {
32+
Set<String> copy = new HashSet<String>();
33+
copy.addAll( value );
34+
return copy;
35+
}
36+
}
37+
);
38+
}
39+
40+
@Override
41+
public String toString(Set value) {
42+
return null;
43+
}
44+
45+
@Override
46+
public Set fromString(String string) {
47+
return null;
48+
}
49+
50+
@Override
51+
public <X> X unwrap(Set value, Class<X> type, WrapperOptions options) {
52+
return null;
53+
}
54+
55+
@Override
56+
public <X> Set wrap(X value, WrapperOptions options) {
57+
return null;
58+
}
59+
}

0 commit comments

Comments
 (0)