HIBERNATE JBoss.org
 |  Register  | 
     
News 
About 
   Feature List 
   Road Map 
Documentation 
   Related Projects 
   External Documentation 
Download 
Forum & Mailinglists 
Support & Training 
JIRA Issue Tracking
Wiki Community Area


Hibernate Public Training Courses


Get Hibernate in Action eBook!


JavaWorld 2003 Finalist


Jolt Award 2004 Winner
      
Documentation > Hibernate2 Porting Guidelines

Hibernate2 Porting Guidelines

Porting Hibernate 2.0 applications to Hibernate 2.1

Hibernate 2.1 is intended to be completely backward compatible with Hibernate 2.0.x. Please follow these steps for an easy upgrade:

  • make sure you replace not only the Hibernate 2.0 JAR libary with the newer version, but also the dependent 3rd party libraries
  • check the lib/README.txt in the Hibernate 2.1 distribution for a list of required and optional libraries
  • the DTD for mapping and configuration hasn't changed, you should still use the DTD declarations from 2.0
  • if you run into problems after you upgraded, make sure to read the FAQs on this website and use the search engine to find solutions for exceptions

The Hibernate builtin JDBC connection pool no longer supports caching of PreparedStatements, so it is more important now to not use it in production systems. Use the Datasources provided by your Application Server or the DBCP, C3P0, or the Proxool JDBC connection pool.

Porting Hibernate 1.x applications to Hibernate2

Hibernate was grown, rather than designed. At every step, new functionality was added to meet the current needs of actual users. As a result, the project has gone in directions not necessarily intended when it was first conceived. This has been an excellent approach. We have very little in the way of bloated, unused features and those features that do exist usually provide efficient solutions to common cases.

Throughout this growing process, we have tried very hard to maintain a reasonable level of backward compatibility. This has meant sticking with some decisions that I knew were less than perfect. However, it has become clear that a few things now need to break. Rather than breaking them one by one over the next year or so, causing disruption at each stage, I decided we should fix all the things that needed redesigning in one shot, with the expectation that no further incompatible changes will be needed to the existing (mature) functionality.

Hibernate2 features substantial redesign in the following areas

  • id generator framework
  • configuration APIs
  • interceptor callbacks
  • collections
  • package organization and naming
  • exception model

along with

  • changes to the mapping document format and default attribute values
  • a number of cool new features

Hibernate2 is not a drop-in replacement for Hibernate 1.2. Code changes will certainly be required. However, we expect that these changes will be of the trivial, automatable variety and that no application redesign will be necessary (unless you are using toplevel collections).

To port an application from Hibernate 1.2 to Hibernate2, follow the following steps

(1) remove any use of toplevel collections

(2) rewrite config code to use the new API

(3) s/cirrus.hibernate/net.sf.hibernate/g

(4) for mapping documents:

  • s/readonly/inverse/g
  • s/role/name/g
  • s/hibernate-mapping-1.1.dtd/hibernate-mapping-2.0.dtd
  • replace old id generator strategy names with new names
  • add name attribute to all <param> elements
  • add unsaved-value="any" to <id> elements with no unsaved-value attribute

Note that unsaved-value now defaults to null

(5) s/SQLException/JDBCException/g

(6) add some extra (empty) methods to your Interceptor, if you have one

(7) rework any custom IdentifierGenerator that accepts parameters

(8) s/cirrus.hibernate.sql/net.sf.hibernate.dialect/g

(9) hibernate.query.imports is no longer supported - instead use the new <import> mapping element (only needed for classes which are not entities).

For most applications, we do not expect this to be very difficult. As a reward, you get some nice new features ;)

      

coWiki