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

HHH-5442 - Write native tutorial chapter 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20249 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-24 15:45:32 +00:00
parent dd86190b17
commit adc1ab6c02
1 changed files with 35 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
View File

@ -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,12 +118,13 @@
</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
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>
@ -131,19 +132,20 @@
</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>