← Back to branch summary

~raginggoblin/infolog/infolog

« back to all changes in this revision

Viewing changes to InfologServer/lib/hibernate-distribution-3.3.2.GA/project/documentation/manual/old/pt-BR/src/main/docbook/content/example_parentchild.xml

  • Committer: Raging Goblin
  • Date: 2013-11-16 16:51:32 UTC
  • Revision ID: raging_goblin-20131116165132-weujnptzc88uy4ah
Mavenized the project, now using shared project InfologSync

Show diffs side-by-side

added added

removed removed

Lines of Context:
InfologServer/lib/hibernate-distribution-3.3.2.GA/project/documentation/manual/old/pt-BR/src/main/docbook/content/example_parentchild.xml
1
 
<?xml version='1.0' encoding="UTF-8"?>
2
 
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
3
 
 
4
 
<chapter id="example-parentchild">
5
 
    <title>Example: Parent/Child</title>
6
 
 
7
 
    <para>
8
 
        One of the very first things that new users try to do with Hibernate is to model a parent / child type 
9
 
        relationship. There are two different approaches to this. For various reasons the most convenient 
10
 
        approach, especially for new users, is to model both <literal>Parent</literal> and <literal>Child</literal> 
11
 
        as entity classes with a <literal>&lt;one-to-many&gt;</literal> association from <literal>Parent</literal> 
12
 
        to <literal>Child</literal>. (The alternative approach is to declare the <literal>Child</literal> as a 
13
 
        <literal>&lt;composite-element&gt;</literal>.) Now, it turns out that default semantics of a one to many 
14
 
        association (in Hibernate) are much less close to the usual semantics of a parent / child relationship than 
15
 
        those of a composite element mapping. We will explain how to use a <emphasis>bidirectional one to many 
16
 
        association with cascades</emphasis> to model a parent / child relationship efficiently and elegantly. 
17
 
        It's not at all difficult!
18
 
    </para>
19
 
    
20
 
    <sect1 id="example-parentchild-collections">
21
 
        <title>A note about collections</title>
22
 
 
23
 
        <para>
24
 
            Hibernate collections are considered to be a logical part of their owning entity; never of the
25
 
            contained entities. This is a crucial distinction! It has the following consequences:
26
 
        </para>
27
 
 
28
 
        <itemizedlist>
29
 
            <listitem>
30
 
            <para>
31
 
                When we remove / add an object from / to a collection, the version number of the collection owner
32
 
                is incremented.
33
 
            </para>
34
 
            </listitem>
35
 
            <listitem>
36
 
            <para>
37
 
                If an object that was removed from a collection is an instance of a value type (eg, a composite
38
 
                element), that object will cease to be persistent and its state will be completely removed from
39
 
                the database. Likewise, adding a value type instance to the collection will cause its state to be
40
 
                immediately persistent.
41
 
            </para>
42
 
            </listitem>
43
 
            <listitem>
44
 
            <para>
45
 
                On the other hand, if an entity is removed from a collection (a one-to-many or many-to-many
46
 
                association), it will not be deleted, by default. This behaviour is completely consistent - a
47
 
                change to the internal state of another entity should not cause the associated entity to vanish!
48
 
                Likewise, adding an entity to a collection does not cause that entity to become persistent, by
49
 
                default.
50
 
            </para>
51
 
            </listitem>
52
 
        </itemizedlist>
53
 
 
54
 
        <para>
55
 
            Instead, the default behaviour is that adding an entity to a collection merely creates a link between
56
 
            the two entities, while removing it removes the link. This is very appropriate for all sorts of cases.
57
 
            Where it is not appropriate at all is the case of a parent / child relationship, where the life of the
58
 
            child is bound to the life cycle of the parent.
59
 
        </para>
60
 
    
61
 
    </sect1>
62
 
 
63
 
    <sect1 id="example-parentchild-bidir">
64
 
        <title>Bidirectional one-to-many</title>
65
 
 
66
 
        <para>
67
 
            Suppose we start with a simple <literal>&lt;one-to-many&gt;</literal> association from
68
 
            <literal>Parent</literal> to <literal>Child</literal>.
69
 
        </para>
70
 
 
71
 
        <programlisting><![CDATA[<set name="children">
72
 
    <key column="parent_id"/>
73
 
    <one-to-many class="Child"/>
74
 
</set>]]></programlisting>
75
 
    
76
 
        <para>
77
 
            If we were to execute the following code
78
 
        </para>
79
 
 
80
 
        <programlisting><![CDATA[Parent p = .....;
81
 
Child c = new Child();
82
 
p.getChildren().add(c);
83
 
session.save(c);
84
 
session.flush();]]></programlisting>
85
 
    
86
 
        <para>
87
 
            Hibernate would issue two SQL statements:
88
 
        </para>
89
 
 
90
 
        <itemizedlist>
91
 
        <listitem>
92
 
            <para>an <literal>INSERT</literal> to create the record for <literal>c</literal></para>
93
 
        </listitem>
94
 
        <listitem>
95
 
            <para>
96
 
                an <literal>UPDATE</literal> to create the link from <literal>p</literal> to
97
 
                <literal>c</literal>
98
 
            </para>
99
 
        </listitem>
100
 
        </itemizedlist>
101
 
    
102
 
        <para>
103
 
            This is not only inefficient, but also violates any <literal>NOT NULL</literal> constraint on the
104
 
            <literal>parent_id</literal> column. We can fix the nullability constraint violation by specifying
105
 
            <literal>not-null="true"</literal> in the collection mapping:
106
 
        </para>
107
 
 
108
 
        <programlisting><![CDATA[<set name="children">
109
 
    <key column="parent_id" not-null="true"/>
110
 
    <one-to-many class="Child"/>
111
 
</set>]]></programlisting>
112
 
    
113
 
        <para>
114
 
                However, this is not the recommended solution.
115
 
        </para>
116
 
        <para>
117
 
            The underlying cause of this behaviour is that the link (the foreign key <literal>parent_id</literal>) 
118
 
            from <literal>p</literal> to <literal>c</literal> is not considered part of the state of the 
119
 
            <literal>Child</literal> object and is therefore not created in the <literal>INSERT</literal>. So the 
120
 
            solution is to make the link part of the <literal>Child</literal> mapping.
121
 
        </para>
122
 
 
123
 
        <programlisting><![CDATA[<many-to-one name="parent" column="parent_id" not-null="true"/>]]></programlisting>
124
 
 
125
 
        <para>
126
 
            (We also need to add the <literal>parent</literal> property to the <literal>Child</literal> class.)
127
 
        </para>
128
 
 
129
 
        <para>
130
 
            Now that the <literal>Child</literal> entity is managing the state of the link, we tell the collection 
131
 
            not to update the link. We use the <literal>inverse</literal> attribute.
132
 
        </para>
133
 
 
134
 
        <programlisting><![CDATA[<set name="children" inverse="true">
135
 
    <key column="parent_id"/>
136
 
    <one-to-many class="Child"/>
137
 
</set>]]></programlisting>
138
 
 
139
 
        <para>
140
 
            The following code would be used to add a new <literal>Child</literal>
141
 
        </para>
142
 
 
143
 
        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
144
 
Child c = new Child();
145
 
c.setParent(p);
146
 
p.getChildren().add(c);
147
 
session.save(c);
148
 
session.flush();]]></programlisting>
149
 
 
150
 
        <para>
151
 
            And now, only one SQL <literal>INSERT</literal> would be issued!
152
 
        </para>
153
 
 
154
 
        <para>
155
 
            To tighten things up a bit, we could create an <literal>addChild()</literal> method of
156
 
            <literal>Parent</literal>.
157
 
        </para>
158
 
 
159
 
        <programlisting><![CDATA[public void addChild(Child c) {
160
 
    c.setParent(this);
161
 
    children.add(c);
162
 
}]]></programlisting>
163
 
 
164
 
        <para>
165
 
            Now, the code to add a <literal>Child</literal> looks like
166
 
        </para>
167
 
 
168
 
        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
169
 
Child c = new Child();
170
 
p.addChild(c);
171
 
session.save(c);
172
 
session.flush();]]></programlisting>
173
 
 
174
 
     </sect1>
175
 
     
176
 
     <sect1 id="example-parentchild-cascades">
177
 
         <title>Cascading life cycle</title>
178
 
     
179
 
         <para>
180
 
             The explicit call to <literal>save()</literal> is still annoying. We will address this by
181
 
             using cascades.
182
 
         </para>
183
 
 
184
 
        <programlisting><![CDATA[<set name="children" inverse="true" cascade="all">
185
 
    <key column="parent_id"/>
186
 
    <one-to-many class="Child"/>
187
 
</set>]]></programlisting>
188
 
     
189
 
         <para>
190
 
             This simplifies the code above to
191
 
         </para>
192
 
 
193
 
        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
194
 
Child c = new Child();
195
 
p.addChild(c);
196
 
session.flush();]]></programlisting>
197
 
     
198
 
         <para>
199
 
             Similarly, we don't need to iterate over the children when saving or deleting a <literal>Parent</literal>.
200
 
             The following removes <literal>p</literal> and all its children from the database.
201
 
         </para>
202
 
 
203
 
         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
204
 
session.delete(p);
205
 
session.flush();]]></programlisting>
206
 
     
207
 
         <para>
208
 
             However, this code
209
 
         </para>
210
 
 
211
 
         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
212
 
Child c = (Child) p.getChildren().iterator().next();
213
 
p.getChildren().remove(c);
214
 
c.setParent(null);
215
 
session.flush();]]></programlisting>
216
 
     
217
 
         <para>
218
 
             will not remove <literal>c</literal> from the database; it will ony remove the link to <literal>p</literal>
219
 
             (and cause a <literal>NOT NULL</literal> constraint violation, in this case). You need to explicitly
220
 
             <literal>delete()</literal> the <literal>Child</literal>.
221
 
         </para>
222
 
 
223
 
         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
224
 
Child c = (Child) p.getChildren().iterator().next();
225
 
p.getChildren().remove(c);
226
 
session.delete(c);
227
 
session.flush();]]></programlisting>
228
 
 
229
 
         <para>
230
 
             Now, in our case, a <literal>Child</literal> can't really exist without its parent. So if we remove
231
 
             a <literal>Child</literal> from the collection, we really do want it to be deleted. For this, we must
232
 
             use <literal>cascade="all-delete-orphan"</literal>.
233
 
         </para>
234
 
 
235
 
        <programlisting><![CDATA[<set name="children" inverse="true" cascade="all-delete-orphan">
236
 
    <key column="parent_id"/>
237
 
    <one-to-many class="Child"/>
238
 
</set>]]></programlisting>
239
 
 
240
 
         <para>
241
 
             Note: even though the collection mapping specifies <literal>inverse="true"</literal>, cascades are 
242
 
             still processed by iterating the collection elements. So if you require that an object be saved, 
243
 
             deleted or updated by cascade, you must add it to the collection. It is not enough to simply call
244
 
             <literal>setParent()</literal>.
245
 
         </para>
246
 
               
247
 
     </sect1>
248
 
     
249
 
     <sect1 id="example-parentchild-update">
250
 
         <title>Cascades and <literal>unsaved-value</literal></title>
251
 
     
252
 
         <para>
253
 
             Suppose we loaded up a <literal>Parent</literal> in one <literal>Session</literal>, made some changes 
254
 
             in a UI action and wish to persist these changes in a new session by calling <literal>update()</literal>. 
255
 
             The <literal>Parent</literal> will contain a collection of childen and, since cascading update is enabled, 
256
 
             Hibernate needs to know which children are newly instantiated and which represent existing rows in the 
257
 
             database. Lets assume that both <literal>Parent</literal> and <literal>Child</literal> have genenerated
258
 
             identifier properties of type <literal>Long</literal>. Hibernate will use the identifier and 
259
 
             version/timestamp property value to determine which of the children are new. (See
260
 
             <xref linkend="objectstate-saveorupdate"/>.) <emphasis>In Hibernate3, it is no longer necessary to specify
261
 
             an <literal>unsaved-value</literal> explicitly.</emphasis>
262
 
         </para>
263
 
 
264
 
         <para>
265
 
             The following code will update <literal>parent</literal> and <literal>child</literal> and insert 
266
 
             <literal>newChild</literal>.
267
 
         </para>
268
 
 
269
 
         <programlisting><![CDATA[//parent and child were both loaded in a previous session
270
 
parent.addChild(child);
271
 
Child newChild = new Child();
272
 
parent.addChild(newChild);
273
 
session.update(parent);
274
 
session.flush();]]></programlisting>
275
 
     
276
 
         <para>
277
 
             Well, that's all very well for the case of a generated identifier, but what about assigned identifiers
278
 
             and composite identifiers? This is more difficult, since Hibernate can't use the identifier property to
279
 
             distinguish between a newly instantiated object (with an identifier assigned by the user) and an 
280
 
             object loaded in a previous session. In this case, Hibernate will either use the timestamp or version 
281
 
             property, or will actually query the second-level cache or, worst case, the database, to see if the 
282
 
             row exists.
283
 
         </para>
284
 
         
285
 
         <!-- undocumenting
286
 
         <para>
287
 
             There is one further possibility. The <literal>Interceptor</literal> method named 
288
 
             <literal>isUnsaved()</literal> lets the application implement its own strategy for distinguishing
289
 
             newly instantiated objects. For example, you could define a base class for your persistent classes.
290
 
         </para>
291
 
 
292
 
         <programlisting><![CDATA[public class Persistent {
293
 
    private boolean _saved = false;
294
 
    public void onSave() {
295
 
        _saved=true;
296
 
    }
297
 
    public void onLoad() {
298
 
        _saved=true;
299
 
    }
300
 
    ......
301
 
    public boolean isSaved() {
302
 
        return _saved;
303
 
    }
304
 
}]]></programlisting>
305
 
     
306
 
         <para>
307
 
             (The <literal>saved</literal> property is non-persistent.)
308
 
             Now implement <literal>isUnsaved()</literal>, along with <literal>onLoad()</literal>
309
 
             and <literal>onSave()</literal> as follows.
310
 
         </para>
311
 
 
312
 
         <programlisting><![CDATA[public Boolean isUnsaved(Object entity) {
313
 
    if (entity instanceof Persistent) {
314
 
        return new Boolean( !( (Persistent) entity ).isSaved() );
315
 
    }
316
 
    else {
317
 
        return null;
318
 
    }
319
 
}
320
 
 
321
 
public boolean onLoad(Object entity, 
322
 
    Serializable id,
323
 
    Object[] state,
324
 
    String[] propertyNames,
325
 
    Type[] types) {
326
 
 
327
 
    if (entity instanceof Persistent) ( (Persistent) entity ).onLoad();
328
 
    return false;
329
 
}
330
 
 
331
 
public boolean onSave(Object entity,
332
 
    Serializable id,
333
 
    Object[] state,
334
 
    String[] propertyNames,
335
 
    Type[] types) {
336
 
        
337
 
    if (entity instanceof Persistent) ( (Persistent) entity ).onSave();
338
 
    return false;
339
 
}]]></programlisting>
340
 
 
341
 
                <para>
342
 
                        Don't worry; in Hibernate3 you don't need to write any of this kind of code if you don't want to.
343
 
                </para>
344
 
     -->
345
 
     </sect1>
346
 
 
347
 
     <sect1 id="example-parentchild-conclusion">
348
 
         <title>Conclusion</title>
349
 
 
350
 
         <para>
351
 
             There is quite a bit to digest here and it might look confusing first time around. However, in practice, 
352
 
             it all works out very nicely. Most Hibernate applications use the parent / child pattern in many places.
353
 
         </para>
354
 
 
355
 
         <para>
356
 
             We mentioned an alternative in the first paragraph. None of the above issues exist in the case of
357
 
             <literal>&lt;composite-element&gt;</literal> mappings, which have exactly the semantics of a parent / child
358
 
             relationship. Unfortunately, there are two big limitations to composite element classes: composite elements 
359
 
             may not own collections, and they should not be the child of any entity other than the unique parent.
360
 
         </para>
361
 
     
362
 
     </sect1>
363
 
     
364
 
</chapter>