Upgrading from Hibernate 2 - Beginning Hibernate: From Novice to Professional - page 315

New Features and Support for Old Ones
If you are a Hibernate 2 developer and you have browsed through the earlier chapters, you will
have realized that Hibernate 3 offers a lot of new features. You will have also realized that some
of the Hibernate 2 features that you rely on may no longer be supported in version 3. For the
most part, though, this is not the case.

Changes and Deprecated Features
If you do not plan to take advantage of the Hibernate 3 features in any of your existing code,
you can, as discussed, simply run the two versions side by side without concern. If you are
prepared to make some changes to your existing code, then it is better to take the opportunity
to update your existing code to use Hibernate 3 directly. In order to make this second choice a
little easier, Hibernate 3 provides a number of “deprecated” APIs that permit fewer changes
than a full-blown conversion.
This reduces the immediate impact of the change, and allows you to conduct the rest of
the conversion at your leisure, while still allowing you to remove the legacy Hibernate 2
libraries from your application.

n Tip Hibernate exceptions are now thrown as unchecked exceptions. This will not impact existing code,
but you may want to revisit APIs that explicitly declare HibernateException s. This change is intended to
increase the clarity of API signatures by removing the need for the explicit throws clause in code, which
uses Hibernate but does not catch its exceptions. There are ongoing debates over the relative merits of the
two approaches, but certainly the change from checked to unchecked does not introduce any incompatibili-
ties (whereas the reverse would).

Some changes to HQL have occurred between versions 2 and 3. If you have a substantial
body of existing HQL syntax, you can elect to retain the old syntax. The selection is made with
the hibernate.query.factoryclass configuration attribute, which selects the class to load for
translating HQL into database queries. The options are listed in Table D-1.

Table D-1. The HQL Processing Classes

Query Factory Class HQL Version

org.hibernate.hql.ast.ASTQueryTranslatorFactory 3 (default)

org.hibernate.hql.classic.ClassicQueryTranslatorFactory 2

It is not possible to switch between the two query translators within a SessionFactory
instance. Because HQL queries are not parsed until run time 1 , you will need to run extensive tests
to ensure that your modified queries are correct if you decide to convert to the Hibernate 3 syntax.

1. Named queries were introduced in Hibernate 3. These are stored in the mapping file or the annota-
tions, and are parsed on application initialization—so while they are still parsed at run time, you will
not need to run extensive tests to spot syntactical problems with them.