From hibernate-commits at lists.jboss.org Fri Aug 20 01:23:29 2010 Content-Type: multipart/mixed; boundary="===============5868173166110193189==" MIME-Version: 1.0 From: hibernate-commits at lists.jboss.org To: hibernate-commits at lists.jboss.org Subject: [hibernate-commits] Hibernate SVN: r20202 - core/trunk/documentation/quickstart/src/main/docbook/en-US/content. Date: Fri, 20 Aug 2010 01:23:28 -0400 Message-ID: <201008200523.o7K5NSBj014729@svn01.web.mwc.hst.phx2.redhat.com> --===============5868173166110193189== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: misty(a)redhat.com Date: 2010-08-20 01:23:28 -0400 (Fri, 20 Aug 2010) New Revision: 20202 Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutor= ial_native.xml Log: Rolling back to the last version Steve worked on (20171) Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/conten= t/tutorial_native.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto= rial_native.xml 2010-08-20 02:07:25 UTC (rev 20201) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tuto= rial_native.xml 2010-08-20 05:23:28 UTC (rev 20202) @@ -13,11 +13,9 @@ = - The tutorials in this guide use Maven, in order to leverage its - transitive dependency management capabilities and its integrat= ion - with many development environments (IDEs). You can use another build tool, adapting the exa= mples - to fit your needs. + The tutorials in this guide use Maven, in order to leverage it= s transitive dependency management + capabilities and its integration with many development environ= ments (IDEs). You can use another build + tool, adapting the examples to fit your needs. = @@ -42,11 +40,8 @@ Create the entity Java class = - Create a file named - src/main/java/org/hibernate/tutorial/hbm/Event.j= ava, - containing the text in. + Create a file namedsrc/main/java/org/hibernate/t= utorial/hbm/Event.java, + containing the text in. = @@ -88,7 +83,7 @@ Create the entity mapping file = - Create a file named src/main/resources/org/hiber= nate/tutorial/native/Event.hbm.xml, + Create a file namedsrc/main/resources/org/hibern= ate/tutorial/native/Event.hbm.xml, with the contents in . = @@ -106,104 +101,79 @@ = - Functions of the <property>class</property> element= + Functions of the <literal>class</literal> element</= title> <listitem> <para> - The <literal>class</literal> attribute, combined h= ere - with the <literal>package</literal> attribute from= the - containing <literal>hibernate-mapping</literal> el= ement, - names the FQN of the class you want to define as an - entity. + The <literal>class</literal> attribute, combined h= ere with the <literal>package</literal> + attribute from the containing <literal>hibernate-m= apping</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 en= tity. + The <literal>table</literal> attribute names the d= atabase table which contains the data for + this entity. </para> </listitem> </orderedlist> = <para> - Instances of the <classname>Event</classname> class are now - mapped to rows in the <database class=3D"table">EVENTS</da= tabase> - table. Hibernate uses the <literal>id</literal> element to - uniquely identify rows in the table. + Instances of <classname>Event</classname> are now mapped t= o rows in the <literal>EVENTS</literal> + table. Hibernate uses the <literal>id</literal> element to= uniquely identify rows in the table. </para> <important> <para> - It is not strictly necessary for the <literal>id</lite= ral> - element to map to the table's actual primary key colum= n(s), - but this type of mapping is conventional. Tables mappe= d in - Hibernate do not even need to define primary keys. How= ever, - the Hibernate team <emphasis>strongly</emphasis> recom= mends - 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 that the <literal>id</lit= eral> 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 te= am <emphasis>strongly</emphasis> + recommends that all schemas define proper referential = integrity. Therefore <literal>id</literal> + and <phrase>primary key</phrase> are used interchangea= bly throughout Hibernate documentation. </para> </important> <para> - The <literal>id</literal> element here identifies the <dat= abase - class=3D"field">EVENT_ID</database> column as the primary = key of - the <database class=3D"table">EVENTS</database> table. It = also - identifies the <literal>id</literal> property of the - <classname>Event</classname> class as the property contain= ing - the identifier value. + The <literal>id</literal> element here identifies the <lit= eral>EVENT_ID</literal> column as the + primary key of the <literal>EVENTS</literal> table. It als= o identifies the <literal>id</literal> + property of the <classname>Event</classname> class as the = property to hold 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</classnam= e> - 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 pr= operty - 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. + The important thing to be aware of about the <literal>gene= rator</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 se= quence-like value generation. </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>Hiber= nate - mapping types</phrase></firstterm>. Hibernate mapping type= s are - converters which translate between Java and SQL data - types. Hibernate attempts to determine the correct convers= ion - and mapping type autonomously if the <literal>type</litera= l> - attribute is not present in the mapping, by using Java - reflection to determine the Java type of the declared prop= erty - and using a default mapping type for that Java type. <!-- = We need to decide how we mark up XML tags (elements) and parameters (attrib= utes). --> + The two <literal>property</literal> elements declare the r= emaining two properties of the + <classname>Event</classname> class: <literal>date</literal= > and<literal>title</literal>. The + <literal>date</literal> property mapping include the <lite= ral>column</literal> attribute, but the + <literal>title</literal> does not. In the absence of a <li= teral>column</literal> attribute, Hibernate + uses the property name as the column name. This is appropr= iate for <literal>title</literal>, but since + <literal>date</literal> is a reserved keyword in most data= bases, you need to specify a non-reserved + word for the column name. </para> <para> - 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. + The <literal>title</literal> mapping also lacks a <literal= >type</literal> attribute. The types + declared and used in the mapping files are neither Java da= ta types nor SQL database types. Instead, + they are <firstterm><phrase>Hibernate mapping types</phras= e></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>t= ype</literal> attribute is not present in the + mapping, by using Java reflection to determine the Java ty= pe 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> d= atatype. Full date and time information is + preserved by mapping the property to a <literal>timestamp<= /literal> + converter. + </para> = - <info> + <tip> <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 us= e. + Hibernate makes this mapping type determination using = reflection when the mapping files are + processed. This can take time and resources. If startu= p performance is important, consider + explicitly defining the type to use. </para> - </info + </tip> </step> = <step id=3D"hibernate-gsg-tutorial-native-config"> @@ -219,88 +189,38 @@ </example> = <para> - The first few <property>property</property> tags define - information about the JDBC connection. The - <option>connection.url</option> contains information direc= ting - Hibernate to use the <firstterm>H2 in-memory - database</firstterm>. The rest of the properties are expla= ined - in <xref linkend=3D"tutorial-native-config-options-explain= ed" />. - </para> - = - <!-- <mapping resource=3D"org/hibernate/tutorial/hbm/Event.hbm.xml"/>= --> + The first few <literal>property</literal> are defining JDB= C connection information. These tutorials + utilize the H2 in-memory database. So these are all specif= ic 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> = - <table id=3D"tutorial-native-config-options-explained"> - <title>Configuration Options Used In the Native Configuration Examp= le - - - -

Property Name

 -

Description

 - - - - -

- -

- configures Hibernate's built-in connection pool to - contain the specified number of connections. -

-

- - - The built-in Hibernate connection pool is inappropriate for - production use. It lacks several features found on any - decent connection pool. - - - -

- - - -

- -

- specifies the particular SQL variant Hibernate should - generate. -

-

- - - In most cases, Hibernate can automatically determine which - dialect to use. This capability is valuable for applications - which target multiple databases. - - -

= - - - -

-

- - -

show_sql

 -

- - -

hbm2ddl.auto

 - -

- enables automatic generation of database schemas directly - into the database. -

- - - - - - = + + + The built-in Hibernate connection pool is in no way in= tended for production use. It + lacks several features found on any decent connection = pool. + + + - Finally, the mapping files provide persistent classes to the - configuration. + The dialect option specifies the partic= ular SQL variant Hibernate should generate. + + + + In most cases, Hibernate is able to properly determine= which dialect to use which is invaluable if + your application targets multiple databases. + + + + + The hbm2ddl.auto option turns on automa= tic generation of database schemas directly + into the database. + + + Finally, add the mapping file(s) for persistent classes to= the configuration. + = --===============5868173166110193189==--