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

Doc'd new mapping elements and attributes 

git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@5283 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Christian Bauer 2005-01-24 00:08:45 +00:00
parent e36b59f776
commit 20a4ed79a0
1 changed files with 126 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
reference/en/modules/basic_mapping.xml
View File

@ -195,7 +195,7 @@
</sect2> </sect2>
<sect2 id="mapping-declaration-class" revision="2"> <sect2 id="mapping-declaration-class" revision="3">
<title>class, dynamic-class</title> <title>class, dynamic-class</title>
<para> <para>
@ -247,8 +247,8 @@
entity-name="EntityName" entity-name="EntityName"
catalog="catalog" catalog="catalog"
check="arbitrary sql check condition" check="arbitrary sql check condition"
rowid="TODO" rowid="rowid"
subselect="TODO" subselect="SQL expression"
abstract="true|false" abstract="true|false"
/>]]></programlisting> />]]></programlisting>
<calloutlist> <calloutlist>
@ -356,7 +356,12 @@
</callout> </callout>
<callout arearefs="class17"> <callout arearefs="class17">
<para> <para>
<literal>entity-name</literal> (optional): TODO <literal>entity-name</literal> (optional): Hibernate3 supports class-less persistence:
use the <literal>&lt;dynamic-class&gt;</literal> instead of a <literal>&lt;class&gt;</literal>
mapping and an <literal>entity-name</literal> attribute instead of a class name. This
allows you to implement your domain model using maps of maps or any other dynamic
approach. See <xref linkend="persistent-classes-dynamic"/> for more information.
</para> </para>
</callout> </callout>
<callout arearefs="class18"> <callout arearefs="class18">
@ -373,12 +378,17 @@
</callout> </callout>
<callout arearefs="class20"> <callout arearefs="class20">
<para> <para>
<literal>rowid</literal> (optional): TODO <literal>rowid</literal> (optional): Hibernate can use so called ROWIDs on databases
which support. E.g. on Oracle, Hibernate can use the <literal>rowid</literal> extra
column for fast updates if you set this option to <literal>rowid</literal>. A ROWID
is an implementation detail and represents the physical location of a stored tuple.
</para> </para>
</callout> </callout>
<callout arearefs="class21"> <callout arearefs="class21">
<para> <para>
<literal>subselect</literal> (optional): TODO <literal>subselect</literal> (optional): Maps an immutable and read-only entity
to a database subselect. Useful if you want to have a view instead of a base table,
but don't. See below for more information.
</para> </para>
</callout> </callout>
<callout arearefs="class22"> <callout arearefs="class22">
@ -442,7 +452,8 @@
<para> <para>
Use of <literal>select-before-update</literal> will usually decrease performance. It is very Use of <literal>select-before-update</literal> will usually decrease performance. It is very
useful to prevent a database update trigger being called unnecessarily. useful to prevent a database update trigger being called unnecessarily if you reattach a
graph of detached instances to a <literal>Session</literal>.
</para> </para>
<para> <para>
@ -462,7 +473,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<literal>dirty</literal> check the changed columns <literal>dirty</literal> check the changed columns, allowing some concurrent updates
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -475,15 +486,34 @@
We <emphasis>very</emphasis> strongly recommend that you use version/timestamp We <emphasis>very</emphasis> strongly recommend that you use version/timestamp
columns for optimistic locking with Hibernate. This is the optimal strategy with columns for optimistic locking with Hibernate. This is the optimal strategy with
respect to performance and is the only strategy that correctly handles modifications respect to performance and is the only strategy that correctly handles modifications
made to detached instances (ie. when <literal>Session.update()</literal> is used). made to detached instances (ie. when <literal>Session.merge()</literal> is used).
</para> </para>
<para> <para>
TODO: Document entity name and dynamic class There is no difference between a view and a base table for a Hibernate mapping, as
expected this is transparent at the database level (note that some DBMS don't support
views properly, especially with updates). Sometimes you want to use a view, but can't
create one in the database (ie. with a legacy schema). In this case, you can map an
immutable and read-only entity to a given SQL subselect expression:
</para> </para>
<programlisting><![CDATA[<class name="Being" mutable="false">
<subselect>
select id, name as ident, address as loc, 'human' as species from humans
union
select id, ident, planet as loc, species from aliens
</subselect>
<synchronize table="humans"/>
<synchronize table="aliens"/>
...]]></programlisting>
<para> <para>
TODO: Document subselect and and synchronize for view simulation Declare the tables to synchronize this entity, to ensure that auto-flush happens
correctly, and that queries against the derived entity do not return stale data.
The <literal>&lt;subselect&gt;</literal> is available as both an attribute and
a nested mapping element.
</para> </para>
</sect2> </sect2>
@ -1108,7 +1138,7 @@
</sect2> </sect2>
<sect2 id="mapping-declaration-property" revision="1"> <sect2 id="mapping-declaration-property" revision="2">
<title>property</title> <title>property</title>
<para> <para>
@ -1266,7 +1296,24 @@
</para> </para>
<para> <para>
TODO: Document the nested column formula="" attribute with an example An especially powerful feature are derived properties. These properties are by
definition read-only, the property value is computed at load time. You declare
the computation as a SQL expression, this translates to a <literal>SELECT</literal>
clause subquery in the SQL query that loads an instance:
</para>
<programlisting><![CDATA[
<property name="totalPrice"
formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
WHERE li.productId = p.productId
AND li.customerId = customerId
AND li.orderNumber = orderNumber )"/>]]></programlisting>
<para>
Note that you can reference the entities own table by not declaring an alias on
a particular column (<literal>customerId</literal> in the given example). Also note
that you can use the nested <literal>&lt;formula&gt;</literal> mapping element
if you don't like to use the attribute.
</para> </para>
</sect2> </sect2>
@ -1738,7 +1785,7 @@
</sect2> </sect2>
<sect2 id="mapping-declaration-joinedsubclass" revision="2"> <sect2 id="mapping-declaration-joinedsubclass" revision="3">
<title>joined-subclass</title> <title>joined-subclass</title>
<para> <para>
@ -1765,7 +1812,7 @@
catalog="catalog" catalog="catalog"
extends="SuperclassName" extends="SuperclassName"
persister="ClassName" persister="ClassName"
subselect="TODO"> subselect="SQL expression">
<key .... > <key .... >
@ -1798,10 +1845,6 @@
</calloutlist> </calloutlist>
</programlistingco> </programlistingco>
<para>
TODO
</para>
<para> <para>
No discriminator column is required for this mapping strategy. Each subclass must, No discriminator column is required for this mapping strategy. Each subclass must,
however, declare a table column holding the object identifier using the however, declare a table column holding the object identifier using the
@ -1830,8 +1873,8 @@
<one-to-many class="Cat"/> <one-to-many class="Cat"/>
</set> </set>
<joined-subclass name="DomesticCat" table="DOMESTIC_CATS"> <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
<key column="CAT"/> <key column="CAT"/>
<property name="name" type="string"/> <property name="name" type="string"/>
</joined-subclass> </joined-subclass>
</class> </class>
@ -1843,7 +1886,7 @@
</sect2> </sect2>
<sect2 id="mapping-declaration-unionsubclass"> <sect2 id="mapping-declaration-unionsubclass" revision="1">
<title>union-subclass</title> <title>union-subclass</title>
<para> <para>
@ -1852,7 +1895,8 @@
persistent state of the class, including inherited state. In Hibernate, it is persistent state of the class, including inherited state. In Hibernate, it is
not absolutely necessary to explicitly map such inheritance hierarchies. You not absolutely necessary to explicitly map such inheritance hierarchies. You
can simply map each class with a separate <literal>&lt;class&gt;</literal> can simply map each class with a separate <literal>&lt;class&gt;</literal>
declaration. However, if you wish use polymorphic associations, you need to declaration. However, if you wish use polymorphic associations (e.g. an association
directed at the superclass of your hierarchy), you need to
use the <literal>&lt;union-subclass&gt;</literal> mapping. use the <literal>&lt;union-subclass&gt;</literal> mapping.
</para> </para>
@ -1862,14 +1906,6 @@
<area id="unionsubclass2" coords="3 45"/> <area id="unionsubclass2" coords="3 45"/>
<area id="unionsubclass3" coords="4 45"/> <area id="unionsubclass3" coords="4 45"/>
<area id="unionsubclass4" coords="5 45"/> <area id="unionsubclass4" coords="5 45"/>
<area id="unionsubclass5" coords="6 45"/>
<area id="unionsubclass6" coords="7 45"/>
<area id="unionsubclass7" coords="8 45"/>
<area id="unionsubclass8" coords="9 45"/>
<area id="unionsubclass9" coords="10 45"/>
<area id="unionsubclass10" coords="11 45"/>
<area id="unionsubclass11" coords="12 45"/>
<area id="unionsubclass12" coords="13 45"/>
</areaspec> </areaspec>
<programlisting><![CDATA[<union-subclass <programlisting><![CDATA[<union-subclass
name="ClassName" name="ClassName"
@ -1883,7 +1919,7 @@
extends="SuperclassName" extends="SuperclassName"
abstract="true|false" abstract="true|false"
persister="ClassName" persister="ClassName"
subselect="TODO"> subselect="SQL expression">
<property .... /> <property .... />
..... .....
@ -1910,21 +1946,17 @@
<literal>lazy</literal> (optional, defaults to <literal>true</literal>): Setting <literal>lazy</literal> (optional, defaults to <literal>true</literal>): Setting
<literal>lazy="false"</literal> disables the use of lazy fetching. <literal>lazy="false"</literal> disables the use of lazy fetching.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>
</programlistingco> </programlistingco>
<para>
TODO
</para>
<para> <para>
No discriminator column or key column is required for this mapping strategy. No discriminator column or key column is required for this mapping strategy.
</para> </para>
</sect2> </sect2>
<sect2 id="mapping-declaration-join" revision="2"> <sect2 id="mapping-declaration-join" revision="3">
<title>join</title> <title>join</title>
<para> <para>
@ -1958,7 +1990,7 @@
<calloutlist> <calloutlist>
<callout arearefs="join1"> <callout arearefs="join1">
<para> <para>
<literal>tabe</literal>: The name of the joined table. <literal>table</literal>: The name of the joined table.
</para> </para>
</callout> </callout>
<callout arearefs="join2"> <callout arearefs="join2">
@ -1999,7 +2031,28 @@
</programlistingco> </programlistingco>
<para> <para>
TODO: Document join with an example For example, the address information for a person can be mapped to a separate
table (while preserving value type semantics for all properties):
</para>
<programlisting><![CDATA[<class name="Person"
table="PERSON">
<id name="id" column="PERSON_ID">...</id>
<join table="ADDRESS">
<key column="ADDRESS_ID"/>
<property name="address"/>
<property name="zip"/>
<property name="country"/>
</join>
...]]></programlisting>
<para>
This feature is often only useful for legacy data models, we recommend fewer
tables than classes and a fine-grained domain model. However, it is useful
for switching between inheritance mapping strategies in a single hierarchy, as
explained later.
</para> </para>
</sect2> </sect2>
@ -2483,23 +2536,24 @@
</sect1> </sect1>
<sect1 id="mapping-modularfiles" revision="2"> <sect1 id="mapping-modularfiles" revision="3">
<title>Modular mapping files</title> <title>Modular mapping files</title>
<para> <para>
It is possible to define <literal>subclass</literal> and <literal>joined-subclass</literal> It is possible to define <literal>subclass</literal>, <literal>union-subclass</literal>,
mappings in seperate mapping documents, directly beneath <literal>hibernate-mapping</literal>. and <literal>joined-subclass</literal> mappings in seperate mapping documents, directly beneath
This allows you to extend a class hierachy just by adding a new mapping file. You must <literal>hibernate-mapping</literal>. This allows you to extend a class hierachy just by adding
specify an <literal>extends</literal> attribute in the subclass mapping, naming a previously a new mapping file. You must specify an <literal>extends</literal> attribute in the subclass mapping,
mapped superclass. Note: Previously this feature made the ordering of the mapping documents important. Since Hibernate 3, the naming a previously mapped superclass. Note: Previously this feature made the ordering of the mapping
ordering of mapping files does not matter when using the extends keyword. The ordering inside a single mapping file documents important. Since Hibernate 3, the ordering of mapping files does not matter when using the
still needs to be defined as superclasses before subclasses. extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses
before subclasses.
</para> </para>
<programlisting><![CDATA[ <programlisting><![CDATA[
<hibernate-mapping> <hibernate-mapping>
<subclass name="eg.subclass.DomesticCat" extends="eg.Cat" discriminator-value="D"> <subclass name="eg.subclass.DomesticCat" extends="eg.Cat" discriminator-value="D">
<property name="name" type="string"/> <property name="name" type="string"/>
</subclass> </subclass>
</hibernate-mapping>]]></programlisting> </hibernate-mapping>]]></programlisting>
</sect1> </sect1>
@ -2625,5 +2679,26 @@ public class Cat {
</sect1> </sect1>
<sect1 id="mapping-annotations">
<title>Using JDK 5.0 Annotations</title>
<para>
JDK 5.0 introduced XDoclet-style annotations at the language level, type-safe and
checked at compile time. This mechnism is more powerful than XDoclet annotations and
better supported by tools and IDEs. IntelliJ IDEA, for example, supports auto-completion
and syntax highlighting of JDK 5.0 annotations. The new revision of the EJB specification
(JSR-220) uses JDK 5.0 annotations as the primary metadata mechanism for entity beans.
Hibernate3 implements the <literal>EntityManager</literal> of JSR-220 (the persistence API),
support for mapping metadata is available via the <emphasis>Hibernate Annotations</emphasis>
package, as a separate download. Both EJB3 (JSR-220) and Hibernate3 metadata is supported.
</para>
<para>
Note that support for JDK 5.0 Annotations (and JSR-220) is still work in progress and
not completed.
</para>
</sect1>
</chapter> </chapter>