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="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/preface.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/community.xml" /> <part label="I">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/obtaining.xml" /> <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> </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"> <chapter id="hibernate-gsg-tutorial-annotations">
<title>Tutorial Using Native Hibernate APIs and Annotation Mappings</title> <title>Tutorial Using Native Hibernate APIs and Annotation Mappings</title>
<procedure> <para>
<title>Steps</title> 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"> <section id="hibernate-gsg-tutorial-annotations-config">
<title>Create the Maven POM file</title> <title>The Hibernate configuration file</title>
<para>
Create a file named <filename>pom.xml</filename> in the root of your project directory, containing
the text in <xref linkend="hibernate-gsg-tutorial-annotations-pom-ex1"/>.
</para>
<example id="hibernate-gsg-tutorial-annotations-pom-ex1">
<title><filename>pom.xml</filename></title>
<programlisting role="XML"><xi:include href="extras/examples/annotations/pom.xml" xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
</example>
</step>
<step id="hibernate-gsg-tutorial-native-entity"> <para>
<title>Create the annotated entity Java class</title> 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> <section id="hibernate-gsg-tutorial-basic-entity">
Create a file named <filename>src/main/java/org/hibernate/tutorial/annotations/Event.java</filename>, <title>The annotated entity Java class</title>
containing the text in <xref linkend="hibernate-gsg-tutorial-annotations-entity-ex1"/>. <para>
</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"> <section id="hibernate-gsg-tutorial-annotations-test">
<title><filename>Entity.java</filename></title> <title>Example code</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> <para>
</example> <classname>org.hibernate.tutorial.annotations.AnnotationsIllustrationTest</classname> is essentially the
<para> same as <classname>org.hibernate.tutorial.hbm.NativeApiIllustrationTest</classname> discussed in
<itemizedlist> <xref linkend="hibernate-gsg-tutorial-basic-test"/>.
<title>Notes About the Entity</title> </para>
<listitem> </section>
<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-further"> <section id="hibernate-gsg-tutorial-annotations-further">
<title>Take it further!</title> <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' ?> <?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"> <!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-basic">
<title>Tutorial Using Native Hibernate APIs and <filename>hbm.xml</filename> Mappings</title> <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> <para>
This tutorial uses the <phrase>standard layout</phrase> described in The resource file <filename>hibernate.cfg.xml</filename> defines Hibernate configuration
<ulink url="http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html"/>. information.
</para> </para>
</note>
<tip>
<para> <para>
The tutorials in this guide use Maven, in order to leverage its transitive dependency management The first few <literal>property</literal> elements define JDBC connection information. These tutorials
capabilities and its integration with many development environments (IDEs). You can use another build utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode.
tool, adapting the examples to fit your needs. The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many
connections
to pool.
</para> </para>
</tip>
<procedure> <important>
<title>Steps</title>
<step id="hibernate-gsg-tutorial-native-pom">
<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 built-in Hibernate connection pool is in no way intended for production use. It
the text in<xref linkend="hibernate-gsg-tutorial-native-pom-ex1"/>. 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> </para>
<example id="hibernate-gsg-tutorial-native-pom-ex1"> </important>
<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>
<step id="hibernate-gsg-tutorial-native-entity"> <para>
<title>Create the entity Java class</title> The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate.
</para>
<tip>
<para> <para>
Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/Event.java</filename>, In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if
containing the text in <xref linkend="hibernate-gsg-tutorial-native-entity-ex1"/>. 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> </para>
</tip>
<example id="hibernate-gsg-tutorial-native-entity-ex1"> <para>
<title> The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly
<filename>Entity.java</filename> into the database.
</title> </para>
<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>
<step id="hibernate-gsg-tutorial-native-mapping"> <para>
<title>Create the entity mapping file</title> 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> </section>
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>
<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> <section id="hibernate-gsg-tutorial-basic-entity">
Hibernate uses the mapping metadata to find out how to load and <title>The entity Java class</title>
store objects of the persistent class. The Hibernate mapping <para>
file is one choice for providing Hibernate with this metadata. The entity class for this tutorial is <classname>org.hibernate.tutorial.hbm.Event</classname>.
</para> <itemizedlist>
<title>Notes About the Entity</title>
<orderedlist>
<title>Functions of the <literal>class</literal> element</title>
<listitem> <listitem>
<para> <para>
The <literal>name</literal> attribute (combined here with the <literal>package</literal> This class uses standard JavaBean naming conventions
attribute from the containing <literal>hibernate-mapping</literal> element) names the FQN of for property getter and setter methods, as well as
the class you want to define as an entity. private visibility for the fields. Although this is
the recommended design, it is not required.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The <literal>table</literal> attribute names the database table which contains the data for The no-argument constructor, which is also a JavaBean
this entity. 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> </para>
</listitem> </listitem>
</orderedlist> </itemizedlist>
</para>
</section>
<para>
Instances of the <classname>Event</classname> class are now mapped to rows in the <section id="hibernate-gsg-tutorial-basic-mapping">
<database class="table">EVENTS</database> table. Hibernate uses the <literal>id</literal> element to <title>The mapping file</title>
uniquely identify rows in the table. <para>
</para> The <phrase>hbm.xml</phrase> mapping file for this tutorial is the classpath resource
<important> <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> <para>
It is not strictly necessary for the <literal>id</literal> element to map to the table's actual The <literal>name</literal> attribute (combined here with the <literal>package</literal>
primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even attribute from the containing <literal>hibernate-mapping</literal> element) names the FQN of
need to define primary keys. However, the Hibernate team <emphasis>strongly</emphasis> the class you want to define as an entity.
recommends that all schemas define proper referential integrity. Therefore <literal>id</literal>
and <phrase>primary key</phrase> are used interchangeably throughout Hibernate documentation.
</para> </para>
</important> </listitem>
<para> <listitem>
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>
<para> <para>
Hibernate makes this mapping type determination using reflection when the mapping files are The <literal>table</literal> attribute names the database table which contains the data for
processed. This process can take time and resources. If startup performance is important, consider this entity.
explicitly defining the type to use.
</para> </para>
</tip> </listitem>
</step> </orderedlist>
<step id="hibernate-gsg-tutorial-native-config">
<title>Create the Hibernate configuration file</title>
<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> <para>
Create a file named <filename>src/main/resources/hibernate.cfg.xml</filename> containing the text in It is not strictly necessary for the <literal>id</literal> element to map to the table's actual
<xref linkend="hibernate-gsg-tutorial-native-config-ex1"/>. 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> </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"> <tip>
<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>
<para> <para>
The first few <literal>property</literal> elements define JDBC connection information. These tutorials Hibernate makes this mapping type determination using reflection when the mapping files are
utilize the H2 in-memory database. So these are all specific to running H2 in its in-memory mode. processed. This process can take time and resources. If startup performance is important, consider
The 'connection.pool_size' is used to configure Hibernate's built-in connection pool how many explicitly defining the type to use.
connections
to pool.
</para> </para>
</tip>
<warning> </section>
<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 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> <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> </para>
</note>
<tip> <para>
<para> The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this
In most cases, Hibernate is able to properly determine which dialect to use which is invaluable if tutorial everything is simply configured via the <filename>hibernate.cfg.xml</filename> file
your application targets multiple databases. See the section "Database Dialects" in the discussed in<xref linkend="hibernate-gsg-tutorial-basic-config"/>.
"Database Access" chapter of the "Hibernate Developer Guide" for further information. </para>
</para>
</tip>
<para> <para>
The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly The <classname>org.hibernate.cfg.Configuration</classname> is then used to create the
into the database. <interfacename>org.hibernate.SessionFactory</interfacename> which is a thread-safe object that is
</para> instantiated once to serve the entire application.
<para> </para>
Finally, add the mapping file(s) for persistent classes to the configuration.
</para>
</step>
<step id="hibernate-gsg-tutorial-native-working"> <para>
<title>Do stuff</title> The <interfacename>org.hibernate.SessionFactory</interfacename> acts as a factory for
<para> <interfacename>org.hibernate.Session</interfacename> instances as can be seen in the
Create a file named <filename>src/main/java/org/hibernate/tutorial/hbm/EventManager.java</filename> <methodname>testBasicUsage</methodname> method. A <interfacename>org.hibernate.Session</interfacename>
containing the text in <xref linkend="hibernate-gsg-tutorial-native-working-ex1"/>. should be thought of as a corollary to a "unit of work".
</para> <!-- todo : reference to a discussion in dev guide -->
</para>
<example id="hibernate-gsg-tutorial-native-working-ex1"> <para>
<title> <methodname>testBasicUsage</methodname> first creates some new <classname>Event</classname> objects
<filename>EventManager.java</filename> and hands them over to Hibernate for "management" via the <methodname>save</methodname> method. At that
</title> point, Hibernate takes responsibility to perform an <literal>INSERT</literal> on the database.
<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> </para>
</example>
<para> <para>
The <classname>org.hibernate.cfg.Configuration</classname> class is the first thing to notice. In this <methodname>testBasicUsage</methodname> then illustrates use of the Hibernate Query Language (HQL) to
tutorial we simply configure everything via the <filename>hibernate.cfg.xml</filename> file load all existing <classname>Event</classname> objects from the database. Hibernate will generate the
discussed in<xref linkend="hibernate-gsg-tutorial-native-config"/>. appropriate <literal>SELECT</literal> SQL, send it to the database and populate
</para> <classname>Event</classname> objects with the result set data.
</para>
<para> </section>
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>
<section id="hibernate-gsg-tutorial-annotations-further"> <section id="hibernate-gsg-tutorial-annotations-further">
<title>Take it further!</title> <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>