Hibernate2 Porting Guidelines
Porting Hibernate 1.x applications to Hibernate2Hibernate 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 ;)
|