HHH-7493 : Documentation still refers to dom4j as an entity mode
This commit is contained in:
parent
b810f1049f
commit
e422250076
|
@ -4,7 +4,7 @@
|
|||
xmlns:xl="http://www.w3.org/1999/xlink">
|
||||
|
||||
<title>Configuration properties</title>
|
||||
<section>
|
||||
<section revision="1">
|
||||
<title>General Configuration</title>
|
||||
<informaltable>
|
||||
<tgroup cols="3">
|
||||
|
@ -67,10 +67,9 @@
|
|||
</row>
|
||||
<row>
|
||||
<entry>hibernate.default_entity_mode</entry>
|
||||
<entry><para>One of <literal>dynamic-map</literal>, <literal>dom4j</literal>,
|
||||
<literal>pojo</literal></para></entry>
|
||||
<entry><para><literal>dynamic-map</literal> or <literal>pojo</literal></para></entry>
|
||||
<entry>Default mode for entity representation for all sessions opened from this
|
||||
<classname>SessionFactory</classname></entry>
|
||||
<classname>SessionFactory</classname>, defaults to <literal>pojo</literal>.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>hibernate.order_updates</entry>
|
||||
|
@ -363,4 +362,4 @@
|
|||
</para>
|
||||
</note>
|
||||
</section>
|
||||
</appendix>
|
||||
</appendix>
|
||||
|
|
|
@ -65,7 +65,6 @@
|
|||
<xi:include href="content/query_criteria.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="content/query_sql.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="content/filters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="content/xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="content/performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
|
|
|
@ -309,7 +309,7 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
|
|||
above.</para>
|
||||
</warning></para>
|
||||
|
||||
<table frame="topbot" xml:id="configuration-optional-properties" revision="8">
|
||||
<table frame="topbot" xml:id="configuration-optional-properties" revision="9">
|
||||
<title>Hibernate Configuration Properties</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
|
@ -408,9 +408,10 @@ hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect</programlisting>
|
|||
<entry><property>hibernate.default_entity_mode</property></entry>
|
||||
|
||||
<entry>Sets a default mode for entity representation for all
|
||||
sessions opened from this <literal>SessionFactory</literal> <para>
|
||||
<literal>dynamic-map</literal>, <literal>dom4j</literal>,
|
||||
<literal>pojo</literal> </para></entry>
|
||||
sessions opened from this <literal>SessionFactory</literal>,
|
||||
defaults to <literal>pojo</literal>.<para>
|
||||
<emphasis role="strong">e.g.</emphasis> <literal>dynamic-map</literal> |
|
||||
<literal>pojo</literal> </para> </entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
|
|
|
@ -322,7 +322,7 @@ public class DomesticCat extends Cat {
|
|||
key.</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="persistent-classes-dynamicmodels">
|
||||
<section xml:id="persistent-classes-dynamicmodels" revision="1">
|
||||
<title>Dynamic models</title>
|
||||
|
||||
<note>
|
||||
|
@ -335,8 +335,8 @@ public class DomesticCat extends Cat {
|
|||
<para>Persistent entities do not necessarily have to be represented as
|
||||
POJO classes or as JavaBean objects at runtime. Hibernate also supports
|
||||
dynamic models (using <literal>Map</literal>s of <literal>Map</literal>s
|
||||
at runtime) and the representation of entities as DOM4J trees. With this
|
||||
approach, you do not write persistent classes, only mapping files.</para>
|
||||
at runtime). With this approach, you do not write persistent classes,
|
||||
only mapping files.</para>
|
||||
|
||||
<para>By default, Hibernate works in normal POJO mode. You can set a
|
||||
default entity representation mode for a particular
|
||||
|
@ -444,9 +444,6 @@ dynamicSession.close()
|
|||
call <literal>flush()</literal> and <literal>close()</literal> on the
|
||||
secondary <literal>Session</literal>, and also leave the transaction and
|
||||
connection handling to the primary unit of work.</para>
|
||||
|
||||
<para>More information about the XML representation capabilities can be
|
||||
found in <xref linkend="xml" />.</para>
|
||||
</section>
|
||||
|
||||
|
||||
|
|
|
@ -1,288 +0,0 @@
|
|||
<?xml version='1.0' encoding="UTF-8"?>
|
||||
|
||||
<chapter xml:id="xml" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>XML Mapping</title>
|
||||
|
||||
<para><emphasis>
|
||||
XML Mapping is an experimental feature in Hibernate 3.0 and is currently under
|
||||
active development.
|
||||
</emphasis></para>
|
||||
|
||||
<section xml:id="xml-intro" revision="1">
|
||||
<title>Working with XML data</title>
|
||||
|
||||
<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()</literal>
|
||||
(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 xml:id="xml-intro-mapping">
|
||||
<title>Specifying XML and class mapping together</title>
|
||||
|
||||
<para>
|
||||
Here is an example of mapping a POJO and XML simultaneously:
|
||||
</para>
|
||||
|
||||
<programlisting role="XML"><![CDATA[<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>]]></programlisting>
|
||||
</section>
|
||||
|
||||
<section xml:id="xml-onlyxml">
|
||||
<title>Specifying only an XML mapping</title>
|
||||
|
||||
<para>
|
||||
Here is an example where there is no POJO class:
|
||||
</para>
|
||||
|
||||
<programlisting role="XML"><![CDATA[<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>]]></programlisting>
|
||||
|
||||
<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>Map</literal>s. The property names
|
||||
are purely logical constructs that can be referred to in HQL queries.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="xml-mapping" revision="1">
|
||||
<title>XML mapping metadata</title>
|
||||
|
||||
<para>
|
||||
A range of Hibernate mapping elements accept the <literal>node</literal> 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</literal> attribute
|
||||
must be one of the following:
|
||||
</para>
|
||||
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para><literal>"element-name"</literal>: map to the named XML element</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>"@attribute-name"</literal>: map to the named XML attribute</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><literal>"."</literal>: map to the parent element</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>"element-name/@attribute-name"</literal>:
|
||||
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</literal> attribute. If <literal>embed-xml="true"</literal>,
|
||||
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"</literal>, 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"</literal> for
|
||||
too many associations, since XML does not deal well with circularity.
|
||||
</para>
|
||||
|
||||
<programlisting role="XML"><![CDATA[<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>]]></programlisting>
|
||||
|
||||
<para>
|
||||
In this case, the collection of account ids is embedded, but not
|
||||
the actual account data. The following HQL query:
|
||||
</para>
|
||||
|
||||
<programlisting><![CDATA[from Customer c left join fetch c.accounts where c.lastName like :lastName]]></programlisting>
|
||||
|
||||
<para>
|
||||
would return datasets such as this:
|
||||
</para>
|
||||
|
||||
<programlisting role="XML"><![CDATA[<customer xml: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>]]></programlisting>
|
||||
|
||||
<para>
|
||||
If you set <literal>embed-xml="true"</literal> on the <literal><one-to-many></literal>
|
||||
mapping, the data might look more like this:
|
||||
</para>
|
||||
|
||||
<programlisting role="XML"><![CDATA[<customer xml:id="123456789">
|
||||
<account xml:id="987632567" short-desc="Savings">
|
||||
<customer xml:id="123456789"/>
|
||||
<balance>100.29</balance>
|
||||
</account>
|
||||
<account xml:id="985612323" short-desc="Credit Card">
|
||||
<customer xml:id="123456789"/>
|
||||
<balance>-2370.34</balance>
|
||||
</account>
|
||||
<name>
|
||||
<first-name>Gavin</first-name>
|
||||
<initial>A</initial>
|
||||
<last-name>King</last-name>
|
||||
</name>
|
||||
...
|
||||
</customer>]]></programlisting>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="xml-manipulation" revision="1">
|
||||
<title>Manipulating XML data</title>
|
||||
|
||||
<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"><![CDATA[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();]]></programlisting>
|
||||
|
||||
<programlisting role="JAVA"><![CDATA[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();]]></programlisting>
|
||||
|
||||
<para>
|
||||
When implementing XML-based data import/export, it is useful to combine this feature with Hibernate's <literal>replicate()</literal>
|
||||
operation.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
Loading…
Reference in New Issue