Hibernate example source code file (xml.xml)

This example Hibernate source code file (xml.xml) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

a, cdata, cdata, customer, customer, customer_id, element, element, hibernate, public, this, xml, xml, you

The Hibernate xml.xml source code

<?xml version='1.0' encoding="UTF-8"?>
<!--
  ~ Hibernate, Relational Persistence for Idiomatic Java
  ~
  ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
  ~ indicated by the @author tags or express copyright attribution
  ~ statements applied by the authors.  All third-party contributions are
  ~ distributed under license by Red Hat Middleware LLC.
  ~
  ~ This copyrighted material is made available to anyone wishing to use, modify,
  ~ copy, or redistribute it subject to the terms and conditions of the GNU
  ~ Lesser General Public License, as published by the Free Software Foundation.
  ~
  ~ This program is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.ent">
%BOOK_ENTITIES;

]>

<chapter id="xml">
    <title>XML Mapping

    <para>
        XML Mapping is an experimental feature in Hibernate 3.0 and is currently under
        active development.
    </emphasis>

    <section id="xml-intro" revision="1">
        <title>Working with XML data

        <para>
            Hibernate allows you to work with persistent XML data in much the same way
            you work with persistent POJOs. A parsed XML tree can be thought of
            as another way of representing the relational data at the object level,
            instead of POJOs.
        </para>

        <para>
            Hibernate supports dom4j as API for manipulating XML trees. You can write 
            queries that retrieve dom4j trees from the database and have any 
            modification you make to the tree automatically synchronized to the 
            database. You can even take an XML document, parse it using dom4j, and
            write it to the database with any of Hibernate's basic operations: 
            <literal>persist(), saveOrUpdate(), merge(), delete(), replicate() 
            (merging is not yet supported).
        </para>

        <para>
            This feature has many applications including data import/export, 
            externalization of entity data via JMS or SOAP and XSLT-based reporting.
        </para>
        
        <para>
            A single mapping can be used to simultaneously map properties of a class
            and nodes of an XML document to the database, or, if there is no class to map, 
            it can be used to map just the XML.
        </para>
        
        <section id="xml-intro-mapping">
            <title>Specifying XML and class mapping together

            <para>
                Here is an example of mapping a POJO and XML simultaneously:
            </para>
            
            <programlisting role="XML">
        </section>
        
        <section id="xml-onlyxml">
            <title>Specifying only an XML mapping

            <para>
                Here is an example where there is no POJO class:
            </para>
            
            <programlisting role="XML">
        
            <para>
                This mapping allows you to access the data as a dom4j tree, or as a graph of
                property name/value pairs or java <literal>Maps. The property names
                are purely logical constructs that can be referred to in HQL queries.
            </para>

        </section>
        
     </section>
     
    <section id="xml-mapping" revision="1">
        <title>XML mapping metadata

        <para>
            A range of Hibernate mapping elements accept the <literal>node attribute.
            This lets you specify the name of an XML attribute or element that holds the
            property or entity data. The format of the <literal>node attribute
            must be one of the following:
        </para>
        
        <itemizedlist spacing="compact">
        <listitem>
            <para>"element-name": map to the named XML element
        </listitem>
        <listitem>
            <para>"@attribute-name": map to the named XML attribute
        </listitem>
        <listitem>
            <para>".": map to the parent element
        </listitem>
        <listitem>
            <para>
                <literal>"element-name/@attribute-name":
                map to the named attribute of the named element
            </para>
        </listitem>
        </itemizedlist>
        
        <para>
            For collections and single valued associations, there is an additional 
            <literal>embed-xml attribute. If embed-xml="true",
            the default, the XML tree for the associated entity (or collection of value type) 
            will be embedded directly in the XML tree for the entity that owns the association.
            Otherwise, if <literal>embed-xml="false", then only the referenced 
            identifier value will appear in the XML for single point associations and 
            collections will not appear at all.
        </para>
        
        <para>
            Do not leave <literal>embed-xml="true" for
            too many associations, since XML does not deal well with circularity.
        </para>
        
        <programlisting role="XML">

        <para>
            In this case, the collection of account ids is embedded, but not
            the actual account data. The following HQL query:
        </para>
        
        <programlisting>
        
        <para>
            would return datasets such as this:
        </para>
        
        <programlisting role="XML">
    <account short-desc="Savings">987632567
    <account short-desc="Credit Card">985612323
    <name>
        <first-name>Gavin
        <initial>A
        <last-name>King
    </name>
    ...
</customer>]]>

        <para>
            If you set <literal>embed-xml="true" on the <one-to-many>
            mapping, the data might look more like this:
        </para>
        
        <programlisting role="XML">
    <account id="987632567" short-desc="Savings">
        <customer id="123456789"/>
        <balance>100.29
    </account>
    <account id="985612323" short-desc="Credit Card">
        <customer id="123456789"/>
        <balance>-2370.34
    </account>
    <name>
        <first-name>Gavin
        <initial>A
        <last-name>King
    </name>
    ...
</customer>]]>
       
    </section>
    
    
    <section id="xml-manipulation" revision="1">
        <title>Manipulating XML data
        
        <para>
            You can also re-read and update XML documents in the application. You can do this by
            obtaining a dom4j session:
        </para>
        
       <programlisting role="JAVA">
       
       <programlisting role="JAVA">

        <para>
            When implementing XML-based data import/export, it is useful to combine this feature with Hibernate's <literal>replicate()
            operation.
        </para>
       
    </section>
     
</chapter>