Author: steve.ebersole(a)jboss.com Date: 2010-08-31 07:09:44 -0400 (Tue, 31 Aug 2010) New Revision: 20285 Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml Log: HHH-5442 - Write native tutorial chapter Modified: core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml =================================================================== --- core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-31 09:08:33 UTC (rev 20284) +++ core/trunk/documentation/quickstart/src/main/docbook/en-US/content/tutorial_native.xml 2010-08-31 11:09:44 UTC (rev 20285) @@ -29,11 +29,12 @@ </para> <para> - The first few <literal>property</literal> elements define JDBC connection information. These tutorials + The <literal>connection.driver_class</literal>, <literal>connection.url</literal>, + <literal>connection.username</literal> and <literal>connection.password</literal> + <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. + <literal>connection.pool_size</literal> is used to configure Hibernate's built-in connection pool + how many connections to pool. </para> <important> @@ -47,7 +48,8 @@ </important> <para> - The <literal>dialect</literal> option specifies the particular SQL variant Hibernate should generate. + The <literal>dialect</literal> property specifies the particular SQL variant Hibernate with which + Hibernate will converse. </para> <tip> @@ -61,7 +63,7 @@ </tip> <para> - The <literal>hbm2ddl.auto</literal> option turns on automatic generation of database schemas directly + The <literal>hbm2ddl.auto</literal> property turns on automatic generation of database schemas directly into the database. </para> @@ -118,6 +120,8 @@ file is one choice for providing Hibernate with this metadata. </para> + <programlisting role="XML"><![CDATA[<class name="Event" table="EVENTS">...</class>]]></programlisting> + <orderedlist> <title>Functions of the <literal>class</literal> element</title> <listitem> @@ -137,9 +141,16 @@ <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. + <database class="table">EVENTS</database> table. </para> + + <programlisting role="XML"><![CDATA[<id name="id" column="EVENT_ID">...</id>]]></programlisting> + + <para> + Hibernate uses the property named by the <literal>id</literal> element to uniquely identify rows + in the table. + </para> + <important> <para> It is not strictly necessary for the <literal>id</literal> element to map to the table's actual @@ -158,8 +169,12 @@ <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. + example a simple incrementing count is used. </para> + + <programlisting role="XML"><![CDATA[<property name="date" type="timestamp" column="EVENT_DATE"/> +<property name="title"/>]]></programlisting> + <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 @@ -213,6 +228,13 @@ </para> </note> + <programlisting role="JAVA">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(); +}</programlisting> + <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 @@ -233,12 +255,28 @@ <!-- todo : reference to a discussion in dev guide --> </para> + <programlisting role="JAVA">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();</programlisting> + <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> + <programlisting role="JAVA"><![CDATA[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();]]></programlisting> + <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