Author: bsatguna Date: 2008-05-12 16:14:57 -0400 (Mon, 12 May 2008) New Revision: 14658 Added: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.ent Removed: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Book_Info.xml Modified: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Article_Info.xml core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.xml Log: updated content to reflect latest changes in redhat svn: release notes for 3.2.4.sp01.cp03 Modified: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Article_Info.xml =================================================================== --- core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Article_Info.xml 2008-05-10 22:58:25 UTC (rev 14657) +++ core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Article_Info.xml 2008-05-12 20:14:57 UTC (rev 14658) @@ -2,12 +2,12 @@ <!DOCTYPE articleinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<articleinfo id="Release_Notes-Hibernate-Standalone"> - <title>Enterprise Hibernate x.y.z Release Notes</title> +<articleinfo id="Release_Notes-Hibernate"> + <title>Hibernate</title> <subtitle>Release Notes</subtitle> - <issuenum>0.1</issuenum> - <productnumber>0</productnumber> - <abstract><para>This document outlines information necessary for installation, migration and bug fixes.</para> + <issuenum>3.2.4</issuenum> + <productnumber>0.1</productnumber> + <abstract><para>This document contains release notes for new and existing users of Hibernate regarding Hibernate &VERSION; release. It provides installation and migration notes, document sources and bug fixes for this release.</para> </abstract> <corpauthor><inlinemediaobject> <imageobject> Deleted: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Book_Info.xml =================================================================== --- core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Book_Info.xml 2008-05-10 22:58:25 UTC (rev 14657) +++ core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Book_Info.xml 2008-05-12 20:14:57 UTC (rev 14658) @@ -1,27 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE articleinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<articleinfo id="Release_Notes-Product_Name_and_Version"> - <title>Product Name and Version</title> - <subtitle>Release Notes</subtitle> - <issuenum>0.1</issuenum> - <productnumber>0</productnumber> - <abstract><para>This book is about... (Be brief; this para is used for the RPM spec - file)</para> - </abstract> - <corpauthor><inlinemediaobject> - <imageobject> - <imagedata fileref="Common_Content/images/redhat-logo.svg" /> - </imageobject> - </inlinemediaobject> - </corpauthor><copyright> - <year>&YEAR;</year> - <holder>&HOLDER;</holder> - </copyright> - <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</articleinfo> - - - Added: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.ent =================================================================== --- core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.ent (rev 0) +++ core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.ent 2008-05-12 20:14:57 UTC (rev 14658) @@ -0,0 +1,4 @@ +<!ENTITY PRODUCT "Hibernate Standalone"> +<!ENTITY BOOKID "Release Notes"> +<!ENTITY VERSION "3.2.4.sp01.cp03 version"> +<!ENTITY YEAR "2008"> Modified: core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.xml =================================================================== --- core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.xml 2008-05-10 22:58:25 UTC (rev 14657) +++ core/branches/Branch_3_2_4_SP1_CP/doc/release_notes/src/main/docbook/en-US/Release_Notes.xml 2008-05-12 20:14:57 UTC (rev 14658) @@ -8,63 +8,396 @@ Overview </title> <para> - These release notes contain important information regarding Hibernate &VERSION;. This document covers installation and migration notes, new features and bug fixes. + These release notes contain important information regarding Hibernate &VERSION; release. This document lists the necessary software that must be installed before using Hibernate. Users of previous versions of Hibernate may refer to <xref linkend="Fixed_Issues"/> to find the latest JIRA issue fixes. In addition, the latest <xref linkend="Documentation"/>, product support and license links are also provided. </para> <section id="Background"> <title>Background</title> <para> - Hibernate is a powerful object/relational mapping tool for building Java applications. It significantly reduces repetitive persistence related programming tasks by mapping the object model's data representation to a relational data model. Hibernate offers a sophisticated object-oriented HQL (Hibernate query language) allowing the programmer to make use of polymorphic queries. Queries can be expressed in native SQL or using Criteria and example queries. A full feature datasheet is available <ulink url="http://www.jboss.com/pdf/HibernateBrochure-Jun2005.pdf">... for download</ulink> + Hibernate is a powerful object/relational mapping tool and a query service for building Java applications. Hibernate offers a sophisticated object-oriented HQL (Hibernate query language) allowing the programmer to make use of polymorphic queries. Queries can be expressed in native SQL or using Java-based Criteria and Example queries. A full feature datasheet is available <ulink url="http://www.jboss.com/pdf/HibernateBrochure-Jun2005.pdf">... for download. </para> + <para> + Hibernate can be integrated with any Java EE middleware platform. This release is also embedded in JBoss Enterprise Application platform versions 4.2 CP 03 and 4.3 CP 01 releases. Hence, the <filename>jar</filename> files remain the same as the ones distributed with JBoss Enterprise Application Platform 4.2 CP 03 and 4.3 CP 01 releases. + </para> + <para> + This Hibernate version is available through subscriptions which offers certified software, industry-leading support, updates and patches, documentation, and multi-year maintenance policies. + </para> </section> </section> <section id="Important_Notes"> <title>Installation And Migration Guide</title> <para> - This section contains all information related to installing hibernate, testing the installation and running some examples. + This section lists the software that must be installed on your local machine before beginning to use Hibernate. Migration notes are also listed in this section for users who will be using existing databases along with Hibernate. </para> + + <section id="Prerequisites"> + <title>Prerequisites</title> + <para> + The software required for setting up Hibernate for use will depend on whether you would also like to build and test the Hibernate source files or use the <filename>jar</filename> files directly. + </para> + <section id="Using_Hibernate"> + <title>Using Hibernate</title> + <para><application>JDK 1.5</application></para> + <para> + To build Java applications with Hibernate you must have <application>JDK</application> 1.5 version installed. While this version is compatible with Hibernate, version 1.4 is no longer supported. You must ensure that after installation, the environment variables are set for use. + </para> + + </section> + + <section id="Testing_Hibernate_And_Running_Demo"> + <title>Testing Hibernate and Running the demo</title> + <para> + To test Hibernate and run the demo, you will need <application>Apache Ant 1.7.0</application> and <application>JUnit 3.8.1</application>. + </para> + + <itemizedlist> + <listitem> + <para><application>Apache Ant 1.7.0</application></para> + <para>Apache Ant can be downloaded from this <ulink url="http://ant.apache.org">link</ulink>. You must set the <property>ANT_HOME</property> environment variable to point to the Apache Ant install location. You may refer to the manual available on their website for installing and setting up Apache Ant for use. </para> + </listitem> + <listitem> + <para><application>JUnit 3.8.1</application></para> + <para> + To run JUnit tests, you may use JUnit 3.8.1 version which can be downloaded from <ulink url="http://www.junit.org/">here</ulink>;. After installation, copy <filename>junit.jar</filename> to <literal>$ANT_HOME/lib</literal> directory. Documentation to help you get started on running sample test cases are available on their website. <xref linkend="Running_JUnit_Tests"/> provides further notes on running JUnit tests. + </para> + + </listitem> + </itemizedlist> + + + </section> + </section> + <section id="Installation_Notes"> <title>Installation Notes</title> <para> - We advise users to ensure that adequate disk space is available for the installation of Hibernate, JDK 1.4 (or above) and the database. - + Extract files from the Hibernate <literal>ZIP</literal> file to the desired location. Open the directory where you have extracted these files. To use Hibernate, you must configure the project's classpath settings to point to the <filename>jar</filename> files. Settings for individual IDEs differ, but normally you would add the <filename>jar</filename> files as external library files. </para> + <section id="Hibernate_Dependencies"> + <title>Hibernate Dependencies</title> + <para> + The lib directory contains all the dependencies required to use Hibernate in a supported fashion. Certain dependencies from the community builds (such as connection pool integration and second-level cache providers other than the JBoss Cache provider) are not included as they are not supported. + </para> + </section> + </section> - <section id="Migration_Guide"> - <title>Migration Guide</title> - <para> - Information regarding upgrades - </para> + <section id="Migration_Notes"> + <title>Migration Notes</title> + <section id="Configuring_Database"> + <title>Configuring your database</title> + <para> + To use your database with Hibernate, copy your <literal>JDBC</literal> driver into the <literal>lib</literal> directory. Then edit the <filename>hibernate.properties</filename> file in the <literal>etc</literal> directory. Additional configuration notes are available in <citetitle pubwork="book">Hibernate Reference Guide</citetitle>, chapter 3: Configuration. The Hibernate supported databases are: Oracle9i, Oracle10g, MS SQL 2005, PostgreSQL and MySQL. + </para> + <section id="Oracle_Users"> + <title>Oracle users</title> + <para> + OracleDialect and Oracle9Dialect have been deprecated. Oracle8iDialect, Oracle9iDialect, or Oracle10gDialect should be used instead. + </para> + </section> + </section> </section> </section> - <section id="Features_And_Bug_Fixes"> - <title>New features and bug fixes</title> + + <section id="Certified_Configurations"> + <title>Certified Configurations</title> <para> - All new features and bug fixes mentioned in these release notes are applicable to VERSION;. + Certified Configurations are a defined set of validated, tested, and recommended Operating Systems, chip architectures, JVM, and database combinations. These configurations have been tested and validated against the Hibernate &VERSION; release. </para> - <section id="New_Features"> - <title>New Features</title> + <table id="T_CC"> + <title>Compatible Operating systems, chip architecture and JVMs.</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Operating System</entry> + <entry>Chip Architecture</entry> + <entry>Java Virtual Machine(s)</entry> + </row> + </thead> + <tbody> + <row> + <entry>Red Hat Enterprise Linux v5</entry> + <entry>x86, x86_64</entry> + <entry>Sun JDK 1.5.0_11, BEA JRockit JDK 1.5.0_08</entry> + + </row> + <row> + <entry>Red Hat Enterprise Linux v4.5</entry> + <entry>x86, x86_64</entry> + <entry>Sun JDK 1.5.0_11, BEA JRockit JDK 1.5.0_08, Azul JDK 1.5.0_11</entry> + + + </row> + <row> + <entry>Microsoft Windows 2003</entry> + <entry>x86</entry> + <entry>Sun JDK 1.5.0_11, BEA JRockit JDK 1.5.0_10</entry> + + </row> + <row> + <entry>Microsoft Windows 2003</entry> + <entry>x86_64</entry> + <entry>Sun JDK 1.5.0_11, BEA JRockit JDK 1.5.0_08</entry> + + </row> + <row> + <entry>Solaris 10</entry> + <entry>x86, SPARC</entry> + <entry>Sun JDK 1.5.0_11</entry> + </row> + <row> + <entry>Solaris 9</entry> + <entry>SPARC</entry> + <entry>Sun JDK 1.5.0_11</entry> + </row> + <row> + <entry>HP-UX i2</entry> + <entry>RISC, ia64</entry> + <entry>HP-UX JDK 1.5.0.06</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>The following databases and database drivers were validated and certified as part of the Hibernate &VERSION; release process:</para> + <table id="T_DB"> + <title>Compatible databases and database drivers</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Database</entry> + <entry>Database Driver</entry> + </row> + </thead> + <tbody> + <row> + <entry>Oracle 10g R2</entry> + <entry>Oracle JDBC driver v10.2.0.1, Oracle JDBC driver v10.2.0.2</entry> + </row> + <row> + <entry>Oracle 9i</entry> + <entry>Oracle JDBC driver v10.2.0.1, Oracle JDBC driver v10.2.0.2</entry> + </row> + <row> + <entry>Microsoft SQL Server 2005</entry> + <entry>Microsoft SQL Server 2005 driver, v1.1.1501.101</entry> + </row> + <row> + <entry>MySQL v5.0</entry> + <entry>mysql-connector-java v5.0.4</entry> + </row> + <row> + <entry>PostgreSQL v8.1</entry> + <entry>PostgreSQL v8.2 JDBC3 with SSL (build 504)</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="Running_JUnit_Tests"> + <title>Running JUnit Tests</title> + <para> - Provide a summary of new features applicable to this release. + It is recommended that the Hibernate unit tests be executed using the same dialect and version of JDBC that will be used in production, to ensure that the configuration setting, <property>hibernate.jdbc.batch_versioned_data</property>, is set properly. The value for <property>hibernate.jdbc.batch_versioned_data</property> determines if Hibernate will use batches for updating versioned data (an optimization). </para> - </section> - <section id="Bug_Fixes"> - <title>Bug Fixes</title> <para> - The following bugs have been addressed and resolved in this release. + Optimistic locking relies on the ability to obtain the number of rows updated. If the JDBC driver does not return update counts for each command in a batch, then <property>hibernate.jdbc.batch_versioned_data</property> should be set to "false". </para> + <para> + The unit tests use the settings in <filename>etc/hibernate.properties</filename>. The value for <property>hibernate.jdbc.batch_versioned_data</property> is set to <parameter>true</parameter> in that file. If the unit tests involving optimistic locking fail, then the appropriate value for this flag is <parameter>false</parameter>. Some versions of Oracle JDBC do not support returning update counts for each command in a batch, so it is particularly important to test using the same version of JDBC as will be used in production. + </para> + + <section id="Expected_JUnit_Failures_And_Tests"> + <title>Expected failures and tests</title> + <para> + The following unit tests are expected to fail: + </para> + + <formalpara> + <title> + Ehcache tests (Ehcache is not provided in this distribution): + </title> + <para> + org.hibernate.test.cache.ehcache.EhCacheTest.testQueryCacheInvalidation + org.hibernate.test.cache.ehcache.EhCacheTest.testEmptySecondLevelCacheEntry + org.hibernate.test.cache.ehcache.EhCacheTest.testStaleWritesLeaveCacheConsistent + </para> + </formalpara> + <formalpara> + <title>Expected unit test failure against MS SQL 2005</title> + <para> + org.hibernate.test.legacy.MasterDetailTest.testCachedCollectionRefresh + </para> + </formalpara> + <formalpara> + <title> + "FailureExpected" tests (known issues to be addressed in the future): + </title> + <para> + org.hibernate.test.hql.ASTParserLoadingTest.testParameterTypeMismatchFailureExpected + org.hibernate.test.hql.CriteriaHQLAlignmentTest.testCriteriaAggregationReturnTypeFailureExpected + org.hibernate.test.hql.HQLTest.testEmptyInListFailureExpected + org.hibernate.test.hql.HQLTest.testMaxindexHqlFuncttestMultipleElementAccessorOperatorsFailureExpectedionInElementAccessorFailureExpected + org.hibernate.test.hql.HQLTest.testMultipleElementAccessorOperatorsFailureExpected + org.hibernate.test.hql.HQLTest.testKeyManyToOneJoinFailureExpected + org.hibernate.test.hql.HQLTest.testDuplicateExplicitJoinFailureExpected + org.hibernate.test.keymanytoone.bidir.component.EagerKeyManyToOneTest.testLoadEntityWithEagerFetchingToKeyManyToOneReferenceBackToSelfFailureExpected + org.hibernate.test.legacy.SQLLoaderTest.testReturnPropertyComponentRenameFailureExpected + org.hibernate.test.readonly.ReadOnlyTest.testReadOnlyOnProxiesFailureExpected + org.hibernate.test.sql.hand.query.NativeSQLQueriesTest.testCompositeIdJoinsFailureExpected + </para> + </formalpara> </section> </section> - <section id="Documentation"> + <section id="Fixed_Issues" xreflabel="fixed issues"> + <title>Fixed Issues</title> + <formalpara> + <title> + <ulink url="http://jira.jboss.org/jira/browse/HIBERNATE-92">HIBERNA... - Update dependencies to be consistent with EAP 4.2 CP03 + </title> + <para> + This release bundle has been made consistent with the Hibernate release embedded in JBoss EAP version 4.2 CP03. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://jira.jboss.org/jira/browse/JBPAPP-357">JBPAPP-357 / HHH-2542</ulink> - <parameter>NullPointerException</parameter> in <property>TypeFactory.replaceAssociations</property> for <property>ComponentType</property> + </title> + <para> + This bug which arises when a <literal>NULL</literal> value has been passed into <property>ComponentType</property> object has been fixed. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-1... / HHH-1569</ulink> - Immutable Natural Id can fail with ArrayIndexOutOfBounds in some cases + </title> + <para> + When the <property>natural-id</property> has been set with <parameter>mutable</parameter> as <parameter>false</parameter>, then it may cause <parameter>ArrayIndexOutOfBounds</parameter> errors in some cases. This issue has been resolved. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-2... / HHH-2631</ulink> - Leaking <property>PreparedStatement</property> and <parameter>ResultSet</parameter> via <property>CollectionLoadContext</property> instances maintained in Map <property>collectionLoadContexts</property> in <property>LoadContexts</property> + </title> + <para> + The number of <property>PreparedStatement</property> and <parameter>ResultSet</parameter> instances had increased causing memory consumption in one instance. The JIRA issue contains the full details. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-2... / HHH-2662</ulink> - Workarounds for <application>PostgreSQL</application> issues arising from test suite + </title> + <para> + Few issues that arose from test suite with <application>PostgreSQL</application> has been resolved. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://jira.jboss.org/jira/browse/JBPAPP-743">JBPAPP-743 / HHH-2663</ulink> - Map <property>java.sql.Types.REAL</property> to Hibernate <property>FloatType</property> + </title> + <para> + This is an added functionality to allow the use of <property>REAL</property> type. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://jira.jboss.org/jira/browse/JBPAPP-744">JBPAPP-744 / HHH-2665</ulink> - Split <property>Oracle9Dialect</property> into <property>Oracle9iDialect</property> and <property>Oracle10gDialect</property> + </title> + <para> + Hibernate now checks <application>Oracle</application> database dialects for versions 9i and 10g. + </para> + </formalpara> + <formalpara> + <title> + <ulink url="http://jira.jboss.org/jira/browse/JBPAPP-188">JBPAPP-188 / HHH-2630</ulink> - Hibernate Dialect is not auto-detected for <application>Sybase ASE</application> and <application>DB2</application> + </title> + <para> + Auto detection of these two dialects are now enabled in this release. + </para> + </formalpara> + + </section> + <section id="Documentation" xreflabel="documentation"> <title>Documentation</title> - <para> - List all the documentation links here and where to find them. - </para> + <itemizedlist> + <listitem> + <para> + The <citetitle pubwork="book">Hibernate reference guide</citetitle> is a comprehensive source of material for learning about Hibernate. It kicks off with an example to get you started with Hibernate, lists the major functionality of Hibernate, offers design solutions and suggests best practises. + </para> + </listitem> + <listitem> + <para> + The <citetitle pubwork="book">Hibernate Core API Reference</citetitle> guide will be helpful during application development. + </para> + </listitem> + </itemizedlist> </section> <section id="Product_Support"> - <title>Product Support</title> - <para> - List all the links here. - </para> + <title>Product Support and License Website Links</title> + <formalpara> + <title>Support Processes</title> + <para> + <ulink url="http://www.redhat.com/support/process/">http://www.redh... + </para> + </formalpara> + + <formalpara> + <title> + Production Support Scope of Coverage + </title> + <para> + <ulink url="http://www.redhat.com/support/policy/soc/production">ht... + </para> + </formalpara> + + <formalpara> + <title> + Production Support Service Level Agreement + </title> + + <para> + <ulink url="http://www.redhat.com/support/policy/sla/production/">h... + </para> + </formalpara> + + <formalpara> + <title> + Developer Support Scope of Coverage + </title> + + <para> + <ulink url="http://www.redhat.com/support/policy/soc/developer/">ht... + </para> + </formalpara> + + <formalpara> + <title> + Developer Support Service Level Agreement + </title> + + <para> + <ulink url="http://www.redhat.com/support/policy/sla/developer/">ht... + </para> + </formalpara> + + <formalpara> + <title> + Product Update and Support Policy by Product + </title> + + <para> + <ulink url="http://www.redhat.com/security/updates/jboss_notes/">ht... + </para> + </formalpara> + + <formalpara> + <title> + JBoss End User License Agreement + </title> + + <para> + <ulink url="http://www.redhat.com/licenses/jboss_eula.html">http://... + </para> + </formalpara> </section> </article>