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

The object retrieved from the session factory in Hibernate 3 implements both the pure
Hibernate 3 org.hibernate.Session interface and a Hibernate 2-friendly org.hibernate.
classic.Session interface. By using a classic Session reference instead of the usual one, you
will have access to the methods that have now been deprecated. Despite their deprecated sta-
tus, all of these methods are fully implemented at the present time. Most of them are back-
ward-compatible with their Hibernate 2 counterparts—but the delete(String) method has
changed slightly in that deletions are no longer cascaded to associated entities.
A fully converted Hibernate 3 application will not need to invoke any of these methods,
so you should use a reference to the standard interface unless you're absolutely compelled
by existing logic.
Other deprecated features reside in the classic package and its subpackages. Notable
examples are listed in Table D-2.

Table D-2. Feature Replacements in Hibernate 3

Feature Location in Hibernate 3 Use in Preference

org.hibernate.classic Life cycle Interceptor or event

Validatable

org.hibernate.classic

Interceptor or event

Some of the changes to Hibernate 3 have not justified the creation of a replacement class.
A few methods will have been removed, replaced, or renamed. In these few cases, if you do not
want to run Hibernate 2 and 3 side by side, you will be forced to update your code. When com-
pilation produces errors, consult the javadoc API at http://hibernate.org to see whether the
API has changed, and to determine how to alter your code to work in the new environment. In
practice, there are few changes in the core API between versions 2 and 3, and the changes that
do exist have well-signposted successors in the new API documents.

Additions
The Event class is new to Hibernate 3. If you are familiar with the Interceptor class (which is
retained), you will have some idea of what to expect. This topic is discussed in Appendix A.
The Criteria and Filter APIs have been extended considerably. These are discussed in
detail in Chapter 11.
The flexibility of the mappings has been improved. For example, the join element per-
mits a single class to be represented by multiple tables. Support for stored procedures allows
better integration with legacy databases. The mapping file format is discussed in Chapter 8,
and support for stored procedures and other new features is discussed in Appendix A.

Changes to Tools and Libraries
As you may expect, the libraries upon which Hibernate is based have changed in version 3.
Some have been added and others have been brought up to date. Rather than enumerate
these here, we refer you to the lib/README.txt file in your Hibernate 3 distribution, which
explains in detail whether or not individual libraries are required, and what purpose each
serves.