HHH-5541
git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@20200 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
misty
parent
0c5c9874e6
commit
ca1f02f4c9
|
|
@ -13,9 +13,11 @@
|
|||
|
||||
<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 tutorials in this guide use Maven, in order to leverage its
|
||||
transitive dependency management capabilities and its integration
|
||||
with many development environments (IDEs). <!--This sounds like
|
||||
marketing! -->You can use another build tool, adapting the examples
|
||||
to fit your needs.
|
||||
</para>
|
||||
</tip>
|
||||
|
||||
|
|
@ -40,8 +42,11 @@
|
|||
<title>Create the entity Java class</title>
|
||||
|
||||
<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"/>.
|
||||
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"/>.<!-- Can we
|
||||
just include these files in an example.zip? -->
|
||||
</para>
|
||||
|
||||
<example id="hibernate-gsg-tutorial-native-entity-ex1">
|
||||
|
|
@ -83,7 +88,7 @@
|
|||
<title>Create the entity mapping file</title>
|
||||
|
||||
<para>
|
||||
Create a file named<filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
|
||||
Create a file named <filename>src/main/resources/org/hibernate/tutorial/native/Event.hbm.xml</filename>,
|
||||
with the contents in <xref linkend="hibernate-gsg-tutorial-native-hbm-xml-ex1"/>.
|
||||
</para>
|
||||
|
||||
|
|
@ -101,79 +106,104 @@
|
|||
</para>
|
||||
|
||||
<orderedlist>
|
||||
<title>Functions of the <literal>class</literal> element</title>
|
||||
<title>Functions of the <property>class</property> element</title>
|
||||
<listitem>
|
||||
<para>
|
||||
The <literal>class</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.
|
||||
The <literal>class</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>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
The <literal>table</literal> attribute names the database table which contains the data for
|
||||
this entity.
|
||||
The <literal>table</literal> attribute names the
|
||||
database table which contains the data for this entity.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>
|
||||
Instances of <classname>Event</classname> are now mapped to rows in the <literal>EVENTS</literal>
|
||||
table. Hibernate uses the <literal>id</literal> element to uniquely identify rows in the table.
|
||||
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>
|
||||
It is not strictly necessary that the <literal>id</literal> element map to the table's actual
|
||||
primary key column(s), but it is the normal convention. Tables mapped in Hibernate do not even
|
||||
need to define primary keys. However, the Hibernate team <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.
|
||||
It is not strictly necessary for the <literal>id</literal>
|
||||
element to map to the table's actual primary key column(s),
|
||||
but this type of mapping is conventional. 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 <literal>EVENT_ID</literal> column as the
|
||||
primary key of the <literal>EVENTS</literal> table. It also identifies the <literal>id</literal>
|
||||
property of the <classname>Event</classname> class as the property to hold the identifier value.
|
||||
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
|
||||
different word for the column name.
|
||||
</para>
|
||||
<para>
|
||||
The important thing to be aware of about the <literal>generator</literal> element nested inside the
|
||||
<literal>id</literal> element is that it informs Hibernate which strategy is used to generated primary
|
||||
key values for this entity. In this instance, it uses a sequence-like value generation.
|
||||
The <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. <!-- We need to decide how we mark up XML tags (elements) and parameters (attributes). -->
|
||||
</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 include 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 have 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 <literal>DATE</literal>,
|
||||
<literal>TIME</literal>, or <literal>TIMESTAMP</literal> datatype. Full date and time information is
|
||||
preserved by mapping the property to a <literal>timestamp</literal>
|
||||
converter.
|
||||
In some cases this automatic detection might not choose 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
|
||||
<literal>DATE</literal>, <literal>TIME</literal>, or
|
||||
<literal>TIMESTAMP</literal> datatype. Full date and time
|
||||
information is preserved by mapping the property to a
|
||||
<literal>timestamp</literal> converter.
|
||||
</para>
|
||||
|
||||
<tip>
|
||||
<info>
|
||||
<para>
|
||||
Hibernate makes this mapping type determination using reflection when the mapping files are
|
||||
processed. This can take time and resources. If startup performance is important, consider
|
||||
explicitly defining the type to use.
|
||||
Hibernate makes this mapping type determination using
|
||||
reflection when the mapping files are processed. This can
|
||||
take time and resources. If startup performance is
|
||||
important, consider explicitly defining the type to use.
|
||||
</para>
|
||||
</tip>
|
||||
</info
|
||||
</step>
|
||||
|
||||
<step id="hibernate-gsg-tutorial-native-config">
|
||||
|
|
|
|||
Loading…
Reference in New Issue