Hibernate 3.1 is a relatively minor upgrade to Hibernate 3.0 with many new features.  IN other words, we expect it to be a drop-in replacement for Hibernate 3.0. You should be able to upgrade to 3.1 by using the new JAR (and after checking the 3rd party library dependencies).  However, some changes made to the Hibernate 3.1 core might lead to problems with code relying on old side effects.

You may want to browse the Hibernate Core Migration Guide : 3.0 first.

API changes

• NamingStrategy interface - If you implemented a custom NamingStrategy you will have to add implementations of the new methods of that interface, or extend DefaultNamingStrategy or ImprovedNamingStrategy.
• Event Listeners - You now can plug several event listeners per event, so the EventListeners API changed to accept an array of listeners instead of a single listener object per event.  Your home-made listeners extending the Hibernate default one are likely to work but you might want to consider using the ability to chain those listeners instead of inheriting from the default one.
• hbm2java - hbm2java is no longer part of Hibernate Core as it has been rewritten and integrated into Hibernate Tools. In that process some features have been removed because they were broken or not maintained, see Hbm2javaCompability.

Metadata Changes

• N/A

Query Language Changes

• Invalid query checking - Hibernate 3.1 is much more strict in checking for invalid queries, some of which actually worked purely by side effect in earlier versions. Some examples:
  • Hibernate never supported "from Entity e where e.collection.property" but needs an explicit join for collection elements "from Entity e join e.collection c where c.property".
  • Furthermore, a query that specifies join fetching, but the owner of the fetched association was not present in the select list throws an exception now: "select b from A join fetch a.bees b" - this query makes no sense, remove the "fetch".

Configuration changes

• JDBC connection release mode - Previous versions defaulted to ON_CLOSE for backwards compatibility with Hibernate 2.x. As of 3.1, however, the default is now "auto". Typically it is best to simply not override this default. If your application depends on some quirk of the old behavior (like having the same connection available beyond transaction boundaries, etc) then you may need to tweak this; but you should view this as a problem with your application logic and fix that. Or, if you believe that you can "read data without or outside of a transaction", you will likely face problems in Hibernate 3.1. Of course, there can be no data access outside of a transaction, be it read or write access, and Hibernate 3.1 makes it much more difficult to write bad code that relies on auto-commit side effects. See section 11.5. (Connection Release Modes) in the 3.1 documentation for more details. Important known issue: If you call session.connection() in Hibernate 3.1.0, you are responsible to close() the JDBC Connection yourself! Note that this might change again in a future release.
• Event listeners - Event listeners now support several event listeners per event. hibernate.cfg.xml should use the more appropriate <event> element to configure them instead of the <listener> one.