[hibernate-commits] Hibernate SVN: r20200 - core/trunk/documentation/quickstart/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu Aug 19 21:01:03 EDT 2010
Author: misty at redhat.com
Date: 2010-08-19 21:01:03 -0400 (Thu, 19 Aug 2010)
New Revision: 20200
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
Log:
HHH-5541
Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-20 00:30:53 UTC (rev 20199)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-20 01:01:03 UTC (rev 20200)
@@ -13,9 +13,11 @@
<tip>
<para>
- The tutorials in this guide use Maven, in order to leverage its transitive dependency management
- capabilities and its integration with many development environments (IDEs). You can use another build
- tool, adapting the examples to fit your needs.
+ The tutorials in this guide use Maven, in order to leverage its
+ transitive dependency management capabilities and its integration
+ with many development environments (IDEs). <!--This sounds like
+ marketing! -->You can use another build tool, adapting the examples
+ to fit your needs.
</para>
</tip>
@@ -40,8 +42,11 @@
<title>Create the entity Java class</title>
<para>
- Create a file named<filename>src/main/java/org/hibernate/tutorial/hbm/Event.java</filename>,
- containing the text in<xref linkend="hibernate-gsg-tutorial-native-entity-ex1"/>.
+ Create a file named
+ <filename>src/main/java/org/hibernate/tutorial/hbm/Event.java</filename>,
+ containing the text in<xref
+ linkend="hibernate-gsg-tutorial-native-entity-ex1"/>.<!-- Can we
+ just include these files in an example.zip? -->
</para>
<example id="hibernate-gsg-tutorial-native-entity-ex1">
@@ -83,7 +88,7 @@
<title>Create the entity mapping file</title>
<para>
- Create a file named<filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
+ Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
with the contents in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
</para>
@@ -101,79 +106,104 @@
</para>
<orderedlist>
- <title>Functions of the <literal>class</literal> element</title>
+ <title>Functions of the <property>class</property> element</title>
<listitem>
<para>
- The <literal>class</literal> attribute, combined here with the <literal>package</literal>
- attribute from the containing <literal>hibernate-mapping</literal> element, names the FQN of
- the class you want to define as an entity.
+ The <literal>class</literal> attribute, combined here
+ with the <literal>package</literal> attribute from the
+ containing <literal>hibernate-mapping</literal> element,
+ names the FQN of the class you want to define as an
+ entity.
</para>
</listitem>
<listitem>
<para>
- The <literal>table</literal> attribute names the database table which contains the data for
- this entity.
+ The <literal>table</literal> attribute names the
+ database table which contains the data for this entity.
</para>
</listitem>
</orderedlist>
<para>
- Instances of <classname>Event</classname> are now mapped to rows in the <literal>EVENTS</literal>
- table. Hibernate uses the <literal>id</literal> element to uniquely identify rows in the table.
+ Instances of the <classname>Event</classname> class are now
+ mapped to rows in the <database class="table">EVENTS</database>
+ table. Hibernate uses the <literal>id</literal> element to
+ uniquely identify rows in the table.
</para>
<important>
<para>
- It is not strictly necessary that the <literal>id</literal> element map to the table's actual
- primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even
- need to define primary keys. However, the Hibernate team <emphasis>strongly</emphasis>
- recommends that all schemas define proper referential integrity. Therefore <literal>id</literal>
- and <phrase>primary key</phrase> are used interchangeably throughout Hibernate documentation.
+ It is not strictly necessary for the <literal>id</literal>
+ element to map to the table's actual primary key column(s),
+ but this type of mapping is conventional. Tables mapped in
+ Hibernate do not even need to define primary keys. However,
+ the Hibernate team <emphasis>strongly</emphasis> recommends
+ that all schemas define proper referential
+ integrity. Therefore <literal>id</literal> and
+ <phrase>primary key</phrase> are used interchangeably
+ throughout Hibernate documentation.
</para>
</important>
<para>
- The <literal>id</literal> element here identifies the <literal>EVENT_ID</literal> column as the
- primary key of the <literal>EVENTS</literal> table. It also identifies the <literal>id</literal>
- property of the <classname>Event</classname> class as the property to hold the identifier value.
+ The <literal>id</literal> element here identifies the <database
+ class="field">EVENT_ID</database> column as the primary key of
+ the <database class="table">EVENTS</database> table. It also
+ identifies the <literal>id</literal> property of the
+ <classname>Event</classname> class as the property containing
+ the identifier value.
</para>
+ <para>
+ The <literal>generator</literal> element nested inside the
+ <literal>id</literal> element informs Hibernate about which
+ strategy is used to generated primary key values for this
+ entity. In this example, a sequence-like value generation is
+ used.
+ </para>
<para>
- The important thing to be aware of about the <literal>generator</literal> element nested inside the
- <literal>id</literal> element is that it informs Hibernate which strategy is used to generated primary
- key values for this entity. In this instance, it uses a sequence-like value generation.
+ The two <literal>property</literal> elements declare the
+ remaining two properties of the <classname>Event</classname>
+ class: <literal>date</literal> and<literal>title</literal>. The
+ <literal>date</literal> property mapping includes the
+ <literal>column</literal> attribute, but the
+ <literal>title</literal> does not. In the absence of a
+ <literal>column</literal> attribute, Hibernate uses the property
+ name as the column name. This is appropriate for
+ <literal>title</literal>, but since <literal>date</literal> is a
+ reserved keyword in most databases, you need to specify a
+ different word for the column name.
</para>
<para>
- The two <literal>property</literal> elements declare the remaining two properties of the
- <classname>Event</classname> class: <literal>date</literal> and<literal>title</literal>. The
- <literal>date</literal> property mapping include the <literal>column</literal> attribute, but the
- <literal>title</literal> does not. In the absence of a <literal>column</literal> attribute, Hibernate
- uses the property name as the column name. This is appropriate for <literal>title</literal>, but since
- <literal>date</literal> is a reserved keyword in most databases, you need to specify a non-reserved
- word for the column name.
+ The <literal>title</literal> mapping also lacks a
+ <literal>type</literal> attribute. The types declared and used
+ in the mapping files are neither Java data types nor SQL
+ database types. Instead, they are <firstterm><phrase>Hibernate
+ mapping types</phrase></firstterm>. Hibernate mapping types are
+ converters which translate between Java and SQL data
+ types. Hibernate attempts to determine the correct conversion
+ and mapping type autonomously if the <literal>type</literal>
+ attribute is not present in the mapping, by using Java
+ reflection to determine the Java type of the declared property
+ and using a default mapping type for that Java type. <!-- We need to decide how we mark up XML tags (elements) and parameters (attributes). -->
</para>
<para>
- The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The types
- declared and used in the mapping files are neither Java data types nor SQL database types. Instead,
- they are <firstterm><phrase>Hibernate mapping types</phrase></firstterm>. Hibernate mapping types are
- converters which translate between Java and SQL data types. Hibernate attempts to determine the correct
- conversion and mapping type autonomously if the <literal>type</literal> attribute is not present in the
- mapping, by using Java reflection to determine the Java type of the declared property and using a
- default mapping type for that Java type.
+ In some cases this automatic detection might not choose the
+ default you expect or need, as seen with the
+ <literal>date</literal> property. Hibernate cannot know if the
+ property, which is of type
+ <classname>java.util.Date</classname>, should map to a SQL
+ <literal>DATE</literal>, <literal>TIME</literal>, or
+ <literal>TIMESTAMP</literal> datatype. Full date and time
+ information is preserved by mapping the property to a
+ <literal>timestamp</literal> converter.
</para>
- <para>
- In some cases this automatic detection might not have the default you expect or need, as seen with the
- <literal>date</literal> property. Hibernate cannot know if the property, which is of type
- <classname>java.util.Date</classname>, should map to a SQL <literal>DATE</literal>,
- <literal>TIME</literal>, or <literal>TIMESTAMP</literal> datatype. Full date and time information is
- preserved by mapping the property to a <literal>timestamp</literal>
- converter.
- </para>
- <tip>
+ <info>
<para>
- Hibernate makes this mapping type determination using reflection when the mapping files are
- processed. This can take time and resources. If startup performance is important, consider
- explicitly defining the type to use.
+ Hibernate makes this mapping type determination using
+ reflection when the mapping files are processed. This can
+ take time and resources. If startup performance is
+ important, consider explicitly defining the type to use.
</para>
- </tip>
+ </info
</step>
<step id="hibernate-gsg-tutorial-native-config">
More information about the hibernate-commits
mailing list