4:10 p.m.
Author: steve.ebersole(a)jboss.com
Date: 2010-08-16 17:10:23 -0400 (Mon, 16 Aug 2010)
New Revision: 20152
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/hibernate.cfg.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/pom.xml
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml
Log:
HHH-5441 - Create "Getting Started Guide"
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/hibernate.cfg.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/hibernate.cfg.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/hibernate.cfg.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -0,0 +1,36 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE hibernate-configuration PUBLIC
+ "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
+ "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
+
+<hibernate-configuration>
+
+ <session-factory>
+
+ <!-- Database connection settings -->
+ <property
name="connection.driver_class">org.h2.Driver</property>
+ <property
name="connection.url">jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE</property>
+ <property name="connection.username">sa</property>
+ <property name="connection.password"></property>
+
+ <!-- JDBC connection pool (use the built-in) -->
+ <property name="connection.pool_size">1</property>
+
+ <!-- SQL dialect -->
+ <property
name="dialect">org.hibernate.dialect.H2Dialect</property>
+
+ <!-- Disable the second-level cache -->
+ <property
name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>
+
+ <!-- Echo all executed SQL to stdout -->
+ <property name="show_sql">true</property>
+
+ <!-- Drop and re-create the database schema on startup -->
+ <property name="hbm2ddl.auto">update</property>
+
+ <!-- Names the annotated entity class -->
+ <mapping class="org.hibernate.tutorial.annotations.Event"/>
+
+ </session-factory>
+
+</hibernate-configuration>
\ No newline at end of file
Added:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java 2010-08-16
21:10:23 UTC (rev 20152)
@@ -0,0 +1,47 @@
+package org.hibernate.tutorial.annotations;
+
+import java.util.Date;
+import javax.persistence.Column;
+import javax.persistence.Entity;
+import javax.persistence.Id;
+import javax.persistence.Table;
+import javax.persistence.Temporal;
+import javax.persistence.TemporalType;
+
+@Entity
+@Table( name = "EVENTS" )
+public class Event {
+ private Long id;
+
+ private String title;
+ private Date date;
+
+ public Event() {}
+
+ @Id
+ public Long getId() {
+ return id;
+ }
+
+ private void setId(Long id) {
+ this.id = id;
+ }
+
+ @Temporal(TemporalType.TIMESTAMP)
+ @Column(name = "EVENT_DATE")
+ 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;
+ }
+}
\ No newline at end of file
Copied:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/pom.xml
(from rev 20151,
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml)
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/pom.xml
(rev 0)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/pom.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -0,0 +1,37 @@
+<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-annotations</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <name>Hibernate Annotations Tutorial</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-core</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/extras/examples/hbm/hibernate.cfg.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml 2010-08-16
18:42:39 UTC (rev 20151)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -28,7 +28,7 @@
<!-- Drop and re-create the database schema on startup -->
<property name="hbm2ddl.auto">update</property>
- <mapping
resource="org/hibernate/tutorial/native/domain/Event.hbm.xml"/>
+ <mapping resource="org/hibernate/tutorial/hbm/Event.hbm.xml"/>
</session-factory>
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml 2010-08-16
18:42:39 UTC (rev 20151)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -1,4 +1,3 @@
-<![CDATA[
<hibernate-mapping package="org.hibernate.tutorial.hbm">
<class name="Event" table="EVENTS">
@@ -10,4 +9,3 @@
</class>
</hibernate-mapping>
-]]>
Modified:
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml 2010-08-16
18:42:39 UTC (rev 20151)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -1,50 +1,37 @@
-<![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">
+ 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>
+ <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>
+ <groupId>org.hibernate.tutorials</groupId>
+ <artifactId>hibernate-tutorial-hbm</artifactId>
+ <version>1.0.0-SNAPSHOT</version>
+ <name>Hibernate hbm.xml 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>
-<dependencies>
- <dependency>
- <groupId>org.hibernate</groupId>
- <artifactId>hibernate-core</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>
- <!-- 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 gives you a choice of bytecode providers between cglib and
javassist -->
+ <dependency>
+ <groupId>javassist</groupId>
+ <artifactId>javassist</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>
+ <!-- The tutorial uses the H2 in-memory database -->
+ <dependency>
+ <groupId>com.h2database</groupId>
+ <artifactId>h2</artifactId>
+ </dependency>
+ </dependencies>
- <!-- 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_annotations.xml
===================================================================
---
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-16
18:42:39 UTC (rev 20151)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -2,16 +2,107 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="hibernate-gsg-tutorial-annotations">
- <title>Tutorial Using Native Hibernate APIs and annotations</title>
+ <title>Tutorial Using Native Hibernate APIs and Annotation
Mappings</title>
- <para>
- This tutorial introduces some key concepts of the native Hibernate API.
- </para>
- <itemizedlist>
- <listitem>
+ <procedure>
+ <title>Steps</title>
+
+ <step id="hibernate-gsg-tutorial-annotations-pom">
+ <title>Create the Maven POM file</title>
<para>
+ Create a file named <filename>pom.xml</filename> in the root
of your project directory, containing
+ the text in<xref
linkend="hibernate-gsg-tutorial-annotations-pom-ex1"/>.
+ </para>
+ <example id="hibernate-gsg-tutorial-annotations-pom-ex1">
+ <title>
+ <filename>pom.xml</filename>
+ </title>
+ <programlisting role="XML"><xi:include
href="extras/examples/annotations/pom.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"
parse="text"/></programlisting>
+ </example>
+ </step>
+ <step id="hibernate-gsg-tutorial-native-entity">
+ <title>Create the annotated entity Java class</title>
+
+ <para>
+ Create a file
named<filename>src/main/java/org/hibernate/tutorial/annotations/Event.java</filename>,
+ containing the text in<xref
linkend="hibernate-gsg-tutorial-annotations-entity-ex1"/>.
</para>
- </listitem>
- </itemizedlist>
+
+ <example id="hibernate-gsg-tutorial-annotations-entity-ex1">
+ <title>
+ <filename>Entity.java</filename>
+ </title>
+ <programlisting role="JAVA"><xi:include
href="extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java"
xmlns:xi="http://www.w3.org/2001/XInclude"
parse="text"/></programlisting>
+ </example>
+ <para>
+ <itemizedlist>
+ <title>Notes About the Entity</title>
+ <listitem>
+ <para>
+ The entity class is still using JavaBean conventions. In
fact the class itself is exactly
+ the same as we saw in <xref
linkend="hibernate-gsg-tutorial-native-entity-ex1"/>, the only
+ difference being the use of annotations to provide the
metadata instead of a separate
+ <filename>hbm.xml</filename> file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The
<interfacename>(a)javax.persistence.Entity</interfacename> annotation is used to
mark a
+ class as an entity. It's function is essentially the
same as the <literal>class</literal>
+ mapping element we see in <xref
linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
+ Additionally the
<interfacename>(a)javax.persistence.Table</interfacename> annotation is
+ used to override the default table name annotations would
have used (<literal>EVENT</literal>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+
<interfacename>(a)javax.persistence.Id</interfacename> marks the property
defining the
+ entity's identifier.
+ </para>
+ <note>
+ <para>
+ Property-related annotations are allowed on either the
field or the getter method.
+ However, for a given entity they cannot be mixed. The
placement of the
+
<interfacename>(a)javax.persistence.Id</interfacename> indicates where
Hibernate
+ should expect to find other property-related
annotations.
+ </para>
+ </note>
+ </listitem>
+ <!-- todo : example of defining the generator -->
+ <listitem>
+ <para>
+ Just as in <xref
linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>, the
+ <literal>date</literal> property needs special
handling to account for its special naming
+ and its SQL type.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </step>
+
+ <step id="hibernate-gsg-tutorial-annotations-config">
+ <title>Create the Hibernate configuration file</title>
+
+ <para>
+ Create a file named
<filename>src/main/resources/hibernate.cfg.xml</filename> with the following
contents:
+ </para>
+
+ <example id="hibernate-gsg-tutorial-annotations-config-ex1">
+
<title><filename>hibernate.cfg.xml</filename></title>
+ <programlisting role="XML"><xi:include
href="extras/examples/annotations/hibernate.cfg.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"
parse="text"/></programlisting>
+ </example>
+
+ <para>
+ Most of the contents are exactly the same as in <xref
linkend="hibernate-gsg-tutorial-native-config-ex1"/>.
+ The single difference is the <literal>mapping</literal>
element at the very end naming the
+ annotated entity class using the <literal>class</literal>
attribute.
+ </para>
+ </step>
+
+ <!-- the rest of the tutorial "here on out" is the same as from the
native + hbm.xml -->
+ <!-- todo : is it enough to say that? -->
+
+ </procedure>
+
</chapter>
\ 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-16
18:42:39 UTC (rev 20151)
+++
core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-16
21:10:23 UTC (rev 20152)
@@ -2,13 +2,11 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="hibernate-gsg-tutorial-native">
- <title>Tutorial Using Native Hibernate APIs and
<filename>hbm.xml</filename> mappings</title>
+ <title>Tutorial Using Native Hibernate APIs and
<filename>hbm.xml</filename> Mappings</title>
<note>
<para>
- This tutorial uses the
- <phrase>standard layout</phrase>
- described in
+ This tutorial uses the <phrase>standard layout</phrase> described
in
<ulink
url="http://maven.apache.org/guides/introduction/introduction-to-the...;.
</para>
</note>