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" - separate tutorial project for bundling 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20277 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Steve Ebersole 2010-08-27 21:44:03 +00:00
parent 227572cfcf
commit 1532e22327
17 changed files with 1213 additions and 375 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
documentation/quickstart/src/main/docbook/en-US/Hibernate_Getting_Started_Guide.xml
View File

@ -8,9 +8,29 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/community.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/obtaining.xml" />
<part label="I">
<title>Basic Information</title>
<partintro>
<para>
The sections in Part I present basic information you will
likely need to get started utilizing Hibernate
</para>
</partintro>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/community.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/obtaining.xml" />
</part>
<part label="II">
<title>Tutorials</title>
<partintro>
<para>
The sections in Part II dive into illustrative examples of using Hibernate in various
ways. The referenced projects and code are available for download at
<ulink url="http://sourceforge.net/projects/hibernate/files/hibernate/&version;"/>
</para>
</partintro>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_native.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" />
</part>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_native.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/tutorial_annotations.xml" />
</book>

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

@ -4,122 +4,84 @@
<chapter id="hibernate-gsg-tutorial-annotations">
<title>Tutorial Using Native Hibernate APIs and Annotation Mappings</title>
<procedure>
<title>Steps</title>
<para>
This tutorial is located within the download bundle under <filename>basic</filename> and illustrates
<itemizedlist>
<listitem>
<para>
using annotations to provide mapping information
</para>
</listitem>
<listitem>
<para>
using the <phrase>native</phrase> Hibernate APIs
</para>
</listitem>
</itemizedlist>
</para>
<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>
<section id="hibernate-gsg-tutorial-annotations-config">
<title>The Hibernate configuration file</title>
<step id="hibernate-gsg-tutorial-native-entity">
<title>Create the annotated entity Java class</title>
<para>
The contents are exactly the same as in <xref linkend="hibernate-gsg-tutorial-basic-config"/>.
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>
</section>
<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>
<section id="hibernate-gsg-tutorial-basic-entity">
<title>The annotated entity Java class</title>
<para>
The entity class in this tutorial is <classname>org.hibernate.tutorial.annotations.Event</classname>
<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-basic-entity"/>, 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 discussed in <xref linkend="hibernate-gsg-tutorial-basic-mapping"/>.
Additionally the <interfacename>@javax.persistence.Table</interfacename> annotation is
used to explicitly specify the table name (the default table name would have been
<database class="table">EVENT</database>).
</para>
</listitem>
<listitem>
<para>
<interfacename>@javax.persistence.Id</interfacename> marks the property defining the
entity's identifier. <interfacename>@javax.persistence.GeneratedValue</interfacename> and
<interfacename>@org.hibernate.annotations.GenericGenerator</interfacename> work in tandem
to indicate that Hibernate should use Hibernate's <literal>increment</literal> generation
strategy for this entity's identifier values.
</para>
</listitem>
<listitem>
<para>
Just as discussed in <xref linkend="hibernate-gsg-tutorial-basic-mapping"/>, the
<literal>date</literal> property needs special handling to account for its special naming
and its SQL type.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<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 explicitly specify the table name (the default table name would have been
<database class="table">EVENT</database>).
</para>
</listitem>
<listitem>
<para>
<interfacename>@javax.persistence.Id</interfacename> marks the property defining the
entity's identifier.
</para>
</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>
<step id="hibernate-gsg-tutorial-annotations-working">
<title>Do stuff</title>
<para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/annotations/EventManager.java</filename>
containing the text in <xref linkend="hibernate-gsg-tutorial-native-working-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-native-working-ex1">
<title>
<filename>EventManager.java</filename>
</title>
<programlisting role="JAVA"><xi:include href="extras/examples/annotations/org/hibernate/tutorial/annotations/EventManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
Refer back to <xref linkend="hibernate-gsg-tutorial-native-working"/> for a discussion
</para>
</step>
<step id="hibernate-gsg-tutorial-annotations-compileAndRun">
<title>Compile and run the code</title>
<para>
Follow the directions at <xref linkend="hibernate-gsg-tutorial-native-compile"/> and
<xref linkend="hibernate-gsg-tutorial-native-running"/> to compile and then run the code. Be sure
to reference the <classname>org.hibernate.tutorial.annotations.EventManager</classname> class
instead of the <classname>org.hibernate.tutorial.hbm.EventManager</classname> class.
</para>
</step>
</procedure>
<section id="hibernate-gsg-tutorial-annotations-test">
<title>Example code</title>
<para>
<classname>org.hibernate.tutorial.annotations.AnnotationsIllustrationTest</classname> is essentially the
same as <classname>org.hibernate.tutorial.hbm.NativeApiIllustrationTest</classname> discussed in
<xref linkend="hibernate-gsg-tutorial-basic-test"/>.
</para>
</section>
<section id="hibernate-gsg-tutorial-annotations-further">
<title>Take it further!</title>

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

@ -1,311 +1,251 @@
<?xml version='1.0' encoding='UTF-8' ?>
<!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>
<chapter id="hibernate-gsg-tutorial-basic">
<title>Tutorial Using Native Hibernate APIs and <phrase>hbm.xml</phrase> Mappings</title>
<para>
This tutorial is located within the download bundle under <filename>basic</filename> and illustrates
<itemizedlist>
<listitem>
<para>
using Hibernate mapping files (<phrase>hbm.xml</phrase>) to provide mapping information
</para>
</listitem>
<listitem>
<para>
using the <phrase>native</phrase> Hibernate APIs
</para>
</listitem>
</itemizedlist>
</para>
<section id="hibernate-gsg-tutorial-basic-config">
<title>The Hibernate configuration file</title>
<note>
<para>
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"/>.
The resource file <filename>hibernate.cfg.xml</filename> defines Hibernate configuration
information.
</para>
</note>
<tip>
<para>
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.
The first few <literal>property</literal> 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.
</para>
</tip>
<procedure>
<title>Steps</title>
<step id="hibernate-gsg-tutorial-native-pom">
<title>Create the Maven POM file</title>
<important>
<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-native-pom-ex1"/>.
The built-in Hibernate connection pool is in no way intended for production use. It
lacks several features found on any decent connection pool. See the section
<citetitle pubwork="section">JDBC Connections</citetitle> in the
<citetitle pubwork="chapter">Database Access</citetitle> chapter of the
<citetitle pubwork="book">Hibernate Developer Guide</citetitle> for further information.
</para>
<example id="hibernate-gsg-tutorial-native-pom-ex1">
<title>
<filename>pom.xml</filename>
</title>
<programlisting role="XML"><xi:include href="extras/examples/hbm/pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
</step>
</important>
<step id="hibernate-gsg-tutorial-native-entity">
<title>Create the entity Java class</title>
<para>
The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate.
</para>
<tip>
<para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/Event.java</filename>,
containing the text in <xref linkend="hibernate-gsg-tutorial-native-entity-ex1"/>.
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
your application targets multiple databases. See the section
<citetitle pubwork="section">Database Dialects</citetitle> in the
<citetitle pubwork="chapter">Database Access</citetitle> chapter of the
<citetitle pubwork="book">Hibernate Developer Guide</citetitle> for further information.
</para>
</tip>
<example id="hibernate-gsg-tutorial-native-entity-ex1">
<title>
<filename>Entity.java</filename>
</title>
<programlisting role="JAVA"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/Event.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>" -->
<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.
</para>
</listitem>
<listitem>
<para>
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>
</para>
</step>
<para>
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly
into the database.
</para>
<step id="hibernate-gsg-tutorial-native-mapping">
<title>Create the entity mapping file</title>
<para>
Finally, add the mapping file(s) for persistent classes to the configuration. The <literal>resource</literal>
attribute of the <literal>mapping</literal> element says to attempt to locate that mapping as a
classpath resource (via a <classname>java.lang.ClassLoader</classname> lookup).
</para>
<para>
Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
containing the text in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
</para>
</section>
<example id="hibernate-gsg-tutorial-native-hbm-xml-ex1">
<title>
<filename>Event.hbm.xml</filename>
</title>
<programlisting role="XML"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/Event.hbm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
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>
<section id="hibernate-gsg-tutorial-basic-entity">
<title>The entity Java class</title>
<para>
The entity class for this tutorial is <classname>org.hibernate.tutorial.hbm.Event</classname>.
<itemizedlist>
<title>Notes About the Entity</title>
<listitem>
<para>
The <literal>name</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.
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 <literal>table</literal> attribute names the database table which contains the data for
this entity.
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>
</orderedlist>
</itemizedlist>
</para>
</section>
<para>
Instances of the <classname>Event</classname> class are now mapped to rows in the
<database class="table">EVENTS</database> table. Hibernate uses the <literal>id</literal> element to
uniquely identify rows in the table.
</para>
<important>
<section id="hibernate-gsg-tutorial-basic-mapping">
<title>The mapping file</title>
<para>
The <phrase>hbm.xml</phrase> mapping file for this tutorial is the classpath resource
<filename>org/hibernate/tutorial/hbm/Event.hbm.xml</filename> as we saw in
<xref linkend="hibernate-gsg-tutorial-basic-config"/>
</para>
<para>
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>
It is not strictly necessary for the <literal>id</literal> 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 <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.
The <literal>name</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>
</important>
<para>
The <literal>id</literal> element here identifies the <database class="field">EVENT_ID</database>
column as the primary key of the <database class="table">EVENTS</database> table. It also identifies
the <literal>id</literal> property of the <classname>Event</classname> class as the property
containing the identifier value.
</para>
<para>
The <literal>generator</literal> element nested inside the <literal>id</literal> 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.
</para>
<para>
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 includes the <literal>column</literal> attribute, but the
<literal>title</literal> does not. In the absence 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 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 chose 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 <database class="datatype">DATE</database>,
<database class="datatype">TIME</database>, or <database class="datatype">TIMESTAMP</database> datatype.
Full date and time information is preserved by mapping the property to a <literal>timestamp</literal>
converter (which identifies an instance of the class
<classname>org.hibernate.type.TimestampType</classname>).
</para>
<tip>
</listitem>
<listitem>
<para>
Hibernate makes this mapping type determination using reflection when the mapping files are
processed. This process can take time and resources. If startup performance is important, consider
explicitly defining the type to use.
The <literal>table</literal> attribute names the database table which contains the data for
this entity.
</para>
</tip>
</step>
<step id="hibernate-gsg-tutorial-native-config">
<title>Create the Hibernate configuration file</title>
</listitem>
</orderedlist>
<para>
Instances of the <classname>Event</classname> class are now mapped to rows in the
<database class="table">EVENTS</database> table. Hibernate uses the <literal>id</literal> element to
uniquely identify rows in the table.
</para>
<important>
<para>
Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> containing the text in
<xref linkend="hibernate-gsg-tutorial-native-config-ex1"/>.
It is not strictly necessary for the <literal>id</literal> 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 <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>
</important>
<para>
The <literal>id</literal> element here identifies the <database class="field">EVENT_ID</database>
column as the primary key of the <database class="table">EVENTS</database> table. It also identifies
the <literal>id</literal> property of the <classname>Event</classname> class as the property
containing the identifier value.
</para>
<para>
The <literal>generator</literal> element nested inside the <literal>id</literal> element informs
Hibernate about which strategy is used to generated primary key values for this entity. In this
example, a simple incrementing count is used.
</para>
<para>
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 includes the <literal>column</literal> attribute, but the
<literal>title</literal> does not. In the absence 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 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 chose 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 <database class="datatype">DATE</database>,
<database class="datatype">TIME</database>, or <database class="datatype">TIMESTAMP</database> datatype.
Full date and time information is preserved by mapping the property to a <literal>timestamp</literal>
converter (which identifies an instance of the class
<classname>org.hibernate.type.TimestampType</classname>).
</para>
<example id="hibernate-gsg-tutorial-native-config-ex1">
<title><filename>hibernate.cfg.xml</filename></title>
<programlisting role="XML"><xi:include href="extras/examples/hbm/hibernate.cfg.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<tip>
<para>
The first few <literal>property</literal> 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.
Hibernate makes this mapping type determination using reflection when the mapping files are
processed. This process can take time and resources. If startup performance is important, consider
explicitly defining the type to use.
</para>
</tip>
<warning>
<para>
The built-in Hibernate connection pool is in no way intended for production use. It
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.
</para>
</warning>
</section>
<section id="hibernate-gsg-tutorial-basic-test">
<title>Example code</title>
<para>
The <classname>org.hibernate.tutorial.hbm.NativeApiIllustrationTest</classname> class illustrates using
the Hibernate <phrase>native API</phrase>.
</para>
<note>
<para>
The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate.
The example code in these tutorials is done as JUnit tests mainly for ease of use. However it is
nice in that <methodname>setUp</methodname> and <methodname>tearDown</methodname> roughly illustrate
how a <interfacename>org.hibernate.SessionFactory</interfacename> would be created at the start up
of an application and closed at the end of the application lifecycle.
</para>
</note>
<tip>
<para>
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
your application targets multiple databases. See the section "Database Dialects" in the
"Database Access" chapter of the "Hibernate Developer Guide" for further information.
</para>
</tip>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this
tutorial everything is simply configured via the <filename>hibernate.cfg.xml</filename> file
discussed in<xref linkend="hibernate-gsg-tutorial-basic-config"/>.
</para>
<para>
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly
into the database.
</para>
<para>
Finally, add the mapping file(s) for persistent classes to the configuration.
</para>
</step>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the
<interfacename>org.hibernate.SessionFactory</interfacename> which is a thread-safe object that is
instantiated once to serve the entire application.
</para>
<step id="hibernate-gsg-tutorial-native-working">
<title>Do stuff</title>
<para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/EventManager.java</filename>
containing the text in <xref linkend="hibernate-gsg-tutorial-native-working-ex1"/>.
</para>
<para>
The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for
<interfacename>org.hibernate.Session</interfacename> instances as can be seen in the
<methodname>testBasicUsage</methodname> method. A <interfacename>org.hibernate.Session</interfacename>
should be thought of as a corollary to a "unit of work".
<!-- todo : reference to a discussion in dev guide -->
</para>
<example id="hibernate-gsg-tutorial-native-working-ex1">
<title>
<filename>EventManager.java</filename>
</title>
<programlisting role="JAVA"><xi:include href="extras/examples/hbm/org/hibernate/tutorial/hbm/EventManager.java" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
<para>
<methodname>testBasicUsage</methodname> first creates some new <classname>Event</classname> objects
and hands them over to Hibernate for "management" via the <methodname>save</methodname> method. At that
point, Hibernate takes responsibility to perform an <literal>INSERT</literal> on the database.
</para>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this
tutorial we simply configure everything via the <filename>hibernate.cfg.xml</filename> file
discussed in<xref linkend="hibernate-gsg-tutorial-native-config"/>.
</para>
<para>
The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the
<interfacename>org.hibernate.SessionFactory</interfacename> which is a thread-safe object that is
instantiated once to serve the entire application.
</para>
<para>
The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for
<interfacename>org.hibernate.Session</interfacename> instances as can be seen in the
<methodname>createAndStoreEvent</methodname> and <methodname>listEvents</methodname> methods of the
<classname>EventManager</classname> class. A <interfacename>org.hibernate.Session</interfacename>
should be thought of as a corollary to a "unit of work". <!-- todo : reference to a discussion in dev guide -->
</para>
<para>
<methodname>createAndStoreEvent</methodname> creates a new <classname>Event</classname> object
and hands it over to Hibernate for "management". At that point, Hibernate takes responsibility to
perform an <literal>INSERT</literal> on the database.
</para>
<para>
<methodname>listEvents</methodname> illustrates use of the Hibernate Query Language (HQL) to load all
existing <classname>Event</classname> objects from the database. Hibernate will generate the
appropriate <literal>SELECT</literal> SQL, send it to the database and populate
<classname>Event</classname> objects with the result set data.
</para>
</step>
<step id="hibernate-gsg-tutorial-native-compile">
<title>Compile the source</title>
<screen><xi:include href="extras/examples/hbm/compile-output.txt" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></screen>
</step>
<step id="hibernate-gsg-tutorial-native-running">
<title>Run the code</title>
<para>
To perform a store (leveraging the maven exec plugin):
<command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager" -Dexec.args="store"</command>
You should see Hibernate starting up and, depending on your configuration, lots of log output. Towards
the end, the following line will be displayed:
<screen>[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)</screen>
This is the <literal>INSERT</literal>executed by Hibernate.
</para>
<para>
To perform a list:
<command>mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.hbm.EventManager"-Dexec.args="list"</command>
</para>
<note>
<para>
Currently nothing will ever be output when performing the list because the database is recreated
every time the <interfacename>org.hibernate.SessionFactory</interfacename> is created.
</para>
</note>
</step>
</procedure>
<para>
<methodname>testBasicUsage</methodname> then illustrates use of the Hibernate Query Language (HQL) to
load all existing <classname>Event</classname> objects from the database. Hibernate will generate the
appropriate <literal>SELECT</literal> SQL, send it to the database and populate
<classname>Event</classname> objects with the result set data.
</para>
</section>
<section id="hibernate-gsg-tutorial-annotations-further">
<title>Take it further!</title>

47
documentation/quickstart/tutorials/annotations/pom.xml Normal file
View File

@ -0,0 +1,47 @@
<?xml version="1.0"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<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>
<parent>
<groupId>org.hibernate.tutorials</groupId>
<artifactId>hibernate-tutorials</artifactId>
<version>3.6.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>hibernate-tutorial-annotations</artifactId>
<name>Hibernate Annotations Tutorial</name>
<description>Hibernate tutorial illustrating the use of native APIs and annotations for mapping metadata</description>
<properties>
<!-- Skip artifact deployment -->
<maven.deploy.skip>true</maven.deploy.skip>
</properties>
</project>

77
documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/AnnotationsIllustrationTest.java Normal file
View File

@ -0,0 +1,77 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.annotations;
import java.util.Date;
import java.util.List;
import junit.framework.TestCase;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
/**
* TODO : javadoc
*
* @author Steve Ebersole
*/
public class AnnotationsIllustrationTest extends TestCase {
private SessionFactory sessionFactory;
@Override
protected void setUp() throws Exception {
// A SessionFactory is set up once for an application
sessionFactory = new Configuration()
.configure() // configures settings from hibernate.cfg.xml
.buildSessionFactory();
}
@Override
protected void tearDown() throws Exception {
if ( sessionFactory != null ) {
sessionFactory.close();
}
}
public void testBasicUsage() {
// create a couple of events...
Session session = sessionFactory.openSession();
session.beginTransaction();
session.save( new Event( "Our very first event!", new Date() ) );
session.save( new Event( "A follow up event", new Date() ) );
session.getTransaction().commit();
session.close();
// now lets pull events from the database and list them
session = sessionFactory.openSession();
session.beginTransaction();
List result = session.createQuery( "from Event" ).list();
for ( Event event : (List<Event>) result ) {
System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() );
}
session.getTransaction().commit();
session.close();
}
}

83
documentation/quickstart/tutorials/annotations/src/test/java/org/hibernate/tutorial/annotations/Event.java Normal file
View File

@ -0,0 +1,83 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.annotations;
import java.util.Date;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.Temporal;
import javax.persistence.TemporalType;
import org.hibernate.annotations.GenericGenerator;
@Entity
@Table( name = "EVENTS" )
public class Event {
private Long id;
private String title;
private Date date;
public Event() {
// this form used by Hibernate
}
public Event(String title, Date date) {
// for application use, to create new events
this.title = title;
this.date = date;
}
@Id
@GeneratedValue(generator="increment")
@GenericGenerator(name="increment", strategy = "increment")
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;
}
}

59
documentation/quickstart/tutorials/annotations/src/test/resources/hibernate.cfg.xml Normal file
View File

@ -0,0 +1,59 @@
<?xml version='1.0' encoding='utf-8'?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://www.hibernate.org/dtd/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/tutorials/basic/pom.xml Normal file
View File

@ -0,0 +1,47 @@
<?xml version="1.0"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<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>
<parent>
<groupId>org.hibernate.tutorials</groupId>
<artifactId>hibernate-tutorials</artifactId>
<version>3.6.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>hibernate-tutorial-hbm</artifactId>
<name>Hibernate hbm.xml Tutorial</name>
<description>Hibernate tutorial illustrating the use of native APIs and hbm.xml for mapping metadata</description>
<properties>
<!-- Skip artifact deployment -->
<maven.deploy.skip>true</maven.deploy.skip>
</properties>
</project>

41
documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.hbm.xml Normal file
View File

@ -0,0 +1,41 @@
<?xml version="1.0"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE hibernate-mapping PUBLIC
"-//Hibernate/Hibernate Mapping DTD 3.0//EN"
"http://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">
<hibernate-mapping package="org.hibernate.tutorial.hbm">
<class name="Event" table="EVENTS">
<id name="id" column="EVENT_ID">
<generator class="increment"/>
</id>
<property name="date" type="timestamp" column="EVENT_DATE"/>
<property name="title"/>
</class>
</hibernate-mapping>

67
documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/Event.java Normal file
View File

@ -0,0 +1,67 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.hbm;
import java.util.Date;
public class Event {
private Long id;
private String title;
private Date date;
public Event() {
// this form used by Hibernate
}
public Event(String title, Date date) {
// for application use, to create new events
this.title = title;
this.date = date;
}
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;
}
}

77
documentation/quickstart/tutorials/basic/src/test/java/org/hibernate/tutorial/hbm/NativeApiIllustrationTest.java Normal file
View File

@ -0,0 +1,77 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.hbm;
import java.util.Date;
import java.util.List;
import junit.framework.TestCase;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
/**
* TODO : javadoc
*
* @author Steve Ebersole
*/
public class NativeApiIllustrationTest extends TestCase {
private SessionFactory sessionFactory;
@Override
protected void setUp() throws Exception {
// A SessionFactory is set up once for an application
sessionFactory = new Configuration()
.configure() // configures settings from hibernate.cfg.xml
.buildSessionFactory();
}
@Override
protected void tearDown() throws Exception {
if ( sessionFactory != null ) {
sessionFactory.close();
}
}
public void testBasicUsage() {
// create a couple of events...
Session session = sessionFactory.openSession();
session.beginTransaction();
session.save( new Event( "Our very first event!", new Date() ) );
session.save( new Event( "A follow up event", new Date() ) );
session.getTransaction().commit();
session.close();
// now lets pull events from the database and list them
session = sessionFactory.openSession();
session.beginTransaction();
List result = session.createQuery( "from Event" ).list();
for ( Event event : (List<Event>) result ) {
System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() );
}
session.getTransaction().commit();
session.close();
}
}

58
documentation/quickstart/tutorials/basic/src/test/resources/hibernate.cfg.xml Normal file
View File

@ -0,0 +1,58 @@
<?xml version='1.0' encoding='utf-8'?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://www.hibernate.org/dtd/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"/>
<!-- 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>
<mapping resource="org/hibernate/tutorial/hbm/Event.hbm.xml"/>
</session-factory>
</hibernate-configuration>

54
documentation/quickstart/tutorials/entitymanager/pom.xml Normal file
View File

@ -0,0 +1,54 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<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>
<parent>
<artifactId>hibernate-tutorials</artifactId>
<groupId>org.hibernate.tutorials</groupId>
<version>3.6.0-SNAPSHOT</version>
</parent>
<artifactId>hibernate-tutorial-entitymanager</artifactId>
<name>Hibernate JPA Tutorial</name>
<description>Hibernate tutorial illustrating the use of JPA APIs and annotations for mapping metadata</description>
<properties>
<!-- Skip artifact deployment -->
<maven.deploy.skip>true</maven.deploy.skip>
</properties>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</project>

72
documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/EntityManagerIllustrationTest.java Normal file
View File

@ -0,0 +1,72 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.em;
import java.util.Date;
import java.util.List;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import junit.framework.TestCase;
/**
* TODO : javadoc
*
* @author Steve Ebersole
*/
public class EntityManagerIllustrationTest extends TestCase {
private EntityManagerFactory entityManagerFactory;
@Override
protected void setUp() throws Exception {
// like discussed with regards to SessionFactory, an EntityManagerFactory is set up once for an application
entityManagerFactory = Persistence.createEntityManagerFactory( "hibernate-jpa-tutorial" );
}
@Override
protected void tearDown() throws Exception {
entityManagerFactory.close();
}
public void testBasicUsage() {
// create a couple of events...
EntityManager entityManager = entityManagerFactory.createEntityManager();
entityManager.getTransaction().begin();
entityManager.persist( new Event( "Our very first event!", new Date() ) );
entityManager.persist( new Event( "A follow up event", new Date() ) );
entityManager.getTransaction().commit();
entityManager.close();
// now lets pull events from the database and list them
entityManager = entityManagerFactory.createEntityManager();
entityManager.getTransaction().begin();
List<Event> result = entityManager.createQuery( "from Event", Event.class ).getResultList();
for ( Event event : result ) {
System.out.println( "Event (" + event.getDate() + ") : " + event.getTitle() );
}
entityManager.getTransaction().commit();
entityManager.close();
}
}

83
documentation/quickstart/tutorials/entitymanager/src/test/java/org/hibernate/tutorial/em/Event.java Normal file
View File

@ -0,0 +1,83 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* Copyright (c) 2010, Red Hat Inc. or third-party contributors as
* indicated by the @author tags or express copyright attribution
* statements applied by the authors. All third-party contributions are
* distributed under license by Red Hat Inc.
*
* This copyrighted material is made available to anyone wishing to use, modify,
* copy, or redistribute it subject to the terms and conditions of the GNU
* Lesser General Public License, as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
* for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this distribution; if not, write to:
* Free Software Foundation, Inc.
* 51 Franklin Street, Fifth Floor
* Boston, MA 02110-1301 USA
*/
package org.hibernate.tutorial.em;
import java.util.Date;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.Table;
import javax.persistence.Temporal;
import javax.persistence.TemporalType;
import org.hibernate.annotations.GenericGenerator;
@Entity
@Table( name = "EVENTS" )
public class Event {
private Long id;
private String title;
private Date date;
public Event() {
// this form used by Hibernate
}
public Event(String title, Date date) {
// for application use, to create new events
this.title = title;
this.date = date;
}
@Id
@GeneratedValue(generator="increment")
@GenericGenerator(name="increment", strategy = "increment")
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;
}
}

49
documentation/quickstart/tutorials/entitymanager/src/test/resources/META-INF/persistence.xml Normal file
View File

@ -0,0 +1,49 @@
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="2.0">
<persistence-unit name="hibernate-jpa-tutorial">
<description>
Persistence unit for the JPA tutorial of the Hibernate Getting Started Guide
</description>
<class>org.hibernate.tutorial.em.Event</class>
<properties>
<property name="javax.persistence.jdbc.driver" value="org.h2.Driver" />
<property name="javax.persistence.jdbc.url" value="jdbc:h2:mem:db1;DB_CLOSE_DELAY=-1;MVCC=TRUE" />
<property name="javax.persistence.jdbc.user" value="sa" />
<property name="javax.persistence.jdbc.password" value="" />
<property name="hibernate.show_sql" value="true" />
<property name="hibernate.hbm2ddl.auto" value="update" />
</properties>
</persistence-unit>
</persistence>

102
documentation/quickstart/tutorials/pom.xml Normal file
View File

@ -0,0 +1,102 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
~ Copyright (c) 2010, Red Hat Inc. or third-party contributors as
~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are
~ distributed under license by Red Hat Inc.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
~ Lesser General Public License, as published by the Free Software Foundation.
~
~ This program is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
~ for more details.
~
~ You should have received a copy of the GNU Lesser General Public License
~ along with this distribution; if not, write to:
~ Free Software Foundation, Inc.
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
<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-tutorials</artifactId>
<version>3.6.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>Hibernate Getting Started Guide Tutorials</name>
<description>Aggregator for the Hibernate tutorials presented in the Getting Started Guide</description>
<properties>
<!-- Skip artifact deployment -->
<maven.deploy.skip>true</maven.deploy.skip>
</properties>
<modules>
<module>basic</module>
<module>annotations</module>
<module>entitymanager</module>
</modules>
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>${project.version}</version>
</dependency>
<!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>1.6.1</version>
</dependency>
<!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
<dependency>
<groupId>javassist</groupId>
<artifactId>javassist</artifactId>
<version>3.12.0.GA</version>
</dependency>
<!-- The tutorials use JUnit test cases to illustrate usage -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.8.1</version>
</dependency>
<!-- The tutorials use the H2 in-memory database -->
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>1.2.140</version>
</dependency>
</dependencies>
<build>
<testResources>
<testResource>
<filtering>false</filtering>
<directory>src/main/java</directory>
<includes>
<include>**/*.xml</include>
</includes>
</testResource>
<testResource>
<filtering>true</filtering>
<directory>src/test/resources</directory>
</testResource>
</testResources>
</build>
</project>