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

HHH-5441 - Create "Getting Started Guide" 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20152 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-16 21:10:23 +00:00
parent 54ae3b1dae
commit c2e3712ddc
8 changed files with 251 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/hibernate.cfg.xml Normal file
View File

@ -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>

47
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/org/hibernate/tutorial/annotations/Event.java Normal file
View File

@ -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;
}
}

37
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/annotations/pom.xml Normal file
View File

@ -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>

2
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
View File

@ -28,7 +28,7 @@
<!-- Drop and re-create the database schema on startup --> <!-- Drop and re-create the database schema on startup -->
<property name="hbm2ddl.auto">update</property> <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> </session-factory>

2
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
View File

@ -1,4 +1,3 @@
<![CDATA[
<hibernate-mapping package="org.hibernate.tutorial.hbm"> <hibernate-mapping package="org.hibernate.tutorial.hbm">
<class name="Event" table="EVENTS"> <class name="Event" table="EVENTS">
@ -10,4 +9,3 @@
</class> </class>
</hibernate-mapping> </hibernate-mapping>
]]>

69
documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
View File

@ -1,50 +1,37 @@
<![CDATA[
<project xmlns="http://maven.apache.org/POM/4.0.0" <project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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"> 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> <groupId>org.hibernate.tutorials</groupId>
<artifactId>hibernate-tutorial-native</artifactId> <artifactId>hibernate-tutorial-hbm</artifactId>
<version>1.0.0-SNAPSHOT</version> <version>1.0.0-SNAPSHOT</version>
<name>Hibernate Native Tutorial</name> <name>Hibernate hbm.xml Tutorial</name>
<build> <dependencies>
<!-- we dont want the version to be part of the generated war file name --> <dependency>
<finalName>${artifactId}</finalName> <groupId>org.hibernate</groupId>
</build> <artifactId>hibernate-core</artifactId>
</dependency>
<dependencies> <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
<dependency> <dependency>
<groupId>org.hibernate</groupId> <groupId>org.slf4j</groupId>
<artifactId>hibernate-core</artifactId> <artifactId>slf4j-simple</artifactId>
</dependency> </dependency>
<!-- Because this is a web app, we also have a dependency on the servlet api. --> <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
<dependency> <dependency>
<groupId>javax.servlet</groupId> <groupId>javassist</groupId>
<artifactId>servlet-api</artifactId> <artifactId>javassist</artifactId>
</dependency> </dependency>
<!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend --> <!-- The tutorial uses the H2 in-memory database -->
<dependency> <dependency>
<groupId>org.slf4j</groupId> <groupId>com.h2database</groupId>
<artifactId>slf4j-simple</artifactId> <artifactId>h2</artifactId>
</dependency> </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> </project>
]]>

109
documentation/quickstart/src/main/docbook/en-US/content/tutorial_annotations.xml
View File

@ -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"> <!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"> <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> <procedure>
This tutorial introduces some key concepts of the native Hibernate API. <title>Steps</title>
</para>
<itemizedlist> <step id="hibernate-gsg-tutorial-annotations-pom">
<listitem> <title>Create the Maven POM file</title>
<para> <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> </para>
</listitem> <example id="hibernate-gsg-tutorial-annotations-pom-ex1">
</itemizedlist> <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>
<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>@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>@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>@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>@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> </chapter>

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

@ -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"> <!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"> <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> <note>
<para> <para>
This tutorial uses the This tutorial uses the <phrase>standard layout</phrase> described in
<phrase>standard layout</phrase>
described in
<ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>. <ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>.
</para> </para>
</note> </note>