[hibernate-commits] Hibernate SVN: r19616 - core/trunk/documentation/manual/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed May 26 12:19:02 EDT 2010
Author: epbernard
Date: 2010-05-26 12:19:02 -0400 (Wed, 26 May 2010)
New Revision: 19616
Modified:
core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
Log:
HHH-5149 move xml specific constructs to its dedicated section
Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml 2010-05-26 16:18:28 UTC (rev 19615)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml 2010-05-26 16:19:02 UTC (rev 19616)
@@ -371,6 +371,182 @@
<literal>Dog.hbm.xml</literal>, or if using inheritance,
<literal>Animal.hbm.xml</literal>.</para>
</section>
+
+ <section id="mapping-declaration-key">
+ <title>Key</title>
+
+ <para>The <literal><key></literal> element is featured a few
+ times within this guide. It appears anywhere the parent mapping
+ element defines a join to a new table that references the primary key
+ of the original table. It also defines the foreign key in the joined
+ table:</para>
+
+ <programlistingco role="XML">
+ <areaspec>
+ <area coords="2" id="key1" />
+
+ <area coords="3" id="key2" />
+
+ <area coords="4" id="key3" />
+
+ <area coords="5" id="key4" />
+
+ <area coords="6" id="key5" />
+
+ <area coords="7" id="key6" />
+ </areaspec>
+
+ <programlisting><key
+ column="columnname"
+ on-delete="noaction|cascade"
+ property-ref="propertyName"
+ not-null="true|false"
+ update="true|false"
+ unique="true|false"
+/></programlisting>
+
+ <calloutlist>
+ <callout arearefs="key1">
+ <para><literal>column</literal> (optional): the name of the
+ foreign key column. This can also be specified by nested
+ <literal><column></literal> element(s).</para>
+ </callout>
+
+ <callout arearefs="key2">
+ <para><literal>on-delete</literal> (optional - defaults to
+ <literal>noaction</literal>): specifies whether the foreign key
+ constraint has database-level cascade delete enabled.</para>
+ </callout>
+
+ <callout arearefs="key3">
+ <para><literal>property-ref</literal> (optional): specifies that
+ the foreign key refers to columns that are not the primary key
+ of the original table. It is provided for legacy data.</para>
+ </callout>
+
+ <callout arearefs="key4">
+ <para><literal>not-null</literal> (optional): specifies that the
+ foreign key columns are not nullable. This is implied whenever
+ the foreign key is also part of the primary key.</para>
+ </callout>
+
+ <callout arearefs="key5">
+ <para><literal>update</literal> (optional): specifies that the
+ foreign key should never be updated. This is implied whenever
+ the foreign key is also part of the primary key.</para>
+ </callout>
+
+ <callout arearefs="key6">
+ <para><literal>unique</literal> (optional): specifies that the
+ foreign key should have a unique constraint. This is implied
+ whenever the foreign key is also the primary key.</para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <para>For systems where delete performance is important, we recommend
+ that all keys should be defined
+ <literal>on-delete="cascade"</literal>. Hibernate uses a
+ database-level <literal>ON CASCADE DELETE</literal> constraint,
+ instead of many individual <literal>DELETE</literal> statements. Be
+ aware that this feature bypasses Hibernate's usual optimistic locking
+ strategy for versioned data.</para>
+
+ <para>The <literal>not-null</literal> and <literal>update</literal>
+ attributes are useful when mapping a unidirectional one-to-many
+ association. If you map a unidirectional one-to-many association to a
+ non-nullable foreign key, you <emphasis>must</emphasis> declare the
+ key column using <literal><key
+ not-null="true"></literal>.</para>
+ </section>
+
+ <section id="mapping-declaration-import">
+ <title>Import</title>
+
+ <para>If your application has two persistent classes with the same
+ name, and you do not want to specify the fully qualified package name
+ in Hibernate queries, classes can be "imported" explicitly, rather
+ than relying upon <literal>auto-import="true"</literal>. You can also
+ import classes and interfaces that are not explicitly mapped:</para>
+
+ <programlisting role="XML"><import class="java.lang.Object" rename="Universe"/></programlisting>
+
+ <programlistingco role="XML">
+ <areaspec>
+ <area coords="2" id="import1" />
+
+ <area coords="3" id="import2" />
+ </areaspec>
+
+ <programlisting><import
+ class="ClassName"
+ rename="ShortName"
+/></programlisting>
+
+ <calloutlist>
+ <callout arearefs="import1">
+ <para><literal>class</literal>: the fully qualified class name
+ of any Java class.</para>
+ </callout>
+
+ <callout arearefs="import2">
+ <para><literal>rename</literal> (optional - defaults to the
+ unqualified class name): a name that can be used in the query
+ language.</para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+
+ <note>
+ <para>This feature is unique to hbm.xml and is not supported in
+ annotations.</para>
+ </note>
+ </section>
+
+ <section id="mapping-column" revision="5">
+ <title>Column and formula elements</title>
+
+ <para>Mapping elements which accept a <literal>column</literal>
+ attribute will alternatively accept a
+ <literal><column></literal> subelement. Likewise,
+ <literal><formula></literal> is an alternative to the
+ <literal>formula</literal> attribute. For example:</para>
+
+ <programlisting role="XML"><column
+ name="column_name"
+ length="N"
+ precision="N"
+ scale="N"
+ not-null="true|false"
+ unique="true|false"
+ unique-key="multicolumn_unique_key_name"
+ index="index_name"
+ sql-type="sql_type_name"
+ check="SQL expression"
+ default="SQL expression"
+ read="SQL expression"
+ write="SQL expression"/></programlisting>
+
+ <programlisting role="XML"><formula>SQL expression</formula></programlisting>
+
+ <para>Most of the attributes on <literal>column</literal> provide a
+ means of tailoring the DDL during automatic schema generation. The
+ <literal>read</literal> and <literal>write</literal> attributes allow
+ you to specify custom SQL that Hibernate will use to access the
+ column's value. For more on this, see the discussion of <link
+ linkend="mapping-column-read-and-write">column read and write
+ expressions</link>.</para>
+
+ <para>The <literal>column</literal> and <literal>formula</literal>
+ elements can even be combined within the same property or association
+ mapping to express, for example, exotic join conditions.</para>
+
+ <programlisting role="XML"><many-to-one name="homeAddress" class="Address"
+ insert="false" update="false">
+ <column name="person_id" not-null="true" length="10"/>
+ <formula>'MAILING'</formula>
+</many-to-one></programlisting>
+ </section>
</section>
<section id="mapping-declaration-class" revision="3">
@@ -4574,155 +4750,6 @@
recommended.</para>
</section>
- <section id="mapping-declaration-key">
- <title>Key</title>
-
- <para>The <literal><key></literal> element has featured a few
- times within this guide. It appears anywhere the parent mapping element
- defines a join to a new table that references the primary key of the
- original table. It also defines the foreign key in the joined
- table:</para>
-
- <programlistingco role="XML">
- <areaspec>
- <area coords="2" id="key1" />
-
- <area coords="3" id="key2" />
-
- <area coords="4" id="key3" />
-
- <area coords="5" id="key4" />
-
- <area coords="6" id="key5" />
-
- <area coords="7" id="key6" />
- </areaspec>
-
- <programlisting><key
- column="columnname"
- on-delete="noaction|cascade"
- property-ref="propertyName"
- not-null="true|false"
- update="true|false"
- unique="true|false"
-/></programlisting>
-
- <calloutlist>
- <callout arearefs="key1">
- <para><literal>column</literal> (optional): the name of the
- foreign key column. This can also be specified by nested
- <literal><column></literal> element(s).</para>
- </callout>
-
- <callout arearefs="key2">
- <para><literal>on-delete</literal> (optional - defaults to
- <literal>noaction</literal>): specifies whether the foreign key
- constraint has database-level cascade delete enabled.</para>
- </callout>
-
- <callout arearefs="key3">
- <para><literal>property-ref</literal> (optional): specifies that
- the foreign key refers to columns that are not the primary key of
- the original table. It is provided for legacy data.</para>
- </callout>
-
- <callout arearefs="key4">
- <para><literal>not-null</literal> (optional): specifies that the
- foreign key columns are not nullable. This is implied whenever the
- foreign key is also part of the primary key.</para>
- </callout>
-
- <callout arearefs="key5">
- <para><literal>update</literal> (optional): specifies that the
- foreign key should never be updated. This is implied whenever the
- foreign key is also part of the primary key.</para>
- </callout>
-
- <callout arearefs="key6">
- <para><literal>unique</literal> (optional): specifies that the
- foreign key should have a unique constraint. This is implied
- whenever the foreign key is also the primary key.</para>
- </callout>
- </calloutlist>
- </programlistingco>
-
- <para>For systems where delete performance is important, we recommend
- that all keys should be defined <literal>on-delete="cascade"</literal>.
- Hibernate uses a database-level <literal>ON CASCADE DELETE</literal>
- constraint, instead of many individual <literal>DELETE</literal>
- statements. Be aware that this feature bypasses Hibernate's usual
- optimistic locking strategy for versioned data.</para>
-
- <para>The <literal>not-null</literal> and <literal>update</literal>
- attributes are useful when mapping a unidirectional one-to-many
- association. If you map a unidirectional one-to-many association to a
- non-nullable foreign key, you <emphasis>must</emphasis> declare the key
- column using <literal><key not-null="true"></literal>.</para>
- </section>
-
- <section id="mapping-column" revision="5">
- <title>Column and formula elements</title>
-
- <para>Mapping elements which accept a <literal>column</literal>
- attribute will alternatively accept a <literal><column></literal>
- subelement. Likewise, <literal><formula></literal> is an
- alternative to the <literal>formula</literal> attribute. For
- example:</para>
-
- <programlisting role="XML"><column
- name="column_name"
- length="N"
- precision="N"
- scale="N"
- not-null="true|false"
- unique="true|false"
- unique-key="multicolumn_unique_key_name"
- index="index_name"
- sql-type="sql_type_name"
- check="SQL expression"
- default="SQL expression"
- read="SQL expression"
- write="SQL expression"/></programlisting>
-
- <programlisting role="XML"><formula>SQL expression</formula></programlisting>
-
- <para>Most of the attributes on <literal>column</literal> provide a
- means of tailoring the DDL during automatic schema generation. The
- <literal>read</literal> and <literal>write</literal> attributes allow
- you to specify custom SQL that Hibernate will use to access the column's
- value. For more on this, see the discussion of <link
- linkend="mapping-column-read-and-write">column read and write
- expressions</link>.</para>
-
- <para>The <literal>column</literal> and <literal>formula</literal>
- elements can even be combined within the same property or association
- mapping to express, for example, exotic join conditions.</para>
-
- <programlisting role="XML"><many-to-one name="homeAddress" class="Address"
- insert="false" update="false">
- <column name="person_id" not-null="true" length="10"/>
- <formula>'MAILING'</formula>
-</many-to-one></programlisting>
- </section>
-
- <section id="mapping-declaration-import">
- <title>Import</title>
-
- <para>If your application has two persistent classes with the same name,
- and you do not want to specify the fully qualified package name in
- Hibernate queries, classes can be "imported" explicitly, rather than
- relying upon <literal>auto-import="true"</literal>. You can also import
- classes and interfaces that are not explicitly mapped:</para>
-
- <programlisting role="XML"><import class="java.lang.Object" rename="Universe"/></programlisting>
-
- <programlistingco role="XML">
- <areaspec>
- <area coords="2" id="import1" />
-
- <area coords="3" id="import2" />
- </areaspec>
-
<programlisting><import
class="ClassName"
rename="ShortName"
More information about the hibernate-commits
mailing list