hibernate-orm/reference/en/modules/example_parentchild.xml

<chapter id="example-parentchild">
    <title>Example: Parent/Child</title>

    <para>
        One of the very first things that new users try to do with Hibernate is to model a parent / child type 
        relationship. There are two different approaches to this. For various reasons the most convenient 
        approach, especially for new users, is to model both <literal>Parent</literal> and <literal>Child</literal> 
        as entity classes with a <literal>&lt;one-to-many&gt;</literal> association from <literal>Parent</literal> 
        to <literal>Child</literal>. (The alternative approach is to declare the <literal>Child</literal> as a 
        <literal>&lt;composite-element&gt;</literal>.) Now, it turns out that default semantics of a one to many 
        association (in Hibernate) are much less close to the usual semantics of a parent / child relationship than 
        those of a composite element mapping. We will explain how to use a <emphasis>bidirectional one to many 
        association with cascades</emphasis> to model a parent / child relationship efficiently and elegantly. It's 
        not at all difficult!
    </para>
    
    <sect1 id="example-parentchild-collections">
        <title>A note about collections</title>

        <para>
            Hibernate collections are considered to be a logical part of their owning entity; never of the
            contained entities. This is a crucial distinction! It has the following consequences:
        </para>

        <itemizedlist>
            <listitem>
            <para>
                When we remove / add an object from / to a collection, the version number of the collection owner
                is incremented.
            </para>
            </listitem>
            <listitem>
            <para>
                If an object that was removed from a collection is an instance of a value type (eg, a composite
                element), that object will cease to be persistent and its state will be completely removed from
                the database. Likewise, adding a value type instance to the collection will cause its state to be
                immediately persistent.
            </para>
            </listitem>
            <listitem>
            <para>
                On the other hand, if an entity is removed from a collection (a one-to-many or many-to-many
                association), it will not be deleted, by default. This behaviour is completely consistent - a
                change to the internal state of another entity should not cause the associated entity to vanish!
                Likewise, adding an entity to a collection does not cause that entity to become persistent, by
                default.
            </para>
            </listitem>
        </itemizedlist>

        <para>
            Instead, the default behaviour is that adding an entity to a collection merely creates a link between
            the two entities, while removing it removes the link. This is very appropriate for all sorts of cases.
            Where it is not appropriate at all is the case of a parent / child relationship, where the life of the
            child is bound to the lifecycle of the parent.
        </para>
    
    </sect1>

    <sect1 id="example-parentchild-bidir">
        <title>Bidirectional one-to-many</title>

        <para>
            Suppose we start with a simple <literal>&lt;one-to-many&gt;</literal> association from
            <literal>Parent</literal> to <literal>Child</literal>.
        </para>

        <programlisting><![CDATA[<set name="children">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>]]></programlisting>
    
        <para>
            If we were to execute the following code
        </para>

        <programlisting><![CDATA[Parent p = .....;
Child c = new Child();
p.getChildren().add(c);
session.save(c);
session.flush();]]></programlisting>
    
        <para>
            Hibernate would issue two SQL statements:
        </para>

        <itemizedlist>
        <listitem>
            <para>an <literal>INSERT</literal> to create the record for <literal>c</literal></para>
        </listitem>
        <listitem>
            <para>
                an <literal>UPDATE</literal> to create the link from <literal>p</literal> to
                <literal>c</literal>
            </para>
        </listitem>
        </itemizedlist>
    
        <para>
            This is not only inefficient, but also violates any <literal>NOT NULL</literal> constraint on the
            <literal>parent_id</literal> column.
        </para>

        <para>
            The underlying cause is that the link (the foreign key <literal>parent_id</literal>) from
            <literal>p</literal> to <literal>c</literal> is not considered part of the state of the <literal>Child</literal>
            object and is therefore not created in the <literal>INSERT</literal>. So the solution is to make the link part
            of the <literal>Child</literal> mapping.
        </para>

        <programlisting><![CDATA[<many-to-one name="parent" column="parent_id" not-null="true"/>]]></programlisting>

        <para>
            (We also need to add the <literal>parent</literal> property to the <literal>Child</literal> class.)
        </para>

        <para>
            Now that the <literal>Child</literal> entity is managing the state of the link, we tell the collection not
            to update the link. We use the <literal>inverse</literal> attribute.
        </para>

        <programlisting><![CDATA[<set name="children" inverse="true">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>]]></programlisting>

        <para>
            The following code would be used to add a new <literal>Child</literal>
        </para>

        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
c.setParent(p);
p.getChildren().add(c);
session.save(c);
session.flush();]]></programlisting>

        <para>
            And now, only one SQL <literal>INSERT</literal> would be issued!
        </para>

        <para>
            To tighten things up a bit, we could create an <literal>addChild()</literal> method of
            <literal>Parent</literal>.
        </para>

        <programlisting><![CDATA[public void addChild(Child c) {
    c.setParent(this);
    children.add(c);
}]]></programlisting>

        <para>
            Now, the code to add a <literal>Child</literal> looks like
        </para>

        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
p.addChild(c);
session.save(c);
session.flush();]]></programlisting>

     </sect1>
     
     <sect1 id="example-parentchild-cascades">
         <title>Cascading lifecycle</title>
     
         <para>
             The explicit call to <literal>save()</literal> is still annoying. We will address this by
             using cascades.
         </para>

        <programlisting><![CDATA[<set name="children" inverse="true" cascade="all">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>]]></programlisting>
     
         <para>
             This simplifies the code above to
         </para>

        <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
p.addChild(c);
session.flush();]]></programlisting>
     
         <para>
             Similarly, we don't need to iterate over the children when saving or deleting a <literal>Parent</literal>.
             The following removes <literal>p</literal> and all its children from the database.
         </para>

         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
session.delete(p);
session.flush();]]></programlisting>
     
         <para>
             However, this code
         </para>

         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
Child c = (Child) p.getChildren().iterator().next();
p.getChildren().remove(c);
c.setParent(null);
session.flush();]]></programlisting>
     
         <para>
             will not remove <literal>c</literal> from the database; it will ony remove the link to <literal>p</literal>
             (and cause a <literal>NOT NULL</literal> constraint violation, in this case). You need to explicitly
             <literal>delete()</literal> the <literal>Child</literal>.
         </para>

         <programlisting><![CDATA[Parent p = (Parent) session.load(Parent.class, pid);
Child c = (Child) p.getChildren().iterator().next();
p.getChildren().remove(c);
session.delete(c);
session.flush();]]></programlisting>

         <para>
             Now, in our case, a <literal>Child</literal> can't really exist without its parent. So if we remove
             a <literal>Child</literal> from the collection, we really do want it to be deleted. For this, we must
             use <literal>cascade="all-delete-orphan"</literal>.
         </para>

        <programlisting><![CDATA[<set name="children" inverse="true" cascade="all-delete-orphan">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>]]></programlisting>

         <para>
             Note: even though the collection mapping specifies <literal>inverse="true"</literal>, cascades are still
             processed by iterating the collection elements. So if you require that an object be saved, deleted or
             updated by cascade, you must add it to the collection. It is not enough to simply call
             <literal>setParent()</literal>.
         </para>
               
     </sect1>
     
     <sect1 id="example-parentchild-update">
         <title>Using cascading <literal>update()</literal></title>
     
         <para>
             Suppose we loaded up a <literal>Parent</literal> in one <literal>Session</literal>, made some changes in a UI
             action and wish to persist these changes in a new Session (by calling <literal>update()</literal>). The
             <literal>Parent</literal> will contain a collection of childen and, since cascading update is enabled, Hibernate
             needs to know which children are newly instantiated and which represent existing rows in the database. Lets assume
             that both <literal>Parent</literal> and <literal>Child</literal> have (synthetic) identifier properties of type
             <literal>java.lang.Long</literal>. Hibernate will use the identifier property value to determine which of the
             children are new. (You may also use the version or timestamp property, see
             <xref linkend="manipulatingdata-updating-detached"/>.)
         </para>

         <para>
             The <literal>unsaved-value</literal> attribute is used to specify the identifier value of a newly instantiated
             instance. <literal>unsaved-value</literal> defaults to "null", which is perfect for a <literal>Long</literal>
             identifier type. If we would have used a primitive identitifier property, we would need to specify
         </para>

         <programlisting><![CDATA[<id name="id" type="long" unsaved-value="0">]]></programlisting>

         <para>
             for the <literal>Child</literal> mapping. (There is also an <literal>unsaved-value</literal> attribute
             for version and timestamp property mappings.)
         </para>

         <para>
             The following code will update <literal>parent</literal> and <literal>child</literal> and insert
             <literal>newChild</literal>.
         </para>

         <programlisting><![CDATA[//parent and child were both loaded in a previous session
parent.addChild(child);
Child newChild = new Child();
parent.addChild(newChild);
session.update(parent);
session.flush();]]></programlisting>
     
         <para>
             Well, thats all very well for the case of a generated identifier, but what about assigned identifiers
             and composite identifiers? This is more difficult, since <literal>unsaved-value</literal> can't
             distinguish between a newly instantiated object (with an identifier assigned by the user) and an object
             loaded in a previous session. In these cases, you will probably need to give Hibernate a hint; either
         </para>

         <itemizedlist>
         <listitem>
             <para>
                 define <literal>unsaved-value="null"</literal> or <literal>unsaved-value="negative"</literal>
                 on a <literal>&lt;version&gt;</literal> or <literal>&lt;timestamp&gt;</literal> property
                 mapping for the class.
             </para>
         </listitem>
         <listitem>
             <para>
                 set <literal>unsaved-value="none"</literal> and explicitly <literal>save()</literal>
                 newly instantiated children before calling <literal>update(parent)</literal>
             </para>
         </listitem>
         <listitem>
             <para>
                 set <literal>unsaved-value="any"</literal> and explicitly <literal>update()</literal>
                 previously persistent children before calling <literal>update(parent)</literal>
             </para>
         </listitem>
         </itemizedlist>

         <para>
             <literal>none</literal> is the default <literal>unsaved-value</literal> for assigned and composite
             identifiers.
         </para>

         <para>
             There is one further possibility. There is a new <literal>Interceptor</literal> method named
             <literal>isUnsaved()</literal> which lets the application implement its own strategy for distinguishing
             newly instantiated objects. For example, you could define a base class for your persistent classes.
         </para>

         <programlisting><![CDATA[public class Persistent {
    private boolean _saved = false;
    public void onSave() {
        _saved=true;
    }
    public void onLoad() {
        _saved=true;
    }
    ......
    public boolean isSaved() {
        return _saved;
    }
}]]></programlisting>
     
         <para>
             (The <literal>saved</literal> property is non-persistent.)
             Now implement <literal>isUnsaved()</literal>, along with <literal>onLoad()</literal>
             and <literal>onSave()</literal> as follows.
         </para>

         <programlisting><![CDATA[public Boolean isUnsaved(Object entity) {
    if (entity instanceof Persistent) {
        return new Boolean( !( (Persistent) entity ).isSaved() );
    }
    else {
        return null;
    }
}

public boolean onLoad(Object entity, 
    Serializable id,
    Object[] state,
    String[] propertyNames,
    Type[] types) {

    if (entity instanceof Persistent) ( (Persistent) entity ).onLoad();
    return false;
}

public boolean onSave(Object entity,
    Serializable id,
    Object[] state,
    String[] propertyNames,
    Type[] types) {
        
    if (entity instanceof Persistent) ( (Persistent) entity ).onSave();
    return false;
}]]></programlisting>
     
     </sect1>

     <sect1 id="example-parentchild-conclusion">
         <title>Conclusion</title>

         <para>
             There is quite a bit to digest here and it might look confusing first time around. However, in practice, it
             all works out quite nicely. Most Hibernate applications use the parent / child pattern in many places.
         </para>

         <para>
             We mentioned an alternative in the first paragraph. None of the above issues exist in the case of
             <literal>&lt;composite-element&gt;</literal> mappings, which have exactly the semantics of a parent / child
             relationship. Unfortunately, there are two big limitations to composite element classes: composite elements may
             not own collections, and they should not be the child of any entity other than the unique parent. (However,
             they <emphasis>may</emphasis> have a surrogate primary key, using an <literal>&lt;idbag&gt;</literal> mapping.)
         </para>
     
     </sect1>
     
</chapter>