diff --git a/documentation/quickstart/pom.xml b/documentation/quickstart/pom.xml
index 3ad836dd75..50817d4c94 100644
--- a/documentation/quickstart/pom.xml
+++ b/documentation/quickstart/pom.xml
@@ -117,4 +117,22 @@ Error at xsl:text on line 111 of jar:file:/home/steve/.m2/repository/net/sf/docb
+
+
+
+ ${project.groupId}
+ hibernate-core
+ ${project.version}
+
+
+ ${project.groupId}
+ hibernate-entitymanager
+ ${project.version}
+
+
+ ${project.groupId}
+ hibernate-envers
+ ${project.version}
+
+
\ No newline at end of file
diff --git a/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml b/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
index 430365153d..154ba609db 100644
--- a/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
+++ b/documentation/quickstart/src/main/docbook/en-US/Book_Info.xml
@@ -4,7 +4,7 @@
%BOOK_ENTITIES;
]>
-
+
Hibernate Getting Started Guide
&version;
1.0
diff --git a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
index 2268d57054..ada0975451 100644
--- a/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
+++ b/documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
@@ -4,7 +4,7 @@
%BOOK_ENTITIES;
]>
-
+
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt
new file mode 100644
index 0000000000..06f0f9e023
--- /dev/null
+++ b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/compile-output.txt
@@ -0,0 +1,17 @@
+[hibernateTutorial]$ mvn compile
+[INFO] Scanning for projects...
+[INFO] ------------------------------------------------------------------------
+[INFO] Building First Hibernate Tutorial
+[INFO] task-segment: [compile]
+[INFO] ------------------------------------------------------------------------
+[INFO] [resources:resources]
+[INFO] Using default encoding to copy filtered resources.
+[INFO] [compiler:compile]
+[INFO] Compiling 2 source file to hibernateTutorial/target/classes
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 2 seconds
+[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
+[INFO] Final Memory: 5M/547M
+[INFO] ------------------------------------------------------------------------
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
new file mode 100644
index 0000000000..11396f4a8f
--- /dev/null
+++ b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/hibernate.cfg.xml
@@ -0,0 +1,35 @@
+
+
+
+
+
+
+
+
+ org.h2.Driver
+ jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE
+ sa
+
+
+
+ 1
+
+
+ org.hibernate.dialect.H2Dialect
+
+
+ org.hibernate.cache.NoCacheProvider
+
+
+ true
+
+
+ update
+
+
+
+
+
+
\ No newline at end of file
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
similarity index 83%
rename from documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml
rename to documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
index b8fed683e9..e305e7177c 100644
--- a/documentation/quickstart/src/main/docbook/en-US/content/extras/example-Event.hbm.xml
+++ b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml
@@ -1,5 +1,5 @@
+
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
similarity index 92%
rename from documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java
rename to documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
index d3a7f2491d..19502d8abd 100644
--- a/documentation/quickstart/src/main/docbook/en-US/content/extras/example-entity.java
+++ b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/Event.java
@@ -1,4 +1,4 @@
-package org.hibernate.tutorial.native;
+package org.hibernate.tutorial.hbm;
import java.util.Date;
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java
new file mode 100644
index 0000000000..3bd14068c5
--- /dev/null
+++ b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java
@@ -0,0 +1,64 @@
+package org.hibernate.tutorial.hbm;
+
+import org.hibernate.cfg.Configuration;
+import org.hibernate.Session;
+import org.hibernate.SessionFactory;
+
+import java.util.Date;
+import java.util.List;
+
+public class EventManager {
+ private final SessionFactory sessionFactory;
+
+ public static void main(String[] args) {
+ EventManager eventManager = new EventManager();
+
+ if ( args[0].equals( "store" ) ) {
+ eventManager.createAndStoreEvent( "My Event", new Date() );
+ }
+ else if (args[0].equals("list")) {
+ List events = eventManager.listEvents();
+ for (int i = 0; i < events.size(); i++) {
+ Event theEvent = (Event) events.get(i);
+ System.out.println(
+ "Event: " + theEvent.getTitle()
+ + " Time: " + theEvent.getDate()
+ );
+ }
+ }
+
+ eventManager.release();
+ }
+
+ public EventManager() {
+ sessionFactory = new Configuration()
+ .configure() // configures settings from hibernate.cfg.xml
+ .buildSessionFactory();
+ }
+
+ public void release() {
+ sessionFactory.close();
+ }
+
+ private void createAndStoreEvent(String title, Date theDate) {
+ Session session = sessionFactory.openSession();
+ session.beginTransaction();
+
+ Event theEvent = new Event();
+ theEvent.setTitle( title );
+ theEvent.setDate( theDate );
+ session.save( theEvent );
+
+ session.getTransaction().commit();
+ session.close();
+ }
+
+ private List listEvents() {
+ Session session = sessionFactory.openSession();
+ session.beginTransaction();
+ List result = session.createQuery("from Event").list();
+ session.getTransaction().commit();
+ session.close();
+ return result;
+ }
+}
\ No newline at end of file
diff --git a/documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml b/documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
similarity index 100%
rename from documentation/quickstart/src/main/docbook/en-US/content/extras/example-pom.xml
rename to documentation/quickstart/src/main/docbook/en-US/content/extras/examples/hbm/pom.xml
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 a1b6314f92..ae6efd881b 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
@@ -6,18 +6,18 @@
- This tutorial uses the standard layout described in
- .
+ This tutorial uses the
+ standard layout
+ described in
+ .
- 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.
+ The tutorials in this guide use Maven, in order to leverage its transitive dependency management
+ capabilities and its integration with many development environments (IDEs). You can use another build
+ tool, adapting the examples to fit your needs.
@@ -27,13 +27,14 @@
Create the Maven POM file
- Create a file named pom.xml in the root of
- your project directory, containing the the text in .
+ Create a file named pom.xml in the root of your project directory, containing
+ the text in.
- <filename>pom.xml</filename>
-
+
+ <filename>pom.xml</filename>
+
+
@@ -41,24 +42,27 @@
Create the entity Java class
- Create a file named src/main/java/org/hibernate/tutorial/native/Event.java, containing the text in .
+ Create a file namedsrc/main/java/org/hibernate/tutorial/hbm/Event.java,
+ containing the text in.
- <filename>Entity.java</filename>
-
+
+ <filename>Entity.java</filename>
+
+
- Notes About the Entity
+ Notes About the Entity
This class uses standard JavaBean naming conventions
for property getter and setter methods, as well as
- private visibility for the fields. Although this is
+ private visibility for the fields. Although this is
the recommended design, it is not required.
@@ -66,8 +70,8 @@
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
+ 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.
@@ -81,116 +85,95 @@
Create the entity mapping file
- Create a file named src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml, with the contents in .
+ Create a file namedsrc/main/resources/org/hibernate/tutorial/native/Event.hbm.xml,
+ with the contents in .
-
- <filename>Event.hbm.xml</filename>
-
+
+
+ <filename>Event.hbm.xml</filename>
+
+
Hibernate uses the mapping metadata to find out how to load and
- store objects of the persistent class. The Hibernate mapping
+ store objects of the persistent class. The Hibernate mapping
file is one choice for providing Hibernate with this metadata.
-
- 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 class you want to define as an entity.
-
-
-
-
- The table attribute names the database
- table which contains the data for this entity.
-
-
-
+
+ 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 class you want to define as an entity.
+
+
+
+
+ The table attribute names the database table which contains the data for
+ this entity.
+
+
+
- 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 Event 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 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.
+ 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
+ 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 to hold 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 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 two property elements declare the
- remaining two properties of the Event
- class: date and title.
- The date property mapping include the
- column attribute, but the
- title does not. In the absense 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 word for the column name.
+ 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
+ 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
+ word for the column name.
- The title mapping also lacks a
- type attribute. The types declared and used
- in the mapping files are neither Java data types nor SQL
- database types. Instead, they are Hibernate
- mapping types. 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 type
- 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, 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.
+ The title mapping also lacks a type attribute. The types
+ declared and used in the mapping files are neither Java data types nor SQL database types. Instead,
+ they are Hibernate mapping types. 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 type 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, 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.
- 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.
+ 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.
@@ -199,59 +182,25 @@
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 with the following contents:
<filename>hibernate.cfg.xml</filename>
-
-
-
-
-
-
-
-
- org.h2.Driver
- jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE
- sa
-
-
-
- 1
-
-
- org.hibernate.dialect.H2Dialect
-
-
- org.hibernate.cache.NoCacheProvider
-
-
- true
-
-
- update
-
-
-
-
-
-]]>
+
- The first few property are defining 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
+ The first few property are defining 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
+ The built-in Hibernate connection pool is in no way intended for production use. It
lacks several features found on any decent connection pool.
@@ -262,14 +211,14 @@
- In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if your
- application targets multiple databases.
+ In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
+ your application targets multiple databases.
- The hbm2ddl.auto option turns on automatic generation of
- database schemas directly into the database.
+ The hbm2ddl.auto option turns on automatic generation of database schemas directly
+ into the database.
Finally, add the mapping file(s) for persistent classes to the configuration.
@@ -279,106 +228,46 @@
Do stuff
- Create a file named src/main/java/org/hibernate/tutorial/native/EvetManager.java
+ Create a file named src/main/java/org/hibernate/tutorial/hbm/EventManager.java
with the following contents:
- <filename>EventManager.java</filename>
-
+
+ <filename>EventManager.java</filename>
+
+
- The org.hibernate.cfg.Configuration class is the first thing to notice. In this
+ The org.hibernate.cfg.Configuration class is the first thing to notice. In this
tutorial we simply configure everything via the hibernate.cfg.xml file
- discussed in .
+ discussed in.
The org.hibernate.cfg.Configuration is then used to create the
- org.hibernate.SessionFactory which is a
- thread-safe object that is instantiated once to serve the entire application.
+ org.hibernate.SessionFactory which is a thread-safe object that is
+ instantiated once to serve the entire application.
The org.hibernate.SessionFactory acts as a factory for
org.hibernate.Session instances as can be seen in the
createAndStoreEvent and listEvents methods of the
- EventManager class. A org.hibernate.Session
+ EventManager class. A org.hibernate.Session
should be thought of as a corollary to a "unit of work".
createAndStoreEvent creates a new Event object
- and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to
+ and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to
perform an INSERT on the database.
listEvents illustrates use of the Hibernate Query Language (HQL) to load all
- existing Event objects from the database. Hibernate will generate the
+ existing Event objects from the database. Hibernate will generate the
appropriate SELECT SQL, send it to the database and populate
Event objects with the result set data.
@@ -386,25 +275,7 @@ public class EventManager {
Compile the source
-
-[hibernateTutorial]$ mvn compile
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Building First Hibernate Tutorial
-[INFO] task-segment: [compile]
-[INFO] ------------------------------------------------------------------------
-[INFO] [resources:resources]
-[INFO] Using default encoding to copy filtered resources.
-[INFO] [compiler:compile]
-[INFO] Compiling 2 source file to hibernateTutorial/target/classes
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 2 seconds
-[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
-[INFO] Final Memory: 5M/547M
-[INFO] ------------------------------------------------------------------------
-
+
@@ -415,25 +286,25 @@ public class EventManager {
You should see Hibernate starting up and, depending on your configuration, lots of log output. Towards
the end, the following line will be displayed:
[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)
- This is the INSERT executed by Hibernate.
+ This is the INSERTexecuted by Hibernate.
To perform a list:
- mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.native.EventManager" -Dexec.args="list"
+ mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.native.EventManager"-Dexec.args="list"
Currently nothing will ever be output when performing the list because the database is recreated
- every time the org.hibernate.SessionFactory is created. See the
+ every time the org.hibernate.SessionFactory is created.
- Take it further! Try the following:
+ Take it further! Try the following:
@@ -442,8 +313,8 @@ public class EventManager {
- With help of the Developer Guide, add an association to the Event entity
- to model a message thread.
+ With help of the Developer Guide, add an association to the Event
+ entity to model a message thread.