From adc1ab6c024b0f02ec454807d0c254236dc8c8c3 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Tue, 24 Aug 2010 15:45:32 +0000 Subject: [PATCH] HHH-5442 - Write native tutorial chapter git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20249 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../docbook/en-US/content/tutorial_native.xml | 64 ++++++++++--------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml index a833dae129..69d10fb9a1 100644 --- a/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml +++ b/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml @@ -40,8 +40,8 @@ Create the entity Java class - Create a file namedsrc/main/java/org/hibernate/tutorial/hbm/Event.java, - containing the text in. + Create a file named src/main/java/org/hibernate/tutorial/hbm/Event.java, + containing the text in . @@ -83,8 +83,8 @@ Create the entity mapping file - Create a file namedsrc/main/resources/org/hibernate/tutorial/native/Event.hbm.xml, - with the contents in . + Create a file named src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml, + containing the text in . @@ -104,8 +104,8 @@ Functions of the <literal>class</literal> element - The class attribute, combined here with the package - attribute from the containing hibernate-mapping element, names the FQN of + The name attribute (combined here with the package + attribute from the containing hibernate-mapping element) names the FQN of the class you want to define as an entity. @@ -118,32 +118,34 @@ - Instances of Event are now mapped to rows in the EVENTS - table. Hibernate uses the id element to uniquely identify rows in the table. + Instances of the Event class are now mapped to rows in the + EVENTS table. Hibernate uses the id element to + uniquely identify rows in the table. - It is not strictly necessary that the id 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 id 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 strongly recommends that all schemas define proper referential integrity. Therefore id and primary key are used interchangeably throughout Hibernate documentation. - The id element here identifies the EVENT_ID column as the - primary key of the EVENTS table. It also identifies the id - property of the Event class as the property to hold the identifier value. + The id element here identifies the EVENT_ID + column as the primary key of the EVENTS table. It also identifies + the id property of the Event class as the property + containing the identifier value. - The important thing to be aware of about the generator element nested inside the - id 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 generator element nested inside the id 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. The two property elements declare the remaining two properties of the Event class: date andtitle. The - date property mapping include the column attribute, but the + date property mapping includes the column attribute, but the title does not. In the absence of a column attribute, Hibernate uses the property name as the column name. This is appropriate for title, but since date 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. - 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 date property. Hibernate cannot know if the property, which is of type - java.util.Date, should map to a SQL DATE, - TIME, or TIMESTAMP datatype. Full date and time information is - preserved by mapping the property to a timestamp - converter. + java.util.Date, should map to a SQL DATE, + TIME, or TIMESTAMP datatype. + Full date and time information is preserved by mapping the property to a timestamp + converter (which identifies an instance of the class + org.hibernate.type.TimestampType). 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. @@ -180,7 +183,8 @@ Create the Hibernate configuration file - Create a file named src/main/resources/hibernate.cfg.xml with the following contents: + Create a file named src/main/resources/hibernate.cfg.xml containing the text in + . @@ -189,19 +193,20 @@ - The first few property are defining JDBC connection information. These tutorials + The first few property 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. - + 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. - + The dialect option specifies the particular SQL variant Hibernate should generate. @@ -210,7 +215,8 @@ 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.