[hibernate-commits] Hibernate SVN: r20249 - core/trunk/documentation/quickstart/src/main/docbook/en-US/content.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Tue Aug 24 11:45:32 EDT 2010
Author: steve.ebersole at jboss.com
Date: 2010-08-24 11:45:32 -0400 (Tue, 24 Aug 2010)
New Revision: 20249
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
Log:
HHH-5442 - Write native tutorial chapter
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-24 14:29:49 UTC (rev 20248)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-24 15:45:32 UTC (rev 20249)
@@ -40,8 +40,8 @@
<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"/>.
</para>
<example id="hibernate-gsg-tutorial-native-entity-ex1">
@@ -83,8 +83,8 @@
<title>Create the entity mapping file</title>
<para>
- 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"/>.
+ Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
+ containing the text in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-native-hbm-xml-ex1">
@@ -104,8 +104,8 @@
<title>Functions of the <literal>class</literal> 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 <literal>name</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>
@@ -118,32 +118,34 @@
</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
+ It is not strictly necessary for the <literal>id</literal> element to 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.
</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 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 <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 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>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 non-reserved
@@ -159,18 +161,19 @@
default mapping type for that Java type.
</para>
<para>
- In some cases this automatic detection might not have the default you expect or need, as seen with the
+ In some cases this automatic detection might not chose 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.
+ <classname>java.util.Date</classname>, should map to a SQL <database class="datatype">DATE</database>,
+ <database class="datatype">TIME</database>, or <database class="datatype">TIMESTAMP</database> datatype.
+ Full date and time information is preserved by mapping the property to a <literal>timestamp</literal>
+ converter (which identifies an instance of the class
+ <classname>org.hibernate.type.TimestampType</classname>).
</para>
<tip>
<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
+ processed. This process can take time and resources. If startup performance is important, consider
explicitly defining the type to use.
</para>
</tip>
@@ -180,7 +183,8 @@
<title>Create the Hibernate configuration file</title>
<para>
- Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> with the following contents:
+ Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> containing the text in
+ <xref linkend="hibernate-gsg-tutorial-native-config-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-native-config-ex1">
@@ -189,19 +193,20 @@
</example>
<para>
- The first few <literal>property</literal> are defining JDBC connection information. These tutorials
+ The first few <literal>property</literal> elements define JDBC connection information. These tutorials
utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode.
The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many
connections
to pool.
</para>
- <caution>
+ <warning>
<para>
The built-in Hibernate connection pool is in no way intended for production use. It
- lacks several features found on any decent connection pool.
+ lacks several features found on any decent connection pool. See the section "JDBC Connections" in
+ the "Database Access" chapter of the "Hibernate Developer Guide" for further information.
</para>
- </caution>
+ </warning>
<para>
The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate.
@@ -210,7 +215,8 @@
<tip>
<para>
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
- your application targets multiple databases.
+ your application targets multiple databases. See the section "Database Dialects" in the
+ "Database Access" chapter of the "Hibernate Developer Guide" for further information.
</para>
</tip>
More information about the hibernate-commits
mailing list