[hibernate-commits] Hibernate SVN: r20147 - in core/trunk/documentation/quickstart/src/main/docbook/en-US/content: extras and 1 other directory.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Sun Aug 15 19:30:03 EDT 2010
Author: misty at redhat.com
Date: 2010-08-15 19:30:03 -0400 (Sun, 15 Aug 2010)
New Revision: 20147
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
Log:
Line edits regarding HHH-5441
Added: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml
===================================================================
--- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml (rev 0)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml 2010-08-15 23:30:03 UTC (rev 20147)
@@ -0,0 +1,48 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+<modelVersion>4.0.0</modelVersion>
+
+<groupId>org.hibernate.tutorials</groupId>
+<artifactId>hibernate-tutorial-native</artifactId>
+<version>1.0.0-SNAPSHOT</version>
+<name>Hibernate Native Tutorial</name>
+
+<build>
+ <!-- we dont want the version to be part of the generated war file name -->
+ <finalName>${artifactId}</finalName>
+</build>
+
+<dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-core</artifactId>
+ </dependency>
+
+ <!-- Because this is a web app, we also have a dependency on the servlet api. -->
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ </dependency>
+
+ <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-simple</artifactId>
+ </dependency>
+
+ <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
+ <dependency>
+ <groupId>javassist</groupId>
+ <artifactId>javassist</artifactId>
+ </dependency>
+
+ <!-- The tutorial uses the H2 in-memory database -->
+ <dependency>
+ <groupId>com.h2database</groupId>
+ <artifactId>h2</artifactId>
+ </dependency>
+</dependencies>
+
+</project>
\ No newline at end of file
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-15 15:51:53 UTC (rev 20146)
+++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-15 23:30:03 UTC (rev 20147)
@@ -6,18 +6,18 @@
<note>
<para>
- This tutorial will use the "standard layout" advocated by many build tools and best practices.
- <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>
- provides a good description of the "standard layout" if you are unfamiliar.
+ This tutorial uses the <phrase>standard layout</phrase> described in
+ <ulink
+ url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>.
</para>
</note>
<tip>
<para>
- The tutorials in this guide utilize Maven, taking advantage of its transitive dependency management
- capabilities as well as the ability of many IDEs to automatically set up a project based on the Maven
- descriptor. Just be aware that it is not a requirement to use Maven as your build tool in order to use
- Hibernate.
+ The tutorials in this guide use Maven, which includes superior
+ transitive dependency management capabilities and is easy to use
+ with many integrated development environments (IDEs). You can use
+ another build tool, adapting the examples to fit your needs.
</para>
</tip>
@@ -27,59 +27,13 @@
<step id="hibernate-gsg-tutorial-native-pom">
<title>Create the Maven POM file</title>
<para>
- Create a file named <filename>pom.xml</filename> in the root of your project directory with the
- following contents
+ Create a file named <filename>pom.xml</filename> in the root of
+ your project directory, containing the the text in <xref
+ linkend="hibernate-gsg-tutorial-native-pom-ex1" />.
</para>
<example id="hibernate-gsg-tutorial-native-pom-ex1">
<title><filename>pom.xml</filename></title>
- <programlisting role="XML"><![CDATA[<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>org.hibernate.tutorials</groupId>
- <artifactId>hibernate-tutorial-native</artifactId>
- <version>1.0.0-SNAPSHOT</version>
- <name>Hibernate Native Tutorial</name>
-
- <build>
- <!-- we dont want the version to be part of the generated war file name -->
- <finalName>${artifactId}</finalName>
- </build>
-
- <dependencies>
- <dependency>
- <groupId>org.hibernate</groupId>
- <artifactId>hibernate-core</artifactId>
- </dependency>
-
- <!-- Because this is a web app, we also have a dependency on the servlet api. -->
- <dependency>
- <groupId>javax.servlet</groupId>
- <artifactId>servlet-api</artifactId>
- </dependency>
-
- <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
- <dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-simple</artifactId>
- </dependency>
-
- <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
- <dependency>
- <groupId>javassist</groupId>
- <artifactId>javassist</artifactId>
- </dependency>
-
- <!-- The tutorial uses the H2 in-memory database -->
- <dependency>
- <groupId>com.h2database</groupId>
- <artifactId>h2</artifactId>
- </dependency>
- </dependencies>
-
-</project>]]></programlisting>
+ <programlisting role="XML"><xi:include href="extras/example-pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
</step>
@@ -87,68 +41,36 @@
<title>Create the entity Java class</title>
<para>
- Create a file named <filename>src/main/java/org/hibernate/tutorial/native/Event.java</filename>
- with the following contents:
+ Create a file named <filename>src/main/java/org/hibernate/tutorial/native/Event.java</filename>, containing the text in <xref linkend="hibernate-gsg-tutorial-native-entity-ex1" />.
</para>
<example id="hibernate-gsg-tutorial-native-entity-ex1">
<title><filename>Entity.java</filename></title>
- <programlisting role="JAVA"><![CDATA[package org.hibernate.tutorial.native;
-
- import java.util.Date;
-
- public class Event {
- private Long id;
-
- private String title;
- private Date date;
-
- public Event() {}
-
- public Long getId() {
- return id;
- }
-
- private void setId(Long id) {
- this.id = id;
- }
-
- public Date getDate() {
- return date;
- }
-
- public void setDate(Date date) {
- this.date = date;
- }
-
- public String getTitle() {
- return title;
- }
-
- public void setTitle(String title) {
- this.title = title;
- }
- }]]></programlisting>
+ <programlisting role="JAVA"><xi:include href="extras/example-entity.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
<para>
<!-- todo : what's the best way to refer to content in other books? -->
<!-- like here it would be nice to say something like: -->
<!-- "Entity class requirements are covered in detail in <x.y.z Some Developer Guide Chapter/Section>" -->
- A few things to notice about the entity
<itemizedlist>
+ <title>Notes About the Entity</title>
<listitem>
<para>
- This class uses standard JavaBean naming conventions for property getter and setter
- methods, as well as private visibility for the fields. Although this is the
- recommended design, it is not required.
+ This class uses standard JavaBean naming conventions
+ for property getter and setter methods, as well as
+ private visibility for the fields. Although this is
+ the recommended design, it is not required.
</para>
</listitem>
<listitem>
<para>
- The no-argument constructor (also a JavaBean convention) is a requirement for all
- persistent classes. Hibernate has to create objects for you, using Java Reflection. The
- constructor could be private, however package or public visibility is required for runtime
- proxy generation and efficient data retrieval without bytecode instrumentation.
+ The no-argument constructor, which is also a JavaBean
+ convention, is a requirement for all persistent
+ classes. Hibernate needs to create objects for you,
+ using Java Reflection. The constructor can be
+ private. However, package or public visibility is
+ required for runtime proxy generation and efficient
+ data retrieval without bytecode instrumentation.
</para>
</listitem>
</itemizedlist>
@@ -159,107 +81,118 @@
<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 following contents:
+ Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>, with the contents in <xref linkend="example-Event.hbm.xml" />.
</para>
<example>
<title><filename>Event.hbm.xml</filename></title>
- <programlisting role="XML"><![CDATA[
-<hibernate-mapping package="org.hibernate.tutorial.native">
-
- <class name="Event" table="EVENTS">
- <id name="id" column="EVENT_ID">
- <generator class="enhanced-sequence"/>
- </id>
- <property name="date" type="timestamp" column="EVENT_DATE"/>
- <property name="title"/>
- </class>
-
-</hibernate-mapping>]]></programlisting>
+ <programlisting role="XML"><xi:include href="extras/example-Event.hbm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" /></programlisting>
</example>
<para>
- Hibernate needs to know how to load and store objects of the persistent class. This is where the
- "mapping metadata" comes into play. The Hibernate mapping file is one choice for providing Hibernate
- with this metadata.
+ Hibernate uses the mapping metadata to find out how to load and
+ store objects of the persistent class. The Hibernate mapping
+ file is one choice for providing Hibernate with this metadata.
</para>
+ <orderedlist>
+ <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 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.
+ </para>
+ </listitem>
+ </orderedlist>
+
<para>
- The <literal>class</literal> element here is doing 2 things.
- <orderedlist>
- <listitem>
- <para>
- The <literal>class</literal> attribute (here combined with the <literal>package</literal>
- attribute from the containing <literal>hibernate-mapping</literal> element) names the FQN
- of the class we 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.
- </para>
- </listitem>
- </orderedlist>
+ 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.
</para>
- <para>
- Instances of <classname>Event</classname> are now "mapped" to rows in the <literal>EVENTS</literal> table.
- But an assumption there is that Hibernate knows how to uniquely identify rows in the table. This is the
- purpose of the <literal>id</literal> element. It names the column(s) which uniquely identify each row.
- </para>
- <note>
+ <important>
<para>
- It is not strictly necessary that the <literal>id</literal> element map to the table's
- actual primary key column(s); however that is the normal convention. Nor is it strictly
- necessary that tables mapped in Hibernate even define primary keys, the Hibernate team
- <emphasis>highly</emphasis> recommends all schemas define proper referential integrity.
- Therefore <literal>id</literal> and primary key are used interchangeably throughout Hibernate
- documentation.
+ 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.
</para>
- </note>
+ </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. Further, it names the <literal>id</literal> property of
- the <classname>Event</classname> class is the property to hold the identifier value.
+ 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.
</para>
<para>
- In regards to the <literal>generator</literal> element nested inside the <literal>id</literal> element,
- for now just be aware that it tells Hibernate the strategy used to generated primary key values for
- this entity. Here we are telling it to use a sequence-like value generation.
+ 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.
</para>
<para>
- The 2 <literal>property</literal> elements are declaring the remaining 2 properties of the
- <classname>Event</classname> class: <literal>date</literal> and <literal>title</literal>. Notice
- that the <literal>date</literal> property mapping include the <literal>column</literal>
- attribute, but the <literal>title</literal> does not. Without the <literal>column</literal>
- attribute, Hibernate by default uses the property name as the column name. This works for
- <literal>title</literal>, however, <literal>date</literal> is a reserved keyword in most databases
- so you will need to explicitly tell Hibernate the column name in this case.
+ 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 absense 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.
</para>
<para>
- The <literal>title</literal> mapping also lacks a <literal>type</literal> attribute. The
- types declared and used in the mapping files are not Java data types; they are not SQL
- database types either. These types are called <emphasis>Hibernate mapping types</emphasis>,
- converters which can translate from Java to SQL data types and vice versa. Hibernate will try to
- determine the correct conversion and mapping type itself 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
- have the default you expect or need. This is the case 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 with a <literal>timestamp</literal>
- converter.
+ 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.
+ </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>
<para>
- Hibernate makes this mapping type determination using reflection when the mapping files
- are processed. This can take time and resources, so if startup performance is important
- you should 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>
-
</step>
<step id="hibernate-gsg-tutorial-native-config">
More information about the hibernate-commits
mailing list