Hibernate

Release Notes

Copyright © 2008 Red Hat Inc.. This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License (which is presently available at http://creativecommons.org/licenses/by-nc-sa/3.0/).

Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries.

All other trademarks referenced herein are the property of their respective owners.

The GPG fingerprint of the security@redhat.com key is:

CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E

1801 Varsity Drive
RaleighNC 27606-2072
USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle ParkNC 27709
USA

Abstract

This document provides the release notes for Hibernate .


1.  Overview

These release notes contain important information regarding Hibernate release. This document lists the necessary software that must be installed before using Hibernate. Users of previous versions of Hibernate may refer to Issues to find the latest JIRA issue fixes. In addition, the latest documentation, product support and license links are also provided.

1.1. Background

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. However, please read these release notes for more information on software that are compatible with this version of Hibernate release.

2. Installation And Migration Guide

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.

2.1. Prerequisites

The software listed in this section needs to be installed before using Hibernate, running unit tests or running the demo.

2.1.1. Using Hibernate

JDK 1.5

To build Java applications with Hibernate you must have JDK 1.5 version installed. While this version is compatible with Hibernate, version 1.4 is no longer supported. Once installation of JDK 1.5 version is completed, you must set the environment variables.

2.1.2. Testing Hibernate and Running the demo

To test Hibernate and run the demo, you will need Apache Ant 1.7.0 and JUnit 3.8.1.

  • Apache Ant 1.7.0

    Apache Ant can be downloaded from this link. You must set the ANT_HOME 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.

  • JUnit 3.8.1

    To run JUnit tests, you may use JUnit 3.8.1 version which can be downloaded from here. After installation, copy junit.jar to $ANT_HOME/lib directory. Section 3, “Running JUnit Tests” provides further notes on running JUnit tests.

2.2. Installation Notes

Extract files from the Hibernate ZIP 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 these jar files. Settings for individual IDEs differ, but normally you would add the jar files as external library files.

2.3. Migration Notes

2.3.1. Configuring your database

To use your database with Hibernate, copy your JDBC driver into the lib directory. Then edit the hibernate.properties file in the etc directory. Additional configuration notes are available in Hibernate Reference Guide, chapter 3: Configuration. The Hibernate supported databases are: Oracle9i, Oracle10g, MS SQL 2005, PostgreSQL and MySQL.

2.3.1.1. Oracle users

OracleDialect and Oracle9Dialect have been deprecated. Oracle8iDialect, Oracle9iDialect, or Oracle10gDialect should be used instead.

3. Running JUnit Tests

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, hibernate.jdbc.batch_versioned_data, is set properly. The value for hibernate.jdbc.batch_versioned_data determines if Hibernate will use batches for updating versioned data (an optimization).

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 hibernate.jdbc.batch_versioned_data should be set to "false".

The unit tests use the settings in etc/hibernate.properties. The value for hibernate.jdbc.batch_versioned_data is set to true in that file. If the unit tests involving optimistic locking fail, then the appropriate value for this flag is false. 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.

3.1. Expected failures and tests

The following unit tests are expected to fail:

4. Issues

4.1. Issue type: Bugs

[HHH-2683] - "datediff" is declared as NoArgSQLFunction in H2Dialect, but actually accepts 3 arguments.  This issue is now resolved. It has been changed from NoArgSQLFunction to StandardSQLFunction.

[HHH-3257] - Content images not displayed. This issue affects the use of jdocbook plugin. useRelativeImageUris is now set to false to fix this error.

[HHH-3260] - Hibernate wraps a listener init or destroy exception into an AssertionFailure. AssertionFailure is now replaced with HibernateException to catch listener exception errors.

[HHH-3261] - Do not wrap exceptions raised by event listeners (at init or destroy time). Use of AssertionFailureExceptions has been removed.

[HHH-3265] - change license url in pom to http://www.gnu.org/licenses/lgpl-2.1.html. The license information has been updated to version 2.1 of LGPL.

[HHH-3266] - distribution bundle missing jta dependency. The missing dependency set has been updated in the dist.xml file.

[HHH-3272] - use of Integer.valueOf(int) which is not available in JDK 1.4. This has been updated for the compatible JDK version. Instead of Integer.valueOf(int), new Integer(int) is used.

[HHH-3282] - DB2Dialect should report supportsLobValueChangePropogation() as false. The above change has been incorporated.

4.2. Improvement

[HHH-1786] JTASessionContext.CleanupSynch does not remove sessions from currentSessionMap. 

[HHH-2060] - To be able to use <generator> with <composite-id>. Functionality to use <generator> has been incorporated.

[HHH-2506] - Make javassist the default ByteCodeProvider. This is now incorporated into this release.

[HHH-2875] - repackage cglib/asm under org.hibernate namespace. 

[HHH-3229] - Make cascade rules more transparent/explicit/deterministic. 

[HHH-3269] - upgrade to jDocBook plugin version 2.1.1. 

[HHH-3276] - review proposed new doc styling. 

[HHH-3283] - protect BulkManipulationTest#testInsertWithGeneratedTimestampVersion where Dialect#supportsParametersInInsertSelect == false. 

[HHH-3286] - Move ACTION_PERSIST_SKIPLAZY from HEM to Core in CascadingAction. 

4.3. New Feature

[HHH-3279] - create series of maven plugins offering functionality of the ant tools. 

4.4. Task

[HHH-3270] - follow up on documentation license questions. 

5. Documentation

  • The Hibernate reference guide 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.

  • The Hibernate Core API Reference guide will be helpful during application development.

6. Product Support and License Website Links

Support Processes.  http://www.redhat.com/support/process/

Production Support Scope of Coverage .  http://www.redhat.com/support/policy/soc/production

Production Support Service Level Agreement .  http://www.redhat.com/support/policy/sla/production/

Developer Support Scope of Coverage .  http://www.redhat.com/support/policy/soc/developer/

Developer Support Service Level Agreement .  http://www.redhat.com/support/policy/sla/developer/

Product Update and Support Policy by Product .  http://www.redhat.com/security/updates/jboss_notes/

JBoss End User License Agreement .  http://www.redhat.com/licenses/jboss_eula.html