Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-7493 : Documentation still refers to dom4j as an entity mode

This commit is contained in:
Gail Badner 2012-08-08 00:52:13 -07:00
parent b810f1049f
commit e422250076
5 changed files with 12 additions and 304 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
documentation/src/main/docbook/devguide/en-US/appendix-Configuration_Properties.xml
View File

@ -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>

1
documentation/src/main/docbook/manual/en-US/HIBERNATE_-_Relational_Persistence_for_Idiomatic_Java.xml
View File

@ -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" />

7
documentation/src/main/docbook/manual/en-US/content/configuration.xml
View File

@ -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,8 +408,9 @@ 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>,
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>

9
documentation/src/main/docbook/manual/en-US/content/persistent_classes.xml
View File

@ -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>

288
documentation/src/main/docbook/manual/en-US/content/xml.xml
View File

@ -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>&lt;one-to-many&gt;</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>