Chapter 18. XML Mapping
Prev |  | Next

## Chapter 18. XML Mapping

Note that this is an experimental feature in Hibernate 3.0 and is under extremely active development.

## 18.1. Working with XML data

Hibernate lets you work with persistent XML data in much the same way you work with persistent POJOs. A parsed XML tree can be thought of as just another way to represent the relational data at the object level, instead of POJOs.

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: `persist(), saveOrUpdate(), merge(), delete(), replicate()` (merging is not yet supported).

This feature has many applications including data import/export, externalization of entity data via JMS or SOAP and XSLT-based reporting.

A single mapping may 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 may be used to map just the XML.

### 18.1.1. Specifying XML and class mapping together

Here is an example of mapping a POJO and XML simultaneously:

    <class name="Account"
            table="ACCOUNTS"
            node="account">

        <id name="accountId"
                column="ACCOUNT_ID"
                node="@id"/>

        <many-to-one name="customer"
                column="CUSTOMER_ID"
                node="customer/@id"
                embed-xml="false"/>

        <property name="balance"
                column="BALANCE"
                node="balance"/>

        ...

    </class>

### 18.1.2. Specifying only an XML mapping

Here is an example where there is no POJO class:

    <class entity-name="Account"
            table="ACCOUNTS"
            node="account">

        <id name="id"
                column="ACCOUNT_ID"
                node="@id"
                type="string"/>

        <many-to-one name="customerId"
                column="CUSTOMER_ID"
                node="customer/@id"
                embed-xml="false"
                entity-name="Customer"/>

        <property name="balance"
                column="BALANCE"
                node="balance"
                type="big_decimal"/>

        ...

    </class>

This mapping allows you to access the data as a dom4j tree, or as a graph of property name/value pairs (java `Map`s). The property names are purely logical constructs that may be referred to in HQL queries.

## 18.2. XML mapping metadata

Many Hibernate mapping elements accept the `node` attribute. This let's you specify the name of an XML attribute or element that holds the property or entity data. The format of the `node` attribute must be one of the following:

- `"element-name"` - map to the named XML element

- `"@attribute-name"` - map to the named XML attribute

- `"."` - map to the parent element

- `"element-name/@attribute-name"` - map to the named attribute of the named element

For collections and single valued associations, there is an additional `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 `embed-xml="false"`, then only the referenced identifier value will appear in the XML for single point associations and collections will simply not appear at all.

You should be careful not to leave `embed-xml="true"` for too many associations, since XML does not deal well with circularity!

    <class name="Customer"
            table="CUSTOMER"
            node="customer">

        <id name="id"
                column="CUST_ID"
                node="@id"/>

        <map name="accounts"
                node="."
                embed-xml="true">
            <key column="CUSTOMER_ID"
                    not-null="true"/>
            <map-key column="SHORT_DESC"
                    node="@short-desc"
                    type="string"/>
            <one-to-many entity-name="Account"
                    embed-xml="false"
                    node="account"/>
        </map>

        <component name="name"
                node="name">
            <property name="firstName"
                    node="first-name"/>
            <property name="initial"
                    node="initial"/>
            <property name="lastName"
                    node="last-name"/>
        </component>

        ...

    </class>

in this case, we have decided to embed the collection of account ids, but not the actual account data. The following HQL query:

    from Customer c left join fetch c.accounts where c.lastName like :lastName

Would return datasets such as this:

    <customer id="123456789">
        <account short-desc="Savings">987632567</account>
        <account short-desc="Credit Card">985612323</account>
        <name>
            <first-name>Gavin</first-name>
            <initial>A</initial>
            <last-name>King</last-name>
        </name>
        ...
    </customer>

If you set `embed-xml="true"` on the `<one-to-many>` mapping, the data might look more like this:

    <customer id="123456789">
        <account id="987632567" short-desc="Savings">
            <customer id="123456789"/>
            <balance>100.29</balance>
        </account>
        <account id="985612323" short-desc="Credit Card">
            <customer id="123456789"/>
            <balance>-2370.34</balance>
        </account>
        <name>
            <first-name>Gavin</first-name>
            <initial>A</initial>
            <last-name>King</last-name>
        </name>
        ...
    </customer>

## 18.3. Manipulating XML data

Let's rearead and update XML documents in the application. We do this by obtaining a dom4j session:

    Document doc = ....;

    Session session = factory.openSession();
    Session dom4jSession = session.getSession(EntityMode.DOM4J);
    Transaction tx = session.beginTransaction();

    List results = dom4jSession
        .createQuery("from Customer c left join fetch c.accounts where c.lastName like :lastName")
        .list();
    for ( int i=0; i<results.size(); i++ ) {
        //add the customer data to the XML document
        Element customer = (Element) results.get(i);
        doc.add(customer);
    }

    tx.commit();
    session.close();

    Session session = factory.openSession();
    Session dom4jSession = session.getSession(EntityMode.DOM4J);
    Transaction tx = session.beginTransaction();

    Element cust = (Element) dom4jSession.get("Customer", customerId);
    for ( int i=0; i<results.size(); i++ ) {
        Element customer = (Element) results.get(i);
        //change the customer name in the XML and database
        Element name = customer.element("name");
        name.element("first-name").setText(firstName);
        name.element("initial").setText(initial);
        name.element("last-name").setText(lastName);
    }

    tx.commit();
    session.close();

It is extremely useful to combine this feature with Hibernate's `replicate()` operation to implement XML-based data import/export.

Prev | Up | Next
Chapter 17. Filtering data | Home | Chapter 19. Improving performance