Preface

Working with both Object-Oriented software and Relational Databases can be cumbersome and time consuming.
Development costs are significantly higher due to a paradigm mismatch between how data is represented in
objects versus relational databases. Hibernate is an Object/Relational Mapping solution for Java environments.
The term Object/Relational Mapping refers to the technique of mapping data from an object model representation
to a relational data model representation (and visa versa). See
http://en.wikipedia.org/wiki/Object-relational_mapping
for a good high-level discussion.

Note

While having a strong background in SQL is not required to use Hibernate, having a basic understanding of
the concepts can greatly help you understand Hibernate more fully and quickly. Probably the single
best background is an understanding of data modeling principles. You might want to consider these resources
as a good starting point:

Hibernate not only takes care of the mapping from Java classes to database tables (and from Java data types to
SQL data types), but also provides data query and retrieval facilities. It can significantly reduce
development time otherwise spent with manual data handling in SQL and JDBC. Hibernate’s design goal is to
relieve the developer from 95% of common data persistence-related programming tasks by eliminating the need for
manual, hand-crafted data processing using SQL and JDBC. However, unlike many other persistence solutions,
Hibernate does not hide the power of SQL from you and guarantees that your investment in relational technology
and knowledge is as valid as always.

Hibernate may not be the best solution for data-centric applications that only use stored-procedures to
implement the business logic in the database, it is most useful with object-oriented domain models and business
logic in the Java-based middle-tier. However, Hibernate can certainly help you to remove or encapsulate
vendor-specific SQL code and will help with the common task of result set translation from a tabular
representation to a graph of objects.

If you are new to Hibernate and Object/Relational Mapping or even Java,
please follow these steps:

Read Chapter 1, Tutorial for a tutorial with step-by-step
instructions. The source code for the tutorial is included in the
distribution in the doc/reference/tutorial/
directory.

View the eg/ directory in the Hibernate
distribution. It contains a simple standalone application. Copy your
JDBC driver to the lib/ directory and edit
etc/hibernate.properties, specifying correct values for
your database. From a command prompt in the distribution directory,
type ant eg (using Ant), or under Windows, type
build eg.

Use this reference documentation as your primary source of
information. Consider reading [JPwH]
if you need more help with application design, or if you prefer
a step-by-step tutorial. Also visit
http://caveatemptor.hibernate.org
and download the example application from [JPwH].

FAQs are answered on the Hibernate website.

Links to third party demos, examples, and tutorials are maintained
on the Hibernate website.

The Community Area on the Hibernate website is a good resource for
design patterns and various integration solutions (Tomcat, JBoss AS,
Struts, EJB, etc.).

There are a number of ways to become involved in the Hibernate community, including

Intended for new users, this chapter provides an step-by-step introduction
to Hibernate, starting with a simple application using an in-memory database. The
tutorial is based on an earlier tutorial developed by Michael Gloegl. All
code is contained in the tutorials/web directory of the project
source.

Important

This tutorial expects the user have knowledge of both Java and
SQL. If you have a limited knowledge of JAVA or SQL, it is advised
that you start with a good introduction to that technology prior
to attempting to learn Hibernate.

Note

The distribution contains another example application under
the tutorial/eg project source
directory.

1.1. Part 1 - The first Hibernate Application

For this example, we will set up a small database application that can store
events we want to attend and information about the host(s) of these events.

Note

Although you can use whatever database you feel comfortable using, we
will use HSQLDB
(an in-memory, Java database) to avoid describing installation/setup of any particular
database servers.

1.1.1. Setup

The first thing we need to do is to set up the development environment. We
will be using the "standard layout" advocated by alot of build tools such
as Maven.
Maven, in particular, has a
good resource describing this
layout.
As this tutorial is to be a web application, we will be creating and making
use of src/main/java, src/main/resources
and src/main/webapp directories.

We will be using Maven in this tutorial, taking advantage of its
transitive dependency management capabilities as well as the ability of
many IDEs to automatically set up a project for us based on the maven descriptor.

Tip

It is not a requirement to use Maven. If you wish to use something else to
build this tutorial (such as Ant), the layout will remain the same. The only
change is that you will need to manually account for all the needed
dependencies. If you use something like
Ivy
providing transitive dependency management you would still use the dependencies
mentioned below. Otherwise, you'd need to grab all
dependencies, both explicit and transitive, and add them to the project's
classpath. If working from the Hibernate distribution bundle, this would mean
hibernate3.jar, all artifacts in the
lib/required directory and all files from either the
lib/bytecode/cglib or lib/bytecode/javassist
directory; additionally you will need both the servlet-api jar and one of the slf4j
logging backends.

Save this file as pom.xml in the project root directory.

1.1.2. The first class

Next, we create a class that represents the event we want to store in the
database; it is a simple JavaBean class with some properties:

This class uses standard JavaBean naming conventions for property
getter and setter methods, as well as private visibility for the
fields. Although this is the recommended design, it is not required.
Hibernate can also access fields directly, the benefit of accessor
methods is robustness for refactoring.

The id property holds a unique identifier value
for a particular event. All persistent entity classes (there are
less important dependent classes as well) will need such an identifier
property if we want to use the full feature set of Hibernate. In fact,
most applications, especially web applications, need to distinguish
objects by identifier, so you should consider this a feature rather
than a limitation. However, we usually do not manipulate the identity
of an object, hence the setter method should be private. Only Hibernate
will assign identifiers when an object is saved. Hibernate can access
public, private, and protected accessor methods, as well as public,
private and protected fields directly. The choice is up to you and
you can match it to fit your application design.

The no-argument constructor is a requirement for all persistent
classes; Hibernate has to create objects for you, using Java
Reflection. The constructor can be private, however package or public
visibility is required for runtime proxy generation and efficient data
retrieval without bytecode instrumentation.

Save this file to the src/main/java/org/hibernate/tutorial/domain
directory.

1.1.3. The mapping file

Hibernate needs to know how to load and store objects of the
persistent class. This is where the Hibernate mapping file
comes into play. The mapping file tells Hibernate what table in
the database it has to access, and what columns in that table
it should use.

Hibernate DTD is sophisticated. You can use it for auto-completion
of XML mapping elements and attributes in your editor or IDE.
Opening up the DTD file in your text editor is the easiest way to
get an overview of all elements and attributes, and to view the
defaults, as well as some comments. Hibernate will not load the
DTD file from the web, but first look it up from the classpath of
the application. The DTD file is included in
hibernate-core.jar (it is also included in the
hibernate3.jar, if using the distribution bundle).

Important

We will omit the DTD declaration in future examples to shorten the code. It is,
of course, not optional.

Between the two hibernate-mapping tags, include a
class element. All persistent entity classes (again, there
might be dependent classes later on, which are not first-class entities) need
a mapping to a table in the SQL database:

So far we have told Hibernate how to persist and load object of
class Event to the table
EVENTS. Each instance is now represented by a
row in that table. Now we can continue by mapping the unique
identifier property to the tables primary key. As we do not want
to care about handling this identifier, we configure Hibernate's
identifier generation strategy for a surrogate primary key column:

The id element is the declaration of the
identifier property. The name="id" mapping
attribute declares the name of the JavaBean property and tells
Hibernate to use the getId() and
setId() methods to access the property. The
column attribute tells Hibernate which column of the
EVENTS table holds the primary key value.

The nested generator element specifies the
identifier generation strategy (aka how are identifier values
generated?). In this case we choose native,
which offers a level of portability depending on the configured
database dialect. Hibernate supports database generated, globally
unique, as well as application assigned, identifiers. Identifier
value generation is also one of Hibernate's many extension points
and you can plugin in your own strategy.

Similar to the id element, the
name attribute of the
property element tells Hibernate which getter
and setter methods to use. In this case, Hibernate will search
for getDate(), setDate(),
getTitle() and setTitle()
methods.

Note

Why does the date property mapping include the
column attribute, but the title
does not? Without the column attribute, Hibernate
by default uses the property name as the column name. This works for
title, however, date is a reserved
keyword in most databases so you will need to map it to a different name.

The title mapping also lacks a type attribute. The
types declared and used in the mapping files are not Java data types; they are not SQL
database types either. These types are called Hibernate mapping types,
converters which can translate from Java to SQL data types and vice versa. Again,
Hibernate will try to determine the correct conversion and mapping type itself if
the type attribute is not present in the mapping. In some cases this
automatic detection using Reflection on the Java class might not have the default you
expect or need. This is the case with the date property. Hibernate cannot
know if the property, which is of java.util.Date, should map to a
SQL date, timestamp, or time column.
Full date and time information is preserved by mapping the property with a
timestamp converter.

Tip

Hibernate makes this mapping type determination using reflection when the mapping files
are processed. This can take time and resources, so if startup performance is important
you should consider explicitly defining the type to use.

Save this mapping file as
src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml.

1.1.4. Hibernate configuration

At this point, you should have the persistent class and its mapping
file in place. It is now time to configure Hibernate. First let's set up
HSQLDB to run in "server mode"

Note

We do this so that the data remains between runs.

We will utilize the Maven exec plugin to launch the HSQLDB server
by running:
mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial"
You will see it start up and bind to a TCP/IP socket; this is where
our application will connect later. If you want to start
with a fresh database during this tutorial, shutdown HSQLDB, delete
all files in the target/data directory,
and start HSQLDB again.

Hibernate will be connecting to the database on behalf of your application, so it needs to know
how to obtain connections. For this tutorial we will be using a standalone connection
pool (as opposed to a javax.sql.DataSource). Hibernate comes with
support for two third-party open source JDBC connection pools:
c3p0
and
proxool.
However, we will be using the Hibernate built-in connection pool for this tutorial.

Caution

The built-in Hibernate connection pool is in no way intended for production use. It
lacks several features found on any decent connection pool.

For Hibernate's configuration, we can use a simple hibernate.properties file, a
more sophisticated hibernate.cfg.xml file, or even complete
programmatic setup. Most users prefer the XML configuration file:

Note

Notice that this configuration file specifies a different DTD

You configure Hibernate's SessionFactory. SessionFactory is a global
factory responsible for a particular database. If you have several databases, for easier
startup you should use several <session-factory> configurations in
several configuration files.

The first four property elements contain the necessary
configuration for the JDBC connection. The dialect property
element specifies the particular SQL variant Hibernate generates.

Tip

Hibernate's automatic session management for persistence contexts is particularly useful
in this context. The hbm2ddl.auto option turns on automatic generation of
database schemas directly into the database. This can also be turned
off by removing the configuration option, or redirected to a file with the help of
the SchemaExport Ant task. Finally, add the mapping file(s)
for persistent classes to the configuration.

Save this file as hibernate.cfg.xml into the
src/main/resources directory.

1.1.5. Building with Maven

We will now build the tutorial with Maven. You will need to
have Maven installed; it is available from the
Maven download page.
Maven will read the /pom.xml file we created
earlier and know how to perform some basic project tasks. First,
lets run the compile goal to make sure we can compile
everything so far:

1.1.6. Startup and helpers

It is time to load and store some Event
objects, but first you have to complete the setup with some
infrastructure code. You have to startup Hibernate by building
a global org.hibernate.SessionFactory
object and storing it somewhere for easy access in application code. A
org.hibernate.SessionFactory is used to
obtain org.hibernate.Session instances.
A org.hibernate.Session represents a
single-threaded unit of work. The
org.hibernate.SessionFactory is a
thread-safe global object that is instantiated once.

We will create a HibernateUtil helper class that
takes care of startup and makes accessing the
org.hibernate.SessionFactory more convenient.

Save this code as
src/main/java/org/hibernate/tutorial/util/HibernateUtil.java

This class not only produces the global
org.hibernate.SessionFactory reference in
its static initializer; it also hides the fact that it uses a
static singleton. We might just as well have looked up the
org.hibernate.SessionFactory reference from
JNDI in an application server or any other location for that matter.

If you give the org.hibernate.SessionFactory
a name in your configuration, Hibernate will try to bind it to
JNDI under that name after it has been built. Another, better option is to
use a JMX deployment and let the JMX-capable container instantiate and bind
a HibernateService to JNDI. Such advanced options are
discussed later.

You now need to configure a logging
system. Hibernate uses commons logging and provides two choices: Log4j and
JDK 1.4 logging. Most developers prefer Log4j: copy log4j.properties
from the Hibernate distribution in the etc/ directory to
your src directory, next to hibernate.cfg.xml.
If you prefer to have
more verbose output than that provided in the example configuration, you can change the settings. By default, only the Hibernate startup message is shown on stdout.

The tutorial infrastructure is complete and you are now ready to do some real work with
Hibernate.

1.1.7. Loading and storing objects

We are now ready to start doing some real work with Hibernate.
Let's start by writing an EventManager class
with a main() method:

In createAndStoreEvent() we created a new
Event object and handed it over to Hibernate.
At that point, Hibernate takes care of the SQL and executes an
INSERT on the database.

A org.hibernate.Session is designed to
represent a single unit of work (a single atomic piece of work
to be performed). For now we will keep things simple and assume
a one-to-one granularity between a Hibernate
org.hibernate.Session and a database
transaction. To shield our code from the actual underlying
transaction system we use the Hibernate
org.hibernate.Transaction API.
In this particular case we are using JDBC-based transactional
semantics, but it could also run with JTA.

What does sessionFactory.getCurrentSession() do?
First, you can call it as many times and anywhere you like
once you get hold of your
org.hibernate.SessionFactory.
The getCurrentSession() method always returns
the "current" unit of work. Remember that we switched
the configuration option for this mechanism to "thread" in our
src/main/resources/hibernate.cfg.xml?
Due to that setting, the context of a current unit of work is bound
to the current Java thread that executes the application.

Important

Hibernate offers three methods of current session tracking.
The "thread" based method is not intended for production use;
it is merely useful for prototyping and tutorials such as this
one. Current session tracking is discussed in more detail
later on.

A org.hibernate.Session begins when the
first call to getCurrentSession() is made for
the current thread. It is then bound by Hibernate to the current
thread. When the transaction ends, either through commit or
rollback, Hibernate automatically unbinds the
org.hibernate.Session from the thread
and closes it for you. If you call
getCurrentSession() again, you get a new
org.hibernate.Session and can start a
new unit of work.

Related to the unit of work scope, should the Hibernate
org.hibernate.Session be used to execute
one or several database operations? The above example uses one
org.hibernate.Session for one operation.
However this is pure coincidence; the example is just not complex
enough to show any other approach. The scope of a Hibernate
org.hibernate.Session is flexible but you
should never design your application to use a new Hibernate
org.hibernate.Session for
every database operation. Even though it is
used in the following examples, consider
session-per-operation an anti-pattern.
A real web application is shown later in the tutorial which will
help illustrate this.

Here, we are using a Hibernate Query Language (HQL) query to load all existing
Event objects from the database. Hibernate will generate the
appropriate SQL, send it to the database and populate Event objects
with the data. You can create more complex queries with HQL. See Chapter 16, HQL: The Hibernate Query Language
for more information.

Now we can call our new functionality, again using the Maven exec plugin:
mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"

1.2. Part 2 - Mapping associations

So far we have mapped a single persistent entity class to a table in
isolation. Let's expand on that a bit and add some class associations.
We will add people to the application and store a list of events in
which they participate.

Create an association between these two entities. Persons
can participate in events, and events have participants. The design questions
you have to deal with are: directionality, multiplicity, and collection
behavior.

1.2.2. A unidirectional Set-based association

By adding a collection of events to the Person
class, you can easily navigate to the events for a particular person,
without executing an explicit query - by calling
Person#getEvents. Multi-valued associations
are represented in Hibernate by one of the Java Collection Framework
contracts; here we choose a java.util.Set
because the collection will not contain duplicate elements and the ordering
is not relevant to our examples:

Before mapping this association, let's consider the other side.
We could just keep this unidirectional or create another
collection on the Event, if we wanted to be
able to navigate it from both directions. This is not necessary,
from a functional perspective. You can always execute an explicit
query to retrieve the participants for a particular event. This
is a design choice left to you, but what is clear from this
discussion is the multiplicity of the association: "many" valued
on both sides is called a many-to-many
association. Hence, we use Hibernate's many-to-many mapping:

Hibernate supports a broad range of collection mappings, a
set being most common. For a many-to-many
association, or n:m entity relationship, an
association table is required. Each row in this table represents
a link between a person and an event. The table name is
declared using the table attribute of the
set element. The identifier column name in
the association, for the person side, is defined with the
key element, the column name for the event's
side with the column attribute of the
many-to-many. You also have to tell Hibernate
the class of the objects in your collection (the class on the
other side of the collection of references).

After loading a Person and an
Event, simply modify the collection using the
normal collection methods. There is no explicit call to
update() or save();
Hibernate automatically detects that the collection has been modified
and needs to be updated. This is called
automatic dirty checking. You can also try
it by modifying the name or the date property of any of your
objects. As long as they are in persistent
state, that is, bound to a particular Hibernate
org.hibernate.Session, Hibernate
monitors any changes and executes SQL in a write-behind fashion.
The process of synchronizing the memory state with the database,
usually only at the end of a unit of work, is called
flushing. In our code, the unit of work
ends with a commit, or rollback, of the database transaction.

You can load person and event in different units of work. Or
you can modify an object outside of a
org.hibernate.Session, when it
is not in persistent state (if it was persistent before, this
state is called detached). You can even
modify a collection when it is detached:

The call to update makes a detached object
persistent again by binding it to a new unit of work, so any
modifications you made to it while detached can be saved to
the database. This includes any modifications
(additions/deletions) you made to a collection of that entity
object.

This is not much use in our example, but it is an important concept you can
incorporate into your own application. Complete this exercise by adding a new action
to the main method of the EventManager and call it from the command line. If
you need the identifiers of a person and an event - the save() method
returns it (you might have to modify some of the previous methods to return that identifier):

This is an example of an association between two equally important
classes : two entities. As mentioned earlier, there are other
classes and types in a typical model, usually "less important".
Some you have already seen, like an int or a
java.lang.String. We call these classes
value types, and their instances
depend on a particular entity. Instances of
these types do not have their own identity, nor are they shared
between entities. Two persons do not reference the same
firstname object, even if they have the same
first name. Value types cannot only be found in the JDK , but
you can also write dependent classes yourself
such as an Address or
MonetaryAmount class. In fact, in a Hibernate
application all JDK classes are considered value types.

You can also design a collection of value types. This is
conceptually different from a collection of references to other
entities, but looks almost the same in Java.

1.2.4. Collection of values

Let's add a collection of email addresses to the
Person entity. This will be represented as a
java.util.Set of
java.lang.String instances:

The difference compared with the earlier mapping is the use of
the element part which tells Hibernate that the
collection does not contain references to another entity, but is
rather a collection whose elements are values types, here specifically
of type string. The lowercase name tells you
it is a Hibernate mapping type/converter. Again the
table attribute of the set
element determines the table name for the collection. The
key element defines the foreign-key column
name in the collection table. The column
attribute in the element element defines the
column name where the email address values will actually
be stored.

You can see that the primary key of the collection table is in fact a composite key that
uses both columns. This also implies that there cannot be duplicate email addresses
per person, which is exactly the semantics we need for a set in Java.

You can now try to add elements to this collection, just like we did before by
linking persons and events. It is the same code in Java:

This time we did not use a fetch query to
initialize the collection. Monitor the SQL log and try to
optimize this with an eager fetch.

1.2.5. Bi-directional associations

Next you will map a bi-directional association. You will make
the association between person and event work from both sides
in Java. The database schema does not change, so you will still
have many-to-many multiplicity.

Note

A relational database is more flexible than a network
programming language, in that it does not need a navigation
direction; data can be viewed and retrieved in any possible
way.

These are normal set mappings in both mapping documents.
Notice that the column names in key and many-to-many
swap in both mapping documents. The most important addition here is the
inverse="true" attribute in the set element of the
Event's collection mapping.

What this means is that Hibernate should take the other side, the Person class,
when it needs to find out information about the link between the two. This will be a lot easier to
understand once you see how the bi-directional link between our two entities is created.

1.2.6. Working bi-directional links

First, keep in mind that Hibernate does not affect normal Java semantics. How did we create a
link between a Person and an Event in the unidirectional
example? You add an instance of Event to the collection of event references,
of an instance of Person. If you want to make this link
bi-directional, you have to do the same on the other side by adding a Person
reference to the collection in an Event. This process of "setting the link on both sides"
is absolutely necessary with bi-directional links.

Many developers program defensively and create link management methods to
correctly set both sides (for example, in Person):

The get and set methods for the collection are now protected. This allows classes in the
same package and subclasses to still access the methods, but prevents everybody else from altering
the collections directly. Repeat the steps for the collection
on the other side.

What about the inverse mapping attribute? For you, and for Java, a bi-directional
link is simply a matter of setting the references on both sides correctly. Hibernate, however, does not
have enough information to correctly arrange SQL INSERT and UPDATE
statements (to avoid constraint violations). Making one side of the association inverse tells Hibernate to consider it a mirror of the other side. That is all that is necessary
for Hibernate to resolve any issues that arise when transforming a directional navigation model to
a SQL database schema. The rules are straightforward: all bi-directional associations
need one side as inverse. In a one-to-many association it has to be the many-side,
and in many-to-many association you can select either side.

1.3. Part 3 - The EventManager web application

A Hibernate web application uses Session and Transaction
almost like a standalone application. However, some common patterns are useful. You can now write
an EventManagerServlet. This servlet can list all events stored in the
database, and it provides an HTML form to enter new events.

1.3.1. Writing the basic servlet

First we need create our basic processing servlet. Since our
servlet only handles HTTP GET requests, we
will only implement the doGet() method:

Save this servlet as
src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java

The pattern applied here is called session-per-request.
When a request hits the servlet, a new Hibernate Session is
opened through the first call to getCurrentSession() on the
SessionFactory. A database transaction is then started. All
data access occurs inside a transaction irrespective of whether the data is read or written.
Do not use the auto-commit mode in applications.

Do not use a new Hibernate Session for
every database operation. Use one Hibernate Session that is
scoped to the whole request. Use getCurrentSession(), so that
it is automatically bound to the current Java thread.

Next, the possible actions of the request are processed and the response HTML
is rendered. We will get to that part soon.

Finally, the unit of work ends when processing and rendering are complete. If any
problems occurred during processing or rendering, an exception will be thrown
and the database transaction rolled back. This completes the
session-per-request pattern. Instead of the transaction
demarcation code in every servlet, you could also write a servlet filter.
See the Hibernate website and Wiki for more information about this pattern
called Open Session in View. You will need it as soon
as you consider rendering your view in JSP, not in a servlet.

1.3.2. Processing and rendering

Now you can implement the processing of the request and the rendering of the page.

This coding style, with a mix of Java and HTML, would not scale
in a more complex application;keep in mind that we are only illustrating
basic Hibernate concepts in this tutorial. The code prints an HTML
header and a footer. Inside this page, an HTML form for event entry and
a list of all events in the database are printed. The first method is
trivial and only outputs HTML:

The servlet is now complete. A request to the servlet will be processed
in a single Session and Transaction. As
earlier in the standalone application, Hibernate can automatically bind these
objects to the current thread of execution. This gives you the freedom to layer
your code and access the SessionFactory in any way you like.
Usually you would use a more sophisticated design and move the data access code
into data access objects (the DAO pattern). See the Hibernate Wiki for more
examples.

1.3.3. Deploying and testing

To deploy this application for testing we must create a
Web ARchive (WAR). First we must define the WAR descriptor
as src/main/webapp/WEB-INF/web.xml

Note

If you do not have Tomcat installed, download it from
http://tomcat.apache.org/
and follow the
installation instructions. Our application requires
no changes to the standard Tomcat configuration.

Once deployed and Tomcat is running, access the application at
http://localhost:8080/hibernate-tutorial/eventmanager. Make
sure you watch the Tomcat log to see Hibernate initialize when the first
request hits your servlet (the static initializer in HibernateUtil
is called) and to get the detailed output if any exceptions occurs.

1.4. Summary

This tutorial covered the basics of writing a simple standalone Hibernate application
and a small web application. More tutorials are available from the Hibernate
website.

Chapter 2. Architecture

2.1. Overview

The diagram below provides a high-level view of the Hibernate architecture:

Unfortunately we cannot provide a detailed view of all possible runtime architectures. Hibernate is
sufficiently flexible to be used in a number of ways in many, many architectures. We will, however,
illustrate 2 specifically since they are extremes.

2.1.1. Minimal architecture

The "minimal" architecture has the application manage its own JDBC connections and provide those
connections to Hibernate; additionally the application manages transactions for itself. This approach
uses a minimal subset of Hibernate APIs.

2.1.2. Comprehensive architecture

The "comprehensive" architecture abstracts the application away from the underlying JDBC/JTA APIs and
allows Hibernate to manage the details.

2.1.3. Basic APIs

Here are quick discussions about some of the API objects depicted in the preceding diagrams (you will
see them again in more detail in later chapters).

SessionFactory (org.hibernate.SessionFactory)

A thread-safe, immutable cache of compiled mappings for a single database.
A factory for org.hibernate.Session instances. A client
of org.hibernate.connection.ConnectionProvider. Optionally
maintains a second level cache of data that is reusable between
transactions at a process or cluster level.

Session (org.hibernate.Session)

A single-threaded, short-lived object representing a conversation between
the application and the persistent store. Wraps a JDBC
java.sql.Connection. Factory for
org.hibernate.Transaction. Maintains a
first level cache of persistent the application's persistent objects
and collections; this cache is used when navigating the object graph or looking up
objects by identifier.

Persistent objects and collections

Short-lived, single threaded objects containing persistent state and business
function. These can be ordinary JavaBeans/POJOs. They are associated with exactly one
org.hibernate.Session. Once the
org.hibernate.Session is closed, they will be detached
and free to use in any application layer (for example, directly as data transfer objects
to and from presentation). Chapter 11, Working with objects discusses transient,
persistent and detached object states.

Transient and detached objects and collections

Instances of persistent classes that are not currently associated with a
org.hibernate.Session. They may have been instantiated by
the application and not yet persisted, or they may have been instantiated by a
closed org.hibernate.Session.
Chapter 11, Working with objects discusses transient, persistent and detached object states.

Transaction (org.hibernate.Transaction)

(Optional) A single-threaded, short-lived object used by the application to
specify atomic units of work. It abstracts the application from the underlying JDBC,
JTA or CORBA transaction. A org.hibernate.Session might span several
org.hibernate.Transactions in some cases. However,
transaction demarcation, either using the underlying API or
org.hibernate.Transaction, is never optional.

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(Optional) A factory for, and pool of, JDBC connections. It abstracts the application from
underlying javax.sql.DataSource or
java.sql.DriverManager. It is not exposed to application,
but it can be extended and/or implemented by the developer.

TransactionFactory (org.hibernate.TransactionFactory)

(Optional) A factory for org.hibernate.Transaction
instances. It is not exposed to the application, but it can be extended and/or
implemented by the developer.

Extension Interfaces

Hibernate offers a range of optional extension interfaces you can implement to customize
the behavior of your persistence layer. See the API documentation for details.

2.2. Contextual sessions

Most applications using Hibernate need some form of "contextual" session, where a given
session is in effect throughout the scope of a given context. However, across applications
the definition of what constitutes a context is typically different; different contexts
define different scopes to the notion of current. Applications using Hibernate prior
to version 3.0 tended to utilize either home-grown ThreadLocal-based
contextual sessions, helper classes such as HibernateUtil, or utilized
third-party frameworks, such as Spring or Pico, which provided proxy/interception-based contextual sessions.

Starting with version 3.0.1, Hibernate added the SessionFactory.getCurrentSession()
method. Initially, this assumed usage of JTA transactions, where the
JTA transaction defined both the scope and context of a current session.
Given the maturity of the numerous stand-alone
JTA TransactionManager implementations, most, if not all,
applications should be using JTA transaction management, whether or not
they are deployed into a J2EE container. Based on that, the
JTA-based contextual sessions are all you need to use.

However, as of version 3.1, the processing behind
SessionFactory.getCurrentSession() is now pluggable. To that
end, a new extension interface, org.hibernate.context.spi.CurrentSessionContext,
and a new configuration parameter, hibernate.current_session_context_class,
have been added to allow pluggability of the scope and context of defining current sessions.

See the Javadocs for the org.hibernate.context.spi.CurrentSessionContext
interface for a detailed discussion of its contract. It defines a single method,
currentSession(), by which the implementation is responsible for
tracking the current contextual session. Out-of-the-box, Hibernate comes with three
implementations of this interface:

org.hibernate.context.internal.JTASessionContext: current sessions
are tracked and scoped by a JTA transaction. The processing
here is exactly the same as in the older JTA-only approach. See the Javadocs
for details.

org.hibernate.context.internal.ThreadLocalSessionContext:current
sessions are tracked by thread of execution. See the Javadocs for details.

org.hibernate.context.internal.ManagedSessionContext: current
sessions are tracked by thread of execution. However, you are responsible to
bind and unbind a Session instance with static methods
on this class: it does not open, flush, or close a Session.

The first two implementations provide a "one session - one database transaction" programming
model. This is also known and used as session-per-request. The beginning
and end of a Hibernate session is defined by the duration of a database transaction.
If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to
use the Hibernate Transaction API to hide the underlying transaction system
from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you
execute in an EJB container that supports CMT, transaction boundaries are defined declaratively
and you do not need any transaction or session demarcation operations in your code.
Refer to Chapter 13, Transactions and Concurrency for more information and code examples.

The hibernate.current_session_context_class configuration parameter
defines which org.hibernate.context.spi.CurrentSessionContext implementation
should be used. For backwards compatibility, if this configuration parameter is not set
but a org.hibernate.engine.transaction.jta.platform.spi.JtaPlatform is configured,
Hibernate will use the org.hibernate.context.internal.JTASessionContext.
Typically, the value of this parameter would just name the implementation class to
use. For the three out-of-the-box implementations, however, there are three corresponding
short names: "jta", "thread", and "managed".

Hibernate is designed to operate in many different environments and,
as such, there is a broad range of configuration parameters. Fortunately,
most have sensible default values and Hibernate is distributed with an
example hibernate.properties file in
etc/ that displays the various options. Simply put the
example file in your classpath and customize it to suit your needs.

3.1. Programmatic configuration

An instance of
org.hibernate.cfg.Configuration represents an
entire set of mappings of an application's Java types to an SQL database.
The org.hibernate.cfg.Configuration is used to
build an immutable
org.hibernate.SessionFactory. The mappings
are compiled from various XML mapping files.

You can obtain a
org.hibernate.cfg.Configuration instance by
instantiating it directly and specifying XML mapping documents. If the
mapping files are in the classpath, use addResource().
For example:

This is not the only way to pass configuration properties to
Hibernate. Some alternative options include:

Pass an instance of java.util.Properties
to Configuration.setProperties().

Place a file named hibernate.properties in
a root directory of the classpath.

Set System properties using java
-Dproperty=value.

Include <property> elements in
hibernate.cfg.xml (this is discussed later).

If you want to get started
quicklyhibernate.properties is the easiest
approach.

The org.hibernate.cfg.Configuration is
intended as a startup-time object that will be discarded once a
SessionFactory is created.

3.2. Obtaining a SessionFactory

When all mappings have been parsed by the
org.hibernate.cfg.Configuration, the application
must obtain a factory for
org.hibernate.Session instances. This
factory is intended to be shared by all application threads:

SessionFactory sessions = cfg.buildSessionFactory();

Hibernate does allow your application to instantiate more than one
org.hibernate.SessionFactory. This is
useful if you are using more than one database.

3.3. JDBC connections

It is advisable to have the
org.hibernate.SessionFactory create and
pool JDBC connections for you. If you take this approach, opening a
org.hibernate.Session is as simple
as:

Session session = sessions.openSession(); // open a new Session

Once you start a task that requires access to the database, a JDBC
connection will be obtained from the pool.

Before you can do this, you first need to pass some JDBC connection
properties to Hibernate. All Hibernate property names and semantics are
defined on the class org.hibernate.cfg.Environment.
The most important settings for JDBC connection configuration are outlined
below.

Hibernate will obtain and pool connections using
java.sql.DriverManager if you set the following
properties:

Table 3.1. Hibernate JDBC Properties

Property name

Purpose

hibernate.connection.driver_class

JDBC driver class

hibernate.connection.url

JDBC URL

hibernate.connection.username

database user

hibernate.connection.password

database user password

hibernate.connection.pool_size

maximum number of pooled
connections

Hibernate's own connection pooling algorithm is, however, quite
rudimentary. It is intended to help you get started and is not
intended for use in a production system, or even for
performance testing. You should use a third party pool for best
performance and stability. Just replace the
hibernate.connection.pool_size property with
connection pool specific settings. This will turn off Hibernate's internal
pool. For example, you might like to use c3p0.

C3P0 is an open source JDBC connection pool distributed along with
Hibernate in the lib directory. Hibernate will use
its org.hibernate.connection.C3P0ConnectionProvider
for connection pooling if you set hibernate.c3p0.*
properties. If you would like to use Proxool, refer to the packaged
hibernate.properties and the Hibernate web site for
more information.

For use inside an application server, you should almost always
configure Hibernate to obtain connections from an application server
javax.sql.Datasource registered in JNDI.
You will need to set at least one of the following properties:

Table 3.2. Hibernate Datasource Properties

Property name

Purpose

hibernate.connection.datasource

datasource JNDI name

hibernate.jndi.url

URL of the JNDI provider
(optional)

hibernate.jndi.class

class of the JNDI
InitialContextFactory
(optional)

hibernate.connection.username

database user (optional)

hibernate.connection.password

database user password
(optional)

Here is an example hibernate.properties file
for an application server provided JNDI datasource:

JDBC connections obtained from a JNDI datasource will automatically
participate in the container-managed transactions of the application
server.

Arbitrary connection properties can be given by prepending
"hibernate.connection" to the connection property name.
For example, you can specify a charSet connection
property using hibernate.connection.charSet.

You can define your own plugin strategy for obtaining JDBC
connections by implementing the interface
org.hibernate.connection.ConnectionProvider,
and specifying your custom implementation via the
hibernate.connection.provider_class property.

3.4. Optional configuration properties

There are a number of other properties that control the behavior of
Hibernate at runtime. All are optional and have reasonable default
values.

Warning

Some of these properties are "system-level"
only. System-level properties can be set only via
java -Dproperty=value or
hibernate.properties. They
cannot be set by the other techniques described
above.

Table 3.3. Hibernate Configuration Properties

Property name

Purpose

hibernate.dialect

The classname of a Hibernate
org.hibernate.dialect.Dialect which allows
Hibernate to generate SQL optimized for a particular relational
database.

e.g.full.classname.of.Dialect

In
most cases Hibernate will actually be able to choose the correct
org.hibernate.dialect.Dialect
implementation based on the JDBC metadata
returned by the JDBC driver.

hibernate.show_sql

Write all SQL statements to console. This is an alternative
to setting the log category org.hibernate.SQL
to debug.

e.g.true |
false

hibernate.format_sql

Pretty print the SQL in the log and console.

e.g.true |
false

hibernate.default_schema

Qualify unqualified table names with the given
schema/tablespace in generated SQL.

e.g.SCHEMA_NAME

hibernate.default_catalog

Qualifies unqualified table names with the given catalog in
generated SQL.

e.g.CATALOG_NAME

hibernate.session_factory_name

The
org.hibernate.SessionFactory will
be automatically bound to this name in JNDI after it has been
created.

Sets a default mode for entity representation for all
sessions opened from this SessionFactory,
defaults to pojo.

e.g.dynamic-map |
pojo

hibernate.order_updates

Forces Hibernate to order SQL updates by the primary key
value of the items being updated. This will result in fewer
transaction deadlocks in highly concurrent systems.

e.g.true |
false

hibernate.generate_statistics

If enabled, Hibernate will collect statistics useful for
performance tuning.

e.g.true | false

hibernate.use_identifier_rollback

If enabled, generated identifier properties will be reset
to default values when objects are deleted.

e.g.true |
false

hibernate.use_sql_comments

If turned on, Hibernate will generate comments inside the
SQL, for easier debugging, defaults to false.

e.g.true | false

hibernate.id.new_generator_mappings

Setting is relevant when using
@GeneratedValue. It indicates whether or
not the new IdentifierGenerator
implementations are used for
javax.persistence.GenerationType.AUTO,
javax.persistence.GenerationType.TABLE and
javax.persistence.GenerationType.SEQUENCE.
Default to false to keep backward
compatibility.

e.g.true | false

Note

We recommend all new projects which make use of to use
@GeneratedValue to also set
hibernate.id.new_generator_mappings=true as the new
generators are more efficient and closer to the JPA 2 specification
semantic. However they are not backward compatible with existing
databases (if a sequence or a table is used for id generation).

Set this property to true if your JDBC
driver returns correct row counts from
executeBatch(). It is usually safe to turn this
option on. Hibernate will then use batched DML for automatically
versioned data. Defaults to false.

e.g.true |
false

hibernate.jdbc.factory_class

Select a custom
org.hibernate.jdbc.Batcher. Most
applications will not need this configuration property.

e.g.classname.of.BatcherFactory

hibernate.jdbc.use_scrollable_resultset

Enables use of JDBC2 scrollable resultsets by Hibernate.
This property is only necessary when using user-supplied JDBC
connections. Hibernate uses connection metadata otherwise.

Enables use of JDBC3
PreparedStatement.getGeneratedKeys() to
retrieve natively generated keys after insert. Requires JDBC3+
driver and JRE1.4+, set to false if your driver has problems with
the Hibernate identifier generators. By default, it tries to
determine the driver capabilities using connection metadata.

e.g.true|false

hibernate.connection.provider_class

The classname of a custom
org.hibernate.connection.ConnectionProvider
which provides JDBC connections to Hibernate.

e.g.classname.of.ConnectionProvider

hibernate.connection.isolation

Sets the JDBC transaction isolation level. Check
java.sql.Connection for meaningful
values, but note that most databases do not support all isolation
levels and some define additional, non-standard isolations.

e.g.1, 2, 4,
8

hibernate.connection.autocommit

Enables autocommit for JDBC pooled connections (it is not
recommended).

e.g.true | false

hibernate.connection.release_mode

Specifies when Hibernate should release JDBC connections.
By default, a JDBC connection is held until the session is
explicitly closed or disconnected. For an application server JTA
datasource, use after_statement to aggressively
release connections after every JDBC call. For a non-JTA
connection, it often makes sense to release the connection at the
end of each transaction, by using
after_transaction. auto will
choose after_statement for the JTA and CMT
transaction strategies and after_transaction
for the JDBC transaction strategy.

e.g.auto (default) |
on_close | after_transaction
| after_statement

This setting
only affects Sessions returned from
SessionFactory.openSession. For
Sessions obtained through
SessionFactory.getCurrentSession, the
CurrentSessionContext implementation configured
for use controls the connection release mode for those
Sessions. See Section 2.2, “Contextual sessions”

Optimizes second-level cache operation to minimize writes,
at the cost of more frequent reads. This setting is most useful
for clustered caches and, in Hibernate, is enabled by default for
clustered cache implementations.

e.g.true|false

hibernate.cache.use_query_cache

Enables the query cache. Individual queries still have to
be set cachable.

e.g.true|false

hibernate.cache.use_second_level_cache

Can be used to completely disable the second level cache,
which is enabled by default for classes which specify a
<cache> mapping.

e.g.true|false

hibernate.cache.query_cache_factory

The classname of a custom QueryCache
interface, defaults to the built-in
StandardQueryCache.

e.g.classname.of.QueryCache

hibernate.cache.region_prefix

A prefix to use for second-level cache region names.

e.g.prefix

hibernate.cache.use_structured_entries

Forces Hibernate to store data in the second-level cache in
a more human-friendly format.

e.g.true|false

hibernate.cache.auto_evict_collection_cache

Enables the automatic eviction of a bi-directional association's collection cache when an element
in the ManyToOne collection is added/updated/removed without properly managing the change on the OneToMany
side.

e.g.true|false (default: false)

hibernate.cache.default_cache_concurrency_strategy

Setting used to give the name of the default
org.hibernate.annotations.CacheConcurrencyStrategy
to use when either @Cacheable or
@Cache is used.
@Cache(strategy="..") is used to override this
default.

Table 3.6. Hibernate Transaction Properties

Property name

Purpose

hibernate.transaction.factory_class

The classname of a TransactionFactory to
use with Hibernate Transaction API (defaults to
JDBCTransactionFactory).

e.g.classname.of.TransactionFactory

jta.UserTransaction

A JNDI name used by
JTATransactionFactory to obtain the JTA
UserTransaction from the application server.

e.g.jndi/composite/name

hibernate.transaction.manager_lookup_class

The classname of a
TransactionManagerLookup. It is required when
JVM-level caching is enabled or when using hilo generator in a JTA
environment.

e.g.classname.of.TransactionManagerLookup

hibernate.transaction.flush_before_completion

If enabled, the session will be automatically flushed
during the before completion phase of the transaction. Built-in
and automatic session context management is preferred, see Section 2.2, “Contextual sessions”.

e.g.true |
false

hibernate.transaction.auto_close_session

If enabled, the session will be automatically closed during
the after completion phase of the transaction. Built-in and
automatic session context management is preferred, see Section 2.2, “Contextual sessions”.

e.g.org.hibernate.hql.internal.ast.ASTQueryTranslatorFactory
or
org.hibernate.hql.internal.classic.ClassicQueryTranslatorFactory

hibernate.query.substitutions

Is used to map from tokens in Hibernate queries to SQL
tokens (tokens might be function or literal names, for example).

e.g.hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.auto

Automatically validates or exports schema DDL to the
database when the SessionFactory is created.
With create-drop, the database schema will be
dropped when the SessionFactory is closed
explicitly.

e.g.validate | update |
create | create-drop

hibernate.hbm2ddl.import_files

Comma-separated names of the optional files
containing SQL DML statements executed during the
SessionFactory creation. This is useful for
testing or demoing: by adding INSERT statements for example you
can populate your database with a minimal set of data when it is
deployed.

File order matters, the statements of a give
file are executed before the statements of the following files.
These statements are only executed if the schema is created ie if
hibernate.hbm2ddl.auto is set to
create or
create-drop.

e.g./humans.sql,/dogs.sql

hibernate.hbm2ddl.import_files_sql_extractor

The classname of a custom ImportSqlCommandExtractor
(defaults to the built-in SingleLineSqlCommandExtractor).
This is useful for implementing dedicated parser that extracts
single SQL statements from each import file. Hibernate provides
also MultipleLinesSqlCommandExtractor which
supports instructions/comments and quoted strings spread over
multiple lines (mandatory semicolon at the end of each statement).

e.g.classname.of.ImportSqlCommandExtractor

hibernate.bytecode.use_reflection_optimizer

Enables the use of bytecode manipulation instead of
runtime reflection. This is a System-level property and cannot be
set in hibernate.cfg.xml. Reflection can
sometimes be useful when troubleshooting. Hibernate always
requires javassist even if you turn off the
optimizer.

e.g.true | false

hibernate.bytecode.provider

At the moment, javassist is the only supported bytecode provider.

e.g.javassist

3.4.1. SQL Dialects

Always set the hibernate.dialect property to
the correct org.hibernate.dialect.Dialect subclass
for your database. If you specify a dialect, Hibernate will use sensible
defaults for some of the other properties listed above. This means that
you will not have to specify them manually.

Table 3.8. Hibernate SQL Dialects
(hibernate.dialect)

RDBMS

Dialect

CUBRID 8.3 and later

org.hibernate.dialect.CUBRIDDialect

DB2

org.hibernate.dialect.DB2Dialect

DB2 AS/400

org.hibernate.dialect.DB2400Dialect

DB2 OS390

org.hibernate.dialect.DB2390Dialect

Firebird

org.hibernate.dialect.FirebirdDialect

FrontBase

org.hibernate.dialect.FrontbaseDialect

H2

org.hibernate.dialect.H2Dialect

HyperSQL (HSQL)

org.hibernate.dialect.HSQLDialect

Informix

org.hibernate.dialect.InformixDialect

Ingres

org.hibernate.dialect.IngresDialect

Ingres 9

org.hibernate.dialect.Ingres9Dialect

Ingres 10

org.hibernate.dialect.Ingres10Dialect

Interbase

org.hibernate.dialect.InterbaseDialect

InterSystems Cache 2007.1

org.hibernate.dialect.Cache71Dialect

JDataStore

org.hibernate.dialect.JDataStoreDialect

Mckoi SQL

org.hibernate.dialect.MckoiDialect

Microsoft SQL Server 2000

org.hibernate.dialect.SQLServerDialect

Microsoft SQL Server 2005

org.hibernate.dialect.SQLServer2005Dialect

Microsoft SQL Server 2008

org.hibernate.dialect.SQLServer2008Dialect

Microsoft SQL Server 2012

org.hibernate.dialect.SQLServer2012Dialect

Mimer SQL

org.hibernate.dialect.MimerSQLDialect

MySQL

org.hibernate.dialect.MySQLDialect

MySQL with InnoDB

org.hibernate.dialect.MySQLInnoDBDialect

MySQL with MyISAM

org.hibernate.dialect.MySQLMyISAMDialect

MySQL5

org.hibernate.dialect.MySQL5Dialect

MySQL5 with InnoDB

org.hibernate.dialect.MySQL5InnoDBDialect

Oracle 8i

org.hibernate.dialect.Oracle8iDialect

Oracle 9i

org.hibernate.dialect.Oracle9iDialect

Oracle 10g and later

org.hibernate.dialect.Oracle10gDialect

Oracle TimesTen

org.hibernate.dialect.TimesTenDialect

Pointbase

org.hibernate.dialect.PointbaseDialect

PostgreSQL 8.1

org.hibernate.dialect.PostgreSQL81Dialect

PostgreSQL 8.2

org.hibernate.dialect.PostgreSQL82Dialect

PostgreSQL 9 and later

org.hibernate.dialect.PostgreSQL9Dialect

Progress

org.hibernate.dialect.ProgressDialect

SAP DB

org.hibernate.dialect.SAPDBDialect

SAP HANA (column store)

org.hibernate.dialect.HANAColumnStoreDialect

SAP HANA (row store)

org.hibernate.dialect.HANARowStoreDialect

Sybase

org.hibernate.dialect.SybaseDialect

Sybase 11

org.hibernate.dialect.Sybase11Dialect

Sybase ASE 15.5

org.hibernate.dialect.SybaseASE15Dialect

Sybase ASE 15.7

org.hibernate.dialect.SybaseASE157Dialect

Sybase Anywhere

org.hibernate.dialect.SybaseAnywhereDialect

Teradata

org.hibernate.dialect.TeradataDialect

Unisys OS 2200 RDMS

org.hibernate.dialect.RDMSOS2200Dialect

3.4.2. Outer Join Fetching

If your database supports ANSI, Oracle or Sybase style outer
joins, outer join fetching will often increase
performance by limiting the number of round trips to and from the
database. This is, however, at the cost of possibly more work performed
by the database itself. Outer join fetching allows a whole graph of
objects connected by many-to-one, one-to-many, many-to-many and
one-to-one associations to be retrieved in a single SQL
SELECT.

Outer join fetching can be disabled globally
by setting the property hibernate.max_fetch_depth to
0. A setting of 1 or higher
enables outer join fetching for one-to-one and many-to-one associations
that have been mapped with fetch="join".

3.4.3. Binary Streams

Oracle limits the size of byte arrays that can
be passed to and/or from its JDBC driver. If you wish to use large
instances of binary or
serializable type, you should enable
hibernate.jdbc.use_streams_for_binary. This
is a system-level setting only.

3.4.4. Second-level and query cache

The properties prefixed by hibernate.cache
allow you to use a process or cluster scoped second-level cache system
with Hibernate. See the Section 20.2, “The Second Level Cache” for more
information.

3.4.5. Query Language Substitution

You can define new Hibernate query tokens using
hibernate.query.substitutions. For example:

hibernate.query.substitutions true=1, false=0

This would cause the tokens true and
false to be translated to integer literals in the
generated SQL.

hibernate.query.substitutions toLowercase=LOWER

This would allow you to rename the SQL LOWER
function.

3.4.6. Hibernate statistics

If you enable hibernate.generate_statistics,
Hibernate exposes a number of metrics that are useful when tuning a
running system via SessionFactory.getStatistics().
Hibernate can even be configured to expose these statistics via JMX.
Read the Javadoc of the interfaces in
org.hibernate.stats for more information.

3.5. Logging

Important

Completely out of date. Hibernate uses JBoss Logging starting in 4.0.
This will get documented as we migrate this content to the Developer Guide.

Hibernate utilizes Simple Logging
Facade for Java (SLF4J) in order to log various system events.
SLF4J can direct your logging output to several logging frameworks (NOP,
Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) depending on
your chosen binding. In order to setup logging you will need
slf4j-api.jar in your classpath together with the jar
file for your preferred binding - slf4j-log4j12.jar
in the case of Log4J. See the SLF4J
documentation
for more
detail. To use Log4j you will also need to place a
log4j.properties file in your classpath. An example
properties file is distributed with Hibernate in the
src/ directory.

It is recommended that you familiarize yourself with Hibernate's log
messages. A lot of work has been put into making the Hibernate log as
detailed as possible, without making it unreadable. It is an essential
troubleshooting device. The most interesting log categories are the
following:

Table 3.9. Hibernate Log Categories

Category

Function

org.hibernate.SQL

Log all SQL DML statements as they are executed

org.hibernate.type

Log all JDBC parameters

org.hibernate.tool.hbm2ddl

Log all SQL DDL statements as they are executed

org.hibernate.pretty

Log the state of all entities (max 20 entities) associated
with the session at flush time

org.hibernate.cache

Log all second-level cache activity

org.hibernate.transaction

Log transaction related activity

org.hibernate.jdbc

Log all JDBC resource acquisition

org.hibernate.hql.internal.ast.AST

Log HQL and SQL ASTs during query parsing

org.hibernate.secure

Log all JAAS authorization requests

org.hibernate

Log everything. This is a lot of information but it is
useful for troubleshooting

When developing applications with Hibernate, you should almost
always work with debug enabled for the category
org.hibernate.SQL, or, alternatively, the property
hibernate.show_sql enabled.

3.6. Implementing a NamingStrategy

The interface org.hibernate.cfg.NamingStrategy
allows you to specify a "naming standard" for database objects and schema
elements.

You can provide rules for automatically generating database
identifiers from Java identifiers or for processing "logical" column and
table names given in the mapping file into "physical" table and column
names. This feature helps reduce the verbosity of the mapping document,
eliminating repetitive noise (TBL_ prefixes, for
example). The default strategy used by Hibernate is quite minimal.

You can specify a different strategy by calling
Configuration.setNamingStrategy() before adding
mappings:

The persister class provider methods, when returning a non null
persister class, override the default Hibernate persisters. The entity
name or the collection role are passed to the methods. It is a nice way to
centralize the overriding logic of the persisters instead of spreading
them on each entity or collection mapping.

3.8. XML configuration file

An alternative approach to configuration is to specify a full
configuration in a file named hibernate.cfg.xml. This
file can be used as a replacement for the
hibernate.properties file or, if both are present, to
override properties.

The XML configuration file is by default expected to be in the root
of your CLASSPATH. Here is an example:

The advantage of this approach is the externalization of the mapping
file names to configuration. The hibernate.cfg.xml is
also more convenient once you have to tune the Hibernate cache. It is your
choice to use either hibernate.properties or
hibernate.cfg.xml. Both are equivalent, except for the
above mentioned benefits of using the XML syntax.

3.9. Java EE Application Server integration

Hibernate has the following integration points for J2EE
infrastructure:

Container-managed datasources: Hibernate
can use JDBC connections managed by the container and provided through
JNDI. Usually, a JTA compatible TransactionManager
and a ResourceManager take care of transaction
management (CMT), especially distributed transaction handling across
several datasources. You can also demarcate transaction boundaries
programmatically (BMT), or you might want to use the optional
Hibernate Transaction API for this to keep your
code portable.

Automatic JNDI binding: Hibernate can bind
its SessionFactory to JNDI after startup.

JTA Session binding: the Hibernate
Session can be automatically bound to the scope of
JTA transactions. Simply lookup the SessionFactory
from JNDI and get the current Session. Let
Hibernate manage flushing and closing the Session
when your JTA transaction completes. Transaction demarcation is either
declarative (CMT) or programmatic (BMT/UserTransaction).

JMX deployment: if you have a JMX capable
application server (e.g. JBoss AS), you can choose to deploy Hibernate
as a managed MBean. This saves you the one line startup code to build
your SessionFactory from a
Configuration. The container will startup your
HibernateService and also take care of service
dependencies (datasource has to be available before Hibernate starts,
etc).

Depending on your environment, you might have to set the
configuration option
hibernate.connection.aggressive_release to true if your
application server shows "connection containment" exceptions.

3.9.1. Transaction strategy configuration

The Hibernate Session API is independent of any
transaction demarcation system in your architecture. If you let
Hibernate use JDBC directly through a connection pool, you can begin and
end your transactions by calling the JDBC API. If you run in a J2EE
application server, you might want to use bean-managed transactions and
call the JTA API and UserTransaction when
needed.

To keep your code portable between these two (and other)
environments we recommend the optional Hibernate
Transaction API, which wraps and hides the underlying
system. You have to specify a factory class for
Transaction instances by setting the Hibernate
configuration property
hibernate.transaction.factory_class.

There are three standard, or built-in, choices:

org.hibernate.transaction.JDBCTransactionFactory

delegates to database (JDBC) transactions (default)

org.hibernate.transaction.JTATransactionFactory

delegates to container-managed transactions if an existing
transaction is underway in this context (for example, EJB session
bean method). Otherwise, a new transaction is started and
bean-managed transactions are used.

org.hibernate.transaction.CMTTransactionFactory

delegates to container-managed JTA transactions

You can also define your own transaction strategies (for a CORBA
transaction service, for example).

Some features in Hibernate (i.e., the second level cache,
Contextual Sessions with JTA, etc.) require access to the JTA
TransactionManager in a managed environment. In an
application server, since J2EE does not standardize a single mechanism,
you have to specify how Hibernate should obtain a reference to the
TransactionManager:

Table 3.10. JTA TransactionManagers

Transaction Factory

Application Server

org.hibernate.transaction.JBossTransactionManagerLookup

JBoss AS

org.hibernate.transaction.WeblogicTransactionManagerLookup

Weblogic

org.hibernate.transaction.WebSphereTransactionManagerLookup

WebSphere

org.hibernate.transaction.WebSphereExtendedJTATransactionLookup

WebSphere 6

org.hibernate.transaction.OrionTransactionManagerLookup

Orion

org.hibernate.transaction.ResinTransactionManagerLookup

Resin

org.hibernate.transaction.JOTMTransactionManagerLookup

JOTM

org.hibernate.transaction.JOnASTransactionManagerLookup

JOnAS

org.hibernate.transaction.JRun4TransactionManagerLookup

JRun4

org.hibernate.transaction.BESTransactionManagerLookup

Borland ES

org.hibernate.transaction.JBossTSStandaloneTransactionManagerLookup

JBoss TS used standalone (ie. outside
JBoss AS and a JNDI environment generally). Known to work for
org.jboss.jbossts:jbossjta:4.11.0.Final

3.9.2. JNDI-bound SessionFactory

A JNDI-bound Hibernate SessionFactory can
simplify the lookup function of the factory and create new
Sessions. This is not, however, related to a JNDI
bound Datasource; both simply use the same
registry.

If you wish to have the SessionFactory bound to
a JNDI namespace, specify a name (e.g.
java:hibernate/SessionFactory) using the property
hibernate.session_factory_name. If this property is
omitted, the SessionFactory will not be bound to
JNDI. This is especially useful in environments with a read-only JNDI
default implementation (in Tomcat, for example).

When binding the SessionFactory to JNDI,
Hibernate will use the values of hibernate.jndi.url,
hibernate.jndi.class to instantiate an initial
context. If they are not specified, the default
InitialContext will be used.

Hibernate will automatically place the
SessionFactory in JNDI after you call
cfg.buildSessionFactory(). This means you will have
this call in some startup code, or utility class in your application,
unless you use JMX deployment with the
HibernateService (this is discussed later in greater
detail).

If you use a JNDI SessionFactory, an EJB or any
other class, you can obtain the SessionFactory using
a JNDI lookup.

It is recommended that you bind the
SessionFactory to JNDI in a managed environment and
use a static singleton otherwise. To shield your
application code from these details, we also recommend to hide the
actual lookup code for a SessionFactory in a helper
class, such as HibernateUtil.getSessionFactory().
Note that such a class is also a convenient way to startup Hibernate—see
chapter 1.

3.9.3. Current Session context management with JTA

The easiest way to handle Sessions and
transactions is Hibernate's automatic "current"
Session management. For a discussion of contextual
sessions see Section 2.2, “Contextual sessions”. Using the
"jta" session context, if there is no Hibernate
Session associated with the current JTA transaction,
one will be started and associated with that JTA transaction the first
time you call sessionFactory.getCurrentSession(). The
Sessions retrieved via
getCurrentSession() in the "jta"
context are set to automatically flush before the transaction completes,
close after the transaction completes, and aggressively release JDBC
connections after each statement. This allows the
Sessions to be managed by the life cycle of the JTA
transaction to which it is associated, keeping user code clean of such
management concerns. Your code can either use JTA programmatically
through UserTransaction, or (recommended for portable
code) use the Hibernate Transaction API to set
transaction boundaries. If you run in an EJB container, declarative
transaction demarcation with CMT is preferred.

Persistent classes are classes in an application that implement the entities of the business problem
(e.g. Customer and Order in an E-commerce application). The term "persistent" here means that the classes
are able to be persisted, not that they are in the persistent state (see Section 11.1, “Hibernate object states”
for discussion).

Hibernate works best if these classes follow some simple rules, also known as the Plain Old Java Object (POJO)
programming model. However, none of these rules are hard requirements. Indeed, Hibernate assumes very little
about the nature of your persistent objects. You can express a domain model in other ways (using trees of
java.util.Map instances, for example).

The four main rules of persistent classes are explored in more detail in the following sections.

4.1.1. Implement a no-argument constructor

Cat has a no-argument constructor. All persistent classes must have a default
constructor (which can be non-public) so that Hibernate can instantiate them using
java.lang.reflect.Constructor.newInstance(). It is recommended
that this constructor be defined with at least package visibility in order for
runtime proxy generation to work properly.

4.1.2. Provide an identifier property

Note

Historically this was considered option. While still not (yet) enforced, this should be considered
a deprecated feature as it will be completely required to provide a identifier property in an
upcoming release.

Cat has a property named id. This property maps to the
primary key column(s) of the underlying database table. The type of the identifier property can
be any "basic" type (see ???). See Section 9.4, “Components as composite identifiers”
for information on mapping composite (multi-column) identifiers.

Note

Identifiers do not necessarily need to identify column(s) in the database physically defined
as a primary key. They should just identify columns that can be used to uniquely identify rows
in the underlying table.

We recommend that you declare consistently-named identifier properties on persistent classes and that you use
a nullable (i.e., non-primitive) type.

4.1.3. Prefer non-final classes (semi-optional)

A central feature of Hibernate, proxies (lazy loading), depends upon the
persistent class being either non-final, or the implementation of an interface that declares all public
methods. You can persist final classes that do not implement an interface with
Hibernate; you will not, however, be able to use proxies for lazy association fetching which will
ultimately limit your options for performance tuning. To persist a final
class which does not implement a "full" interface you must disable proxy generation. See
Example 4.2, “Disabling proxies in hbm.xml” and
Example 4.3, “Disabling proxies in annotations”.

Cat declares accessor methods for all its persistent fields. Many other ORM
tools directly persist instance variables. It is better to provide an indirection between the relational
schema and internal data structures of the class. By default, Hibernate persists JavaBeans style
properties and recognizes method names of the form getFoo, isFoo
and setFoo. If required, you can switch to direct field access for particular
properties.

Properties need not be declared public. Hibernate can persist a property declared
with package, protected or private visibility
as well.

4.2. Implementing inheritance

A subclass must also observe the first and second rules. It inherits
its identifier property from the superclass, Cat. For
example:

4.3. Implementing equals() and
hashCode()

intend to put instances of persistent classes in a
Set (the recommended way to represent many-valued
associations); and

intend to use reattachment of detached instances

Hibernate guarantees equivalence of persistent identity (database
row) and Java identity only inside a particular session scope. When you
mix instances retrieved in different sessions, you must implement
equals() and hashCode() if you wish
to have meaningful semantics for Sets.

The most obvious way is to implement
equals()/hashCode() by comparing the
identifier value of both objects. If the value is the same, both must be
the same database row, because they are equal. If both are added to a
Set, you will only have one element in the
Set). Unfortunately, you cannot use that approach with
generated identifiers. Hibernate will only assign identifier values to
objects that are persistent; a newly created instance will not have any
identifier value. Furthermore, if an instance is unsaved and currently in
a Set, saving it will assign an identifier value to the
object. If equals() and hashCode()
are based on the identifier value, the hash code would change, breaking
the contract of the Set. See the Hibernate website for
a full discussion of this problem. This is not a Hibernate issue, but
normal Java semantics of object identity and equality.

It is recommended that you implement equals() and
hashCode() using Business key
equality. Business key equality means that the
equals() method compares only the properties that form
the business key. It is a key that would identify our instance in the real
world (a natural candidate key):

4.4. Dynamic models

Note

The following features are currently considered
experimental and may change in the near future.

Persistent entities do not necessarily have to be represented as
POJO classes or as JavaBean objects at runtime. Hibernate also supports
dynamic models (using Maps of Maps
at runtime). With this approach, you do not write persistent classes,
only mapping files.

By default, Hibernate works in normal POJO mode. You can set a
default entity representation mode for a particular
SessionFactory using the
default_entity_mode configuration option (see Table 3.3, “Hibernate Configuration Properties”).

The following examples demonstrate the representation using
Maps. First, in the mapping file an
entity-name has to be declared instead of, or in
addition to, a class name:

One of the main advantages of dynamic mapping is quick turnaround
time for prototyping, without the need for entity class implementation.
However, you lose compile-time type checking and will likely deal with
many exceptions at runtime. As a result of the Hibernate mapping, the
database schema can easily be normalized and sound, allowing to add a
proper domain model implementation on top later on.

Please note that the call to getSession() using
an EntityMode is on the Session API,
not the SessionFactory. That way, the new
Session shares the underlying JDBC connection,
transaction, and other context information. This means you do not have to
call flush() and close() on the
secondary Session, and also leave the transaction and
connection handling to the primary unit of work.

4.5. Tuplizers

org.hibernate.tuple.Tuplizer and its sub-interfaces are responsible for
managing a particular representation of a piece of data given that representation's
org.hibernate.EntityMode. If a given piece of data is thought of as a data
structure, then a tuplizer is the thing that knows how to create such a data structure, how to extract
values from such a data structure and how to inject values into such a data structure. For example, for
the POJO entity mode, the corresponding tuplizer knows how create the POJO through its constructor.
It also knows how to access the POJO properties using the defined property accessors.

There are two (high-level) types of Tuplizers:

org.hibernate.tuple.entity.EntityTuplizer which is
responsible for managing the above mentioned contracts in regards to entities

org.hibernate.tuple.component.ComponentTuplizer which does the
same for components

Users can also plug in their own tuplizers. Perhaps you require that
java.util.Map implementation other than
java.util.HashMap be used while in the dynamic-map entity-mode. Or perhaps you
need to define a different proxy generation strategy than the one used by default. Both would be achieved
by defining a custom tuplizer implementation. Tuplizer definitions are attached to the entity or component
mapping they are meant to manage. Going back to the example of our Customer entity,
Example 4.6, “Specify custom tuplizers in annotations” shows how to specify a custom
org.hibernate.tuple.entity.EntityTuplizer using annotations while
Example 4.7, “Specify custom tuplizers in hbm.xml” shows how to do the same in hbm.xml

4.6. EntityNameResolvers

org.hibernate.EntityNameResolver is a contract for resolving the entity name
of a given entity instance. The interface defines a single method resolveEntityName
which is passed the entity instance and is expected to return the appropriate entity name (null is
allowed and would indicate that the resolver does not know how to resolve the entity name of the given entity
instance). Generally speaking, an org.hibernate.EntityNameResolver is going
to be most useful in the case of dynamic models. One example might be using proxied interfaces as your
domain model. The hibernate test suite has an example of this exact style of usage under the
org.hibernate.test.dynamicentity.tuplizer2. Here is some of the code from that package
for illustration.

Annotations are split in two categories, the logical mapping
annotations (describing the object model, the association between two
entities etc.) and the physical mapping annotations (describing the
physical schema, tables, columns, indexes, etc). We will mix annotations
from both categories in the following code examples.

JPA annotations are in the javax.persistence.*
package. Hibernate specific extensions are in
org.hibernate.annotations.*. You favorite IDE can
auto-complete annotations and their attributes for you (even without a
specific "JPA" plugin, since JPA annotations are plain Java 5
annotations).

The legacy hbm.xml approach uses an XML schema designed to be
readable and hand-editable. The mapping language is Java-centric, meaning
that mappings are constructed around persistent class declarations and not
table declarations.

Please note that even though many Hibernate users choose to write
the XML by hand, a number of tools exist to generate the mapping document.
These include XDoclet, Middlegen and AndroMDA.

We will now discuss the concepts of the mapping documents (both
annotations and XML). We will only describe, however, the document
elements and attributes that are used by Hibernate at runtime. The mapping
document also contains some extra optional attributes and elements that
affect the database schemas exported by the schema export tool (for
example, the not-null attribute).

5.1.1. Entity

An entity is a regular Java object (aka POJO) which will be
persisted by Hibernate.

To mark an object as an entity in annotations, use the
@Entity annotation.

That's pretty much it, the rest is optional. There are however any
options to tweak your entity mapping, let's explore them.

@Table lets you define the table the entity
will be persisted into. If undefined, the table name is the unqualified
class name of the entity. You can also optionally define the catalog,
the schema as well as unique constraints on the table.

The constraint name is optional (generated if left undefined). The
column names composing the constraint correspond to the column names as
defined before the Hibernate NamingStrategy is
applied.

Tip

Be sure to use the database-level column names for the columnNames
property of a @UniqueConstraint. For example, whilst for simple types the
database-level column name may be the same as the entity-level property name, this is often
not the case for relational properties.

@Entity.name lets you define the shortcut name
of the entity you can used in JP-QL and HQL queries. It defaults to the
unqualified class name of the class.

Hibernate goes beyond the JPA specification and provide additional
configurations. Some of them are hosted on
@org.hibernate.annotations.Entity:

dynamicInsert /
dynamicUpdate (defaults to false): specifies that
INSERT / UPDATE SQL should be
generated at runtime and contain only the columns whose values are
not null. The dynamic-update and
dynamic-insert settings are not inherited by
subclasses. Although these settings can increase performance in some
cases, they can actually decrease performance in others.

selectBeforeUpdate (defaults to false):
specifies that Hibernate should never perform
an SQL UPDATE unless it is certain that an object
is actually modified. Only when a transient object has been
associated with a new session using update(),
will Hibernate perform an extra SQL SELECT to
determine if an UPDATE is actually required. Use
of select-before-update will usually decrease
performance. It is useful to prevent a database update trigger being
called unnecessarily if you reattach a graph of detached instances
to a Session.

polymorphisms (defaults to
IMPLICIT): determines whether implicit or
explicit query polymorphisms is used. Implicit
polymorphisms means that instances of the class will be returned by
a query that names any superclass or implemented interface or class,
and that instances of any subclass of the class will be returned by
a query that names the class itself. Explicit
polymorphisms means that class instances will be returned only by
queries that explicitly name that class. Queries that name the class
will return only instances of subclasses mapped. For most purposes,
the default polymorphisms=IMPLICIT is
appropriate. Explicit polymorphisms is useful when two different
classes are mapped to the same table This allows a "lightweight"
class that contains a subset of the table columns.

persister: specifies a custom
ClassPersister. The persister
attribute lets you customize the persistence strategy used for the
class. You can, for example, specify your own subclass of
org.hibernate.persister.EntityPersister, or you
can even provide a completely new implementation of the interface
org.hibernate.persister.ClassPersister that
implements, for example, persistence via stored procedure calls,
serialization to flat files or LDAP. See
org.hibernate.test.CustomPersister for a simple
example of "persistence" to a Hashtable.

optimisticLock (defaults to
VERSION): determines the optimistic locking
strategy. If you enable dynamicUpdate, you will
have a choice of optimistic locking strategies:

version: check the version/timestamp
columns

all: check all columns

dirty: check the changed columns,
allowing some concurrent updates

none: do not use optimistic
locking

It is strongly recommended that you use
version/timestamp columns for optimistic locking with Hibernate.
This strategy optimizes performance and correctly handles
modifications made to detached instances (i.e. when
Session.merge() is used).

Tip

Be sure to import
@javax.persistence.Entity to mark a class as an
entity. It's a common mistake to import
@org.hibernate.annotations.Entity by
accident.

Some entities are not mutable. They cannot be updated
by the application. This allows Hibernate to make some minor performance
optimizations.. Use the @Immutable
annotation.

You can also alter how Hibernate deals with lazy initialization
for this class. On @Proxy, use
lazy=false to disable lazy fetching (not
recommended). You can also specify an interface to use for lazy
initializing proxies (defaults to the class itself): use
proxyClass on @Proxy.
Hibernate will initially return proxies ( using bytecode provider defined by hibernate.bytecode.provider) that
implement the named interface. The persistent object will load when a
method of the proxy is invoked. See "Initializing collections and
proxies" below.

@BatchSize specifies a "batch size" for
fetching instances of this class by identifier. Not yet loaded instances
are loaded batch-size at a time (default 1).

You can specific an arbitrary SQL WHERE condition to be used when
retrieving objects of this class. Use @Where for
that.

In the same vein, @Check lets you define an
SQL expression used to generate a multi-row check
constraint for automatic schema generation.

There is no difference between a view and a base table for a
Hibernate mapping. This is transparent at the database level, although
some DBMS do not support views properly, especially with updates.
Sometimes you want to use a view, but you cannot create one in the
database (i.e. with a legacy schema). In this case, you can map an
immutable and read-only entity to a given SQL subselect expression using
@org.hibernate.annotations.Subselect:

Declare the tables to synchronize this entity with, ensuring that
auto-flush happens correctly and that queries against the derived entity
do not return stale data. The <subselect> is
available both as an attribute and a nested mapping element.

We will now explore the same options using the hbm.xml structure.
You can declare a persistent class using the class
element. For example:

name (optional): the fully qualified Java
class name of the persistent class or interface. If this attribute
is missing, it is assumed that the mapping is for a non-POJO
entity.

table (optional - defaults to the
unqualified class name): the name of its database table.

discriminator-value (optional - defaults
to the class name): a value that distinguishes individual
subclasses that is used for polymorphic behavior. Acceptable
values include null and not
null.

mutable (optional - defaults to
true): specifies that instances of the class
are (not) mutable.

schema (optional): overrides the schema
name specified by the root
<hibernate-mapping> element.

catalog (optional): overrides the catalog
name specified by the root
<hibernate-mapping> element.

proxy (optional): specifies an interface
to use for lazy initializing proxies. You can specify the name of
the class itself.

dynamic-update (optional - defaults to
false): specifies that
UPDATE SQL should be generated at runtime and
can contain only those columns whose values have changed.

dynamic-insert (optional - defaults to
false): specifies that
INSERT SQL should be generated at runtime and
contain only the columns whose values are not null.

select-before-update (optional - defaults
to false): specifies that Hibernate should
never perform an SQL
UPDATE unless it is certain that an object is
actually modified. Only when a transient object has been
associated with a new session using update(),
will Hibernate perform an extra SQL SELECT to
determine if an UPDATE is actually
required.

lazy (optional): lazy fetching can be
disabled by setting lazy="false".

(17)

entity-name (optional - defaults to the
class name): Hibernate allows a class to be mapped multiple
times, potentially to different tables. It also allows entity
mappings that are represented by Maps or XML at the Java level. In
these cases, you should provide an explicit arbitrary name for the
entity. See Section 4.4, “Dynamic models”
and ??? for more information.

(18)

check (optional): an SQL expression used
to generate a multi-row check constraint for
automatic schema generation.

(19)

rowid (optional): Hibernate can use
ROWIDs on databases. On Oracle, for example, Hibernate can use the
rowid extra column for fast updates once this
option has been set to rowid. A ROWID is an
implementation detail and represents the physical location of a
stored tuple.

(20)

subselect (optional): maps an immutable
and read-only entity to a database subselect. This is useful if
you want to have a view instead of a base table. See below for
more information.

(21)

abstract (optional): is used to mark
abstract superclasses in <union-subclass>
hierarchies.

It is acceptable for the named persistent class to be an
interface. You can declare implementing classes of that interface using
the <subclass> element. You can persist any
static inner class. Specify the class name using
the standard form i.e. e.g.Foo$Bar.

column (optional - defaults to the
property name): the name of the primary key column.

unsaved-value (optional - defaults to a
"sensible" value): an identifier property value that indicates an
instance is newly instantiated (unsaved), distinguishing it from
detached instances that were saved or loaded in a previous
session.

access (optional - defaults to
property): the strategy Hibernate should use
for accessing the property value.

If the name attribute is missing, it is assumed
that the class has no identifier property.

The unsaved-value attribute is almost never
needed in Hibernate and indeed has no corresponding element in
annotations.

You can also declare the identifier as a composite identifier.
This allows access to legacy data with composite keys. Its use is
strongly discouraged for anything else.

5.1.2.1. Composite identifier

You can define a composite primary key through several
syntaxes:

use a component type to represent the identifier and map it
as a property in the entity: you then annotated the property as
@EmbeddedId. The component type has to be
Serializable.

map multiple properties as @Id
properties: the identifier type is then the entity class itself
and needs to be Serializable. This approach
is unfortunately not standard and only supported by
Hibernate.

map multiple properties as @Id
properties and declare an external class to be the identifier
type. This class, which needs to be
Serializable, is declared on the entity via
the @IdClass annotation. The identifier
type must contain the same properties as the identifier properties
of the entity: each property name must be the same, its type must
be the same as well if the entity property is of a basic type, its
type must be the type of the primary key of the associated entity
if the entity property is an association (either a
@OneToOne or a
@ManyToOne).

As you can see the last case is far from obvious. It has been
inherited from the dark ages of EJB 2 for backward compatibilities and
we recommend you not to use it (for simplicity sake).

In the embedded id object, the association is represented as
the identifier of the associated entity. But you can link its value
to a regular association in the entity via the
@MapsId annotation. The
@MapsId value correspond to the property name
of the embedded id object containing the associated entity's
identifier. In the database, it means that the
Customer.user and the
CustomerId.userId properties share the same
underlying column (user_fk in this case).

Tip

The component type used as identifier must implement
equals() and
hashCode().

In practice, your code only sets the
Customer.user property and the user id value is
copied by Hibernate into the CustomerId.userId
property.

Warning

The id value can be copied as late as flush time, don't rely
on it until after flush time.

While not supported in JPA, Hibernate lets you place your
association directly in the embedded id component (instead of having
to use the @MapsId annotation).

This is the recommended approach to map composite identifier.
The following options should not be considered unless some
constraint are present.

5.1.2.1.2. Multiple id properties without identifier type

Another, arguably more natural, approach is to place
@Id on multiple properties of your entity.
This approach is only supported by Hibernate (not JPA compliant) but
does not require an extra embeddable component.

5.1.2.1.3. Multiple id properties with with a dedicated identifier
type

@IdClass on an entity points to the
class (component) representing the identifier of the class. The
properties marked @Id on the entity must have
their corresponding property on the @IdClass.
The return type of search twin property must be either identical for
basic properties or must correspond to the identifier class of the
associated entity for an association.

Warning

This approach is inherited from the EJB 2 days and we
recommend against its use. But, after all it's your application
and Hibernate supports it.

5.1.2.2. Identifier generator

Hibernate can generate and populate identifier values for you
automatically. This is the recommended approach over "business" or
"natural" id (especially composite ids).

Hibernate offers various generation strategies, let's explore
the most common ones first that happens to be standardized by
JPA:

IDENTITY: supports identity columns in DB2, MySQL, MS SQL
Server, Sybase and HypersonicSQL. The returned identifier is of
type long, short or
int.

SEQUENCE (called seqhilo in Hibernate):
uses a hi/lo algorithm to efficiently generate identifiers of type
long, short or
int, given a named database sequence.

TABLE (called
MultipleHiLoPerTableGenerator in Hibernate)
: uses a hi/lo algorithm to efficiently generate identifiers of
type long, short or
int, given a table and column as a source of hi
values. The hi/lo algorithm generates identifiers that are unique
only for a particular database.

AUTO: selects IDENTITY,
SEQUENCE or TABLE depending
upon the capabilities of the underlying database.

Important

We recommend all new projects to use the new enhanced
identifier generators. They are deactivated by default for entities
using annotations but can be activated using
hibernate.id.new_generator_mappings=true. These new
generators are more efficient and closer to the JPA 2 specification
semantic.

However they are not backward compatible with existing
Hibernate based application (if a sequence or a table is used for id
generation). See XXXXXXX ??? for
more information on how to activate them.

To mark an id property as generated, use the
@GeneratedValue annotation. You can specify the
strategy used (default to AUTO) by setting
strategy.

The scope of a generator definition can be the application or
the class. Class-defined generators are not visible outside the class
and can override application level generators. Application level
generators are defined in JPA's XML deployment descriptors (see XXXXXX
???):

If a JPA XML descriptor (like
META-INF/orm.xml) is used to define the
generators, EMP_GEN and SEQ_GEN
are application level generators.

Note

Package level definition is not supported by the JPA
specification. However, you can use the
@GenericGenerator at the package level (see ???).

These are the four standard JPA generators. Hibernate goes
beyond that and provide additional generators or additional options as
we will see below. You can also write your own custom identifier
generator by implementing
org.hibernate.id.IdentifierGenerator.

To define a custom generator, use the
@GenericGenerator annotation (and its plural
counter part @GenericGenerators) that describes
the class of the identifier generator or its short cut name (as
described below) and a list of key/value parameters. When using
@GenericGenerator and assigning it via
@GeneratedValue.generator, the
@GeneratedValue.strategy is ignored: leave it
blank.

The hbm.xml approach uses the optional
<generator> child element inside
<id>. If any parameters are required to
configure or initialize the generator instance, they are passed using
the <param> element.

5.1.2.2.1. Various additional generators

All generators implement the interface
org.hibernate.id.IdentifierGenerator. This is a
very simple interface. Some applications can choose to provide their
own specialized implementations, however, Hibernate provides a range
of built-in implementations. The shortcut names for the built-in
generators are as follows:

increment

generates identifiers of type long,
short or int that are
unique only when no other process is inserting data into the
same table. Do not use in a
cluster.

identity

supports identity columns in DB2, MySQL, MS SQL
Server, Sybase and HypersonicSQL. The returned identifier is
of type long, short or
int.

sequence

uses a sequence in DB2, PostgreSQL, Oracle, SAP DB,
McKoi or a generator in Interbase. The returned identifier
is of type long, short
or int

hilo

uses a hi/lo algorithm to efficiently generate
identifiers of type long,
short or int, given a
table and column (by default
hibernate_unique_key and
next_hi respectively) as a source of hi
values. The hi/lo algorithm generates identifiers that are
unique only for a particular database.

seqhilo

uses a hi/lo algorithm to efficiently generate
identifiers of type long,
short or int, given a
named database sequence.

uuid

Generates a 128-bit UUID based on a custom algorithm.
The value generated is represented as a string of 32
hexidecimal digits. Users can also configure it to use a
separator (config parameter "separator") which separates the
hexidecimal digits into 8{sep}8{sep}4{sep}8{sep}4. Note
specifically that this is different than the IETF RFC 4122
representation of 8-4-4-4-12. If you need RFC 4122 compliant
UUIDs, consider using "uuid2" generator discussed
below.

uuid2

Generates a IETF RFC 4122 compliant (variant 2)
128-bit UUID. The exact "version" (the RFC term) generated
depends on the pluggable "generation strategy" used (see
below). Capable of generating values as
java.util.UUID,
java.lang.String or as a byte array
of length 16 (byte[16]). The "generation
strategy" is defined by the interface
org.hibernate.id.UUIDGenerationStrategy.
The generator defines 2 configuration parameters for
defining which generation strategy to use:

org.hibernate.id.uuid.CustomVersionOneStrategy
- generates "version 1" UUID values, using IP address
since mac address not available. If you need mac
address to be used, consider leveraging one of the
existing third party UUID generators which sniff out
mac address and integrating it via the
org.hibernate.id.UUIDGenerationStrategy
contract. Two such libraries known at time of this
writing include http://johannburkard.de/software/uuid/
and http://commons.apache.org/sandbox/id/uuid.html

guid

uses a database-generated GUID string on MS SQL Server
and MySQL.

native

selects identity,
sequence or hilo
depending upon the capabilities of the underlying
database.

assigned

lets the application assign an identifier to the
object before save() is called. This is
the default strategy if no
<generator> element is
specified.

select

retrieves a primary key, assigned by a database
trigger, by selecting the row by some unique key and
retrieving the primary key value.

foreign

uses the identifier of another associated object. It
is usually used in conjunction with a
<one-to-one> primary key
association.

sequence-identity

a specialized sequence generation strategy that
utilizes a database sequence for the actual value
generation, but combines this with JDBC3 getGeneratedKeys to
return the generated identifier value as part of the insert
statement execution. This strategy is only supported on
Oracle 10g drivers targeted for JDK 1.4. Comments on these
insert statements are disabled due to a bug in the Oracle
drivers.

5.1.2.2.2. Hi/lo algorithm

The hilo and seqhilo
generators provide two alternate implementations of the hi/lo
algorithm. The first implementation requires a "special" database
table to hold the next available "hi" value. Where supported, the
second uses an Oracle-style sequence.

Unfortunately, you cannot use hilo when
supplying your own Connection to Hibernate. When
Hibernate uses an application server datasource to obtain
connections enlisted with JTA, you must configure the
hibernate.transaction.manager_lookup_class.

5.1.2.2.3. UUID algorithm

The UUID contains: IP address, startup time of the JVM that is
accurate to a quarter second, system time and a counter value that
is unique within the JVM. It is not possible to obtain a MAC address
or memory address from Java code, so this is the best option without
using JNI.

5.1.2.2.4. Identity columns and sequences

For databases that support identity columns (DB2, MySQL,
Sybase, MS SQL), you can use identity key
generation. For databases that support sequences (DB2, Oracle,
PostgreSQL, Interbase, McKoi, SAP DB) you can use
sequence style key generation. Both of these
strategies require two SQL queries to insert a new object. For
example:

For cross-platform development, the native
strategy will, depending on the capabilities of the underlying
database, choose from the identity,
sequence and hilo
strategies.

5.1.2.2.5. Assigned identifiers

If you want the application to assign identifiers, as opposed
to having Hibernate generate them, you can use the
assigned generator. This special generator uses
the identifier value already assigned to the object's identifier
property. The generator is used when the primary key is a natural
key instead of a surrogate key. This is the default behavior if you
do not specify @GeneratedValue nor
<generator> elements.

The assigned generator makes Hibernate use
unsaved-value="undefined". This forces Hibernate
to go to the database to determine if an instance is transient or
detached, unless there is a version or timestamp property, or you
define Interceptor.isUnsaved().

5.1.2.2.6. Primary keys assigned by triggers

Hibernate does not generate DDL with triggers. It is for
legacy schemas only.

In the above example, there is a unique valued property named
socialSecurityNumber. It is defined by the class,
as a natural key and a surrogate key named
person_id, whose value is generated by a
trigger.

5.1.2.2.7. Identity copy (foreign generator)

Finally, you can ask Hibernate to copy the identifier from
another associated entity. In the Hibernate jargon, it is known as a
foreign generator but the JPA mapping reads better and is
encouraged.

5.1.2.3. Enhanced identifier generators

Starting with release 3.2.3, there are 2 new generators which
represent a re-thinking of 2 different aspects of identifier
generation. The first aspect is database portability; the second is
optimization Optimization means that you do not have to query the
database for every request for a new identifier value. These two new
generators are intended to take the place of some of the named
generators described above, starting in 3.3.x. However, they are
included in the current releases and can be referenced by FQN.

The first of these new generators is
org.hibernate.id.enhanced.SequenceStyleGenerator
which is intended, firstly, as a replacement for the
sequence generator and, secondly, as a better
portability generator than native. This is because
native generally chooses between
identity and sequence which have
largely different semantics that can cause subtle issues in
applications eyeing portability.
org.hibernate.id.enhanced.SequenceStyleGenerator,
however, achieves portability in a different manner. It chooses
between a table or a sequence in the database to store its
incrementing values, depending on the capabilities of the dialect
being used. The difference between this and native
is that table-based and sequence-based storage have the same exact
semantic. In fact, sequences are exactly what Hibernate tries to
emulate with its table-based generators. This generator has a number
of configuration parameters:

sequence_name (optional, defaults to
hibernate_sequence): the name of the sequence
or table to be used.

initial_value (optional, defaults to
1): the initial value to be retrieved from
the sequence/table. In sequence creation terms, this is
analogous to the clause typically named "STARTS WITH".

increment_size (optional - defaults to
1): the value by which subsequent calls to
the sequence/table should differ. In sequence creation terms,
this is analogous to the clause typically named "INCREMENT
BY".

force_table_use (optional - defaults to
false): should we force the use of a table as
the backing structure even though the dialect might support
sequence?

value_column (optional - defaults to
next_val): only relevant for table
structures, it is the name of the column on the table which is
used to hold the value.

prefer_sequence_per_entity (optional -
defaults to false): should we create
separate sequence for each entity that share current generator
based on its name?

sequence_per_entity_suffix (optional -
defaults to _SEQ): suffix added to the name
of a dedicated sequence.

The second of these new generators is
org.hibernate.id.enhanced.TableGenerator, which is
intended, firstly, as a replacement for the table
generator, even though it actually functions much more like
org.hibernate.id.MultipleHiLoPerTableGenerator, and
secondly, as a re-implementation of
org.hibernate.id.MultipleHiLoPerTableGenerator that
utilizes the notion of pluggable optimizers. Essentially this
generator defines a table capable of holding a number of different
increment values simultaneously by using multiple distinctly keyed
rows. This generator has a number of configuration parameters:

table_name (optional - defaults to
hibernate_sequences): the name of the table
to be used.

value_column_name (optional - defaults
to next_val): the name of the column on the
table that is used to hold the value.

segment_column_name (optional -
defaults to sequence_name): the name of the
column on the table that is used to hold the "segment key". This
is the value which identifies which increment value to
use.

segment_value (optional - defaults to
default): The "segment key" value for the
segment from which we want to pull increment values for this
generator.

segment_value_length (optional -
defaults to 255): Used for schema generation;
the column size to create this segment key column.

initial_value (optional - defaults to
1): The initial value to be retrieved from
the table.

increment_size (optional - defaults to
1): The value by which subsequent calls to
the table should differ.

5.1.2.3.1. Identifier generator optimization

For identifier generators that store values in the database,
it is inefficient for them to hit the database on each and every
call to generate a new identifier value. Instead, you can group a
bunch of them in memory and only hit the database when you have
exhausted your in-memory value group. This is the role of the
pluggable optimizers. Currently only the two enhanced generators
(Section 5.1.2.3, “Enhanced identifier generators” support this
operation.

none (generally this is the default if
no optimizer was specified): this will not perform any
optimizations and hit the database for each and every
request.

hilo: applies a hi/lo algorithm around
the database retrieved values. The values from the database for
this optimizer are expected to be sequential. The values
retrieved from the database structure for this optimizer
indicates the "group number". The
increment_size is multiplied by that value in
memory to define a group "hi value".

pooled: as with the case of
hilo, this optimizer attempts to minimize the
number of hits to the database. Here, however, we simply store
the starting value for the "next group" into the database
structure rather than a sequential value in combination with an
in-memory grouping algorithm. Here,
increment_size refers to the values coming
from the database.

5.1.2.4. Partial identifier generation

Hibernate supports the automatic generation of some of the
identifier properties. Simply use the
@GeneratedValue annotation on one or several id
properties.

Warning

The Hibernate team has always felt such a construct as
fundamentally wrong. Try hard to fix your data model before using
this feature.

5.1.3. Optimistic locking properties (optional)

When using long transactions or conversations that span several
database transactions, it is useful to store versioning data to ensure
that if the same entity is updated by two conversations, the last to
commit changes will be informed and not override the other
conversation's work. It guarantees some isolation while still allowing
for good scalability and works particularly well in read-often
write-sometimes situations.

You can use two approaches: a dedicated version number or a
timestamp.

A version or timestamp property should never be null for a
detached instance. Hibernate will detect any instance with a null
version or timestamp as transient, irrespective of what other
unsaved-value strategies are specified.
Declaring a nullable version or timestamp property is an easy
way to avoid problems with transitive reattachment in Hibernate. It is
especially useful for people using assigned identifiers or composite
keys.

5.1.3.1. Version number

You can add optimistic locking capability to an entity using the
@Version annotation:

The version property will be mapped to the
OPTLOCK column, and the entity manager will use it
to detect conflicting updates (preventing lost updates you might
otherwise see with the last-commit-wins strategy).

The version column may be a numeric. Hibernate supports any kind
of type provided that you define and implement the appropriate
UserVersionType.

The application must not alter the version number set up by
Hibernate in any way. To artificially increase the version number,
check in Hibernate Entity Manager's reference documentation
LockModeType.OPTIMISTIC_FORCE_INCREMENT or
LockModeType.PESSIMISTIC_FORCE_INCREMENT.

If the version number is generated by the database (via a
trigger for example), make sure to use
@org.hibernate.annotations.Generated(GenerationTime.ALWAYS).

unsaved-value (optional - defaults to
undefined): a version property value that
indicates that an instance is newly instantiated (unsaved),
distinguishing it from detached instances that were saved or
loaded in a previous session. Undefined
specifies that the identifier property value should be
used.

generated (optional - defaults to
never): specifies that this version property
value is generated by the database. See the discussion of generated properties for more
information.

insert (optional - defaults to
true): specifies whether the version column
should be included in SQL insert statements. It can be set to
false if the database column is defined with
a default value of 0.

5.1.3.2. Timestamp

Alternatively, you can use a timestamp. Timestamps are a less
safe implementation of optimistic locking. However, sometimes an
application might use the timestamps in other ways as well.

When using timestamp versioning you can tell Hibernate where to
retrieve the timestamp value from - database or JVM - by optionally
adding the @org.hibernate.annotations.Source
annotation to the property. Possible values for the value attribute of
the annotation are
org.hibernate.annotations.SourceType.VM and
org.hibernate.annotations.SourceType.DB. The
default is SourceType.DB which is also used in
case there is no @Source annotation at
all.

Like in the case of version numbers, the timestamp can also be
generated by the database instead of Hibernate. To do that, use
@org.hibernate.annotations.Generated(GenerationTime.ALWAYS).

unsaved-value (optional - defaults to
null): a version property value that
indicates that an instance is newly instantiated (unsaved),
distinguishing it from detached instances that were saved or
loaded in a previous session. Undefined
specifies that the identifier property value should be
used.

source (optional - defaults to
vm): Where should Hibernate retrieve the
timestamp value from? From the database, or from the current
JVM? Database-based timestamps incur an overhead because
Hibernate must hit the database in order to determine the "next
value". It is safer to use in clustered environments. Not all
Dialects are known to support the retrieval
of the database's current timestamp. Others may also be unsafe
for usage in locking due to lack of precision (Oracle 8, for
example).

generated (optional - defaults to
never): specifies that this timestamp
property value is actually generated by the database. See the
discussion of generated
properties for more information.

Note

<Timestamp> is equivalent to
<version type="timestamp">. And
<timestamp source="db"> is equivalent to
<version type="dbtimestamp">

5.1.4. Property

You need to decide which property needs to be made persistent in a
given entity. This differs slightly between the annotation driven
metadata and the hbm.xml files.

5.1.4.1. Property mapping with annotations

In the annotations world, every non static non transient
property (field or method depending on the access type) of an entity
is considered persistent, unless you annotate it as
@Transient. Not having an annotation for your
property is equivalent to the appropriate @Basic
annotation.

The @Basic annotation allows you to declare
the fetching strategy for a property. If set to
LAZY, specifies that this property should be
fetched lazily when the instance variable is first accessed. It
requires build-time bytecode instrumentation, if your classes are not
instrumented, property level lazy loading is silently ignored. The
default is EAGER. You can also mark a property as
not optional thanks to the @Basic.optional
attribute. This will ensure that the underlying column are not
nullable (if possible). Note that a better approach is to use the
@NotNull annotation of the Bean Validation
specification.

counter, a transient field, and
lengthInMeter, a method annotated as
@Transient, and will be ignored by the Hibernate.
name, length, and
firstname properties are mapped persistent and
eagerly fetched (the default for simple properties). The
detailedComment property value will be lazily
fetched from the database once a lazy property of the entity is
accessed for the first time. Usually you don't need to lazy simple
properties (not to be confused with lazy association fetching). The
recommended alternative is to use the projection capability of JP-QL
(Java Persistence Query Language) or Criteria queries.

JPA support property mapping of all basic types supported by
Hibernate (all basic Java types , their respective wrappers and
serializable classes). Hibernate Annotations supports out of the box
enum type mapping either into a ordinal column (saving the enum
ordinal) or a string based column (saving the enum string
representation): the persistence representation, defaulted to ordinal,
can be overridden through the @Enumerated
annotation as shown in the note property
example.

In plain Java APIs, the temporal precision of time is not
defined. When dealing with temporal data you might want to describe
the expected precision in database. Temporal data can have
DATE, TIME, or
TIMESTAMP precision (ie the actual date, only the
time, or both). Use the @Temporal annotation to
fine tune that.

@Lob indicates that the property should be
persisted in a Blob or a Clob depending on the property type:
java.sql.Clob,
Character[], char[] and
java.lang.String will be persisted in a Clob.
java.sql.Blob, Byte[],
byte[] and Serializable
type will be persisted in a Blob.

The name of a Java class with a default basic type:
int, float, char, java.lang.String, java.util.Date,
java.lang.Integer, java.sql.Clob etc.

The name of a serializable Java class.

The class name of a custom type:
com.illflow.type.MyCustomType etc.

If you do not specify a type, Hibernate will use reflection
upon the named property and guess the correct Hibernate type.
Hibernate will attempt to interpret the name of the return class of
the property getter using, in order, rules 2, 3, and 4.

@org.hibernate.annotations.TypeDef and
@org.hibernate.annotations.TypeDefs allows you to
declare type definitions. These annotations can be placed at the
class or package level. Note that these definitions are global for
the session factory (even when defined at the class level). If the
type is used on a single entity, you can place the definition on the
entity itself. Otherwise, it is recommended to place the definition
at the package level. In the example below, when Hibernate
encounters a property of class PhoneNumer, it
delegates the persistence strategy to the custom mapping type
PhoneNumberType. However, properties belonging to
other classes, too, can delegate their persistence strategy to
PhoneNumberType, by explicitly using the
@Type annotation.

Note

Package level annotations are placed in a file named
package-info.java in the appropriate package.
Place your annotations before the package declaration.

5.1.4.1.2. Access type

By default the access type of a class hierarchy is defined by
the position of the @Id or
@EmbeddedId annotations. If these annotations
are on a field, then only fields are considered for persistence and
the state is accessed via the field. If these annotations are on a
getter, then only the getters are considered for persistence and the
state is accessed via the getter/setter. That works well in practice
and is the recommended approach.

Note

The placement of annotations within a class hierarchy has
to be consistent (either field or on property) to be able to
determine the default access type. It is recommended to stick to
one single annotation placement strategy throughout your whole
application.

However in some situations, you need to:

force the access type of the entity hierarchy

override the access type of a specific entity in the class
hierarchy

override the access type of an embeddable type

The best use case is an embeddable class used by several
entities that might not use the same access type. In this case it is
better to force the access type at the embeddable class
level.

To force the access type on a given class, use the
@Access annotation as showed below:

In this example, the default access type is
FIELD except for the
orderNumber property. Note that the corresponding
field, if any must be marked as @Transient or
transient.

@org.hibernate.annotations.AccessType

The annotation
@org.hibernate.annotations.AccessType
should be considered deprecated for FIELD and PROPERTY access. It
is still useful however if you need to use a custom access
type.

5.1.4.1.3. Optimistic lock

It is sometimes useful to avoid increasing the version number
even if a given property is dirty (particularly collections). You
can do that by annotating the property (or collection) with
@OptimisticLock(excluded=true).

More formally, specifies that updates to this property do not
require acquisition of the optimistic lock.

5.1.4.1.4. Declaring column attributes

The column(s) used for a property mapping can be defined using
the @Column annotation. Use it to override
default values (see the JPA specification for more information on
the defaults). You can use this annotation at the property level for
properties that are:

5.1.4.1.5. Formula

Sometimes, you want the Database to do some computation for
you rather than in the JVM, you might also create some kind of
virtual column. You can use a SQL fragment (aka formula) instead of
mapping a property into a column. This kind of property is read only
(its value is calculated by your formula fragment).

column (optional - defaults to the
property name): the name of the mapped database table column.
This can also be specified by nested
<column> element(s).

type (optional): a name that indicates
the Hibernate type.

update, insert (optional - defaults to
true): specifies that the mapped columns
should be included in SQL UPDATE and/or
INSERT statements. Setting both to
false allows a pure "derived" property whose
value is initialized from some other property that maps to the
same column(s), or by a trigger or other application.

formula (optional): an SQL expression
that defines the value for a computed
property. Computed properties do not have a column mapping of
their own.

lazy (optional - defaults to
false): specifies that this property should
be fetched lazily when the instance variable is first accessed.
It requires build-time bytecode instrumentation.

unique (optional): enables the DDL
generation of a unique constraint for the columns. Also, allow
this to be the target of a
property-ref.

not-null (optional): enables the DDL
generation of a nullability constraint for the columns.

optimistic-lock (optional - defaults to
true): specifies that updates to this
property do or do not require acquisition of the optimistic
lock. In other words, it determines if a version increment
should occur when this property is dirty.

generated (optional - defaults to
never): specifies that this property value is
actually generated by the database. See the discussion of generated properties for more
information.

The name of a Java class with a default basic type:
int, float, char, java.lang.String, java.util.Date,
java.lang.Integer, java.sql.Clob etc.

The name of a serializable Java class.

The class name of a custom type:
com.illflow.type.MyCustomType etc.

If you do not specify a type, Hibernate will use reflection upon
the named property and guess the correct Hibernate type. Hibernate
will attempt to interpret the name of the return class of the property
getter using, in order, rules 2, 3, and 4. In certain cases you will
need the type attribute. For example, to
distinguish between Hibernate.DATE and
Hibernate.TIMESTAMP, or to specify a custom
type.

The access attribute allows you to control
how Hibernate accesses the property at runtime. By default, Hibernate
will call the property get/set pair. If you specify
access="field", Hibernate will bypass the get/set
pair and access the field directly using reflection. You can specify
your own strategy for property access by naming a class that
implements the interface
org.hibernate.property.PropertyAccessor.

A powerful feature is derived properties. These properties are
by definition read-only. The property value is computed at load time.
You declare the computation as an SQL expression. This then translates
to a SELECT clause subquery in the SQL query that
loads an instance:

You can reference the entity table by not declaring an alias on
a particular column. This would be customerId in
the given example. You can also use the nested
<formula> mapping element if you do not want
to use the attribute.

5.1.5. Embedded objects (aka components)

Embeddable objects (or components) are objects whose properties
are mapped to the same table as the owning entity's table. Components
can, in turn, declare their own properties, components or
collections

It is possible to declare an embedded component inside an entity
and even override its column mapping. Component classes have to be
annotated at the class level with the @Embeddable
annotation. It is possible to override the column mapping of an embedded
object for a particular entity using the @Embedded
and @AttributeOverride annotation in the associated
property:

An embeddable object inherits the access type of its owning entity
(note that you can override that using the @Access
annotation).

The Person entity has two component properties,
homeAddress and bornIn.
homeAddress property has not been annotated, but
Hibernate will guess that it is a persistent component by looking for
the @Embeddable annotation in the Address class. We
also override the mapping of a column name (to
bornCountryName) with the
@Embedded and @AttributeOverride
annotations for each mapped attribute of
Country. As you can see, Country
is also a nested component of Address,
again using auto-detection by Hibernate and JPA defaults. Overriding
columns of embedded objects of embedded objects is through dotted
expressions.

Hibernate Annotations supports something that is not explicitly
supported by the JPA specification. You can annotate a embedded object
with the @MappedSuperclass annotation to make the
superclass properties persistent (see
@MappedSuperclass for more informations).

You can also use association annotations in an embeddable object
(ie @OneToOne, @ManyToOne,
@OneToMany or @ManyToMany). To
override the association columns you can use
@AssociationOverride.

If you want to have the same embeddable object type twice in the
same entity, the column name defaulting will not work as several
embedded objects would share the same set of columns. In plain JPA, you
need to override at least one set of columns. Hibernate, however, allows
you to enhance the default naming mechanism through the
NamingStrategy interface. You can write a
strategy that prevent name clashing in such a situation.
DefaultComponentSafeNamingStrategy is an example
of this.

If a property of the embedded object points back to the owning
entity, annotate it with the @Parent annotation.
Hibernate will make sure this property is properly loaded with the
entity reference.

lazy (optional - defaults to
false): specifies that this component should be
fetched lazily when the instance variable is first accessed. It
requires build-time bytecode instrumentation.

optimistic-lock (optional - defaults to
true): specifies that updates to this component
either do or do not require acquisition of the optimistic lock. It
determines if a version increment should occur when this property
is dirty.

unique (optional - defaults to
false): specifies that a unique constraint
exists upon all mapped columns of the component.

The child <property> tags map properties
of the child class to table columns.

The <component> element allows a
<parent> subelement that maps a property of the
component class as a reference back to the containing entity.

The <dynamic-component> element allows a
Map to be mapped as a component, where the property
names refer to keys of the map. See Section 9.5, “Dynamic components” for more information. This feature is
not supported in annotations.

5.1.6. Inheritance strategy

Java is a language supporting polymorphism: a class can inherit
from another. Several strategies are possible to persist a class
hierarchy:

Single table per class hierarchy strategy: a single table
hosts all the instances of a class hierarchy

Joined subclass strategy: one table per class and subclass is
present and each table persist the properties specific to a given
subclass. The state of the entity is then stored in its
corresponding class table and all its superclasses

Table per class strategy: one table per concrete class and
subclass is present and each table persist the properties of the
class and its superclasses. The state of the entity is then stored
entirely in the dedicated table for its class.

5.1.6.1. Single table per class hierarchy strategy

With this approach the properties of all the subclasses in a
given mapped class hierarchy are stored in a single table.

Each subclass declares its own persistent properties and
subclasses. Version and id properties are assumed to be inherited from
the root class. Each subclass in a hierarchy must define a unique
discriminator value. If this is not specified, the fully qualified
Java class name is used.

5.1.6.1.1. Discriminator

Discriminators are required for polymorphic persistence using
the table-per-class-hierarchy mapping strategy. It declares a
discriminator column of the table. The discriminator column contains
marker values that tell the persistence layer what subclass to
instantiate for a particular row. Hibernate Core supports the
follwoing restricted set of types as discriminator column:
string, character,
integer, byte,
short, boolean,
yes_no, true_false.

Use the @DiscriminatorColumn to define
the discriminator column as well as the discriminator type.

Note

The enum DiscriminatorType used in
javax.persitence.DiscriminatorColumn only
contains the values STRING,
CHAR and INTEGER which
means that not all Hibernate supported types are available via
the @DiscriminatorColumn
annotation.

You can also use
@DiscriminatorFormula to express in SQL a
virtual discriminator column. This is particularly useful when the
discriminator value can be extracted from one or more columns of the
table. Both @DiscriminatorColumn and
@DiscriminatorFormula are to be set on the
root entity (once per persisted hierarchy).

@org.hibernate.annotations.DiscriminatorOptions
allows to optionally specify Hibernate specific discriminator
options which are not standardized in JPA. The available options are
force and insert. The
force attribute is useful if the table contains
rows with "extra" discriminator values that are not mapped to a
persistent class. This could for example occur when working with a
legacy database. If force is set to
true Hibernate will specify the allowed
discriminator values in the SELECT query, even
when retrieving all instances of the root class. The second option -
insert - tells Hibernate whether or not to
include the discriminator column in SQL INSERTs.
Usually the column should be part of the INSERT
statement, but if your discriminator column is also part of a mapped
composite identifier you have to set this option to
false.

Tip

There is also a
@org.hibernate.annotations.ForceDiscriminator
annotation which is deprecated since version 3.6. Use
@DiscriminatorOptions instead.

Finally, use @DiscriminatorValue on
each class of the hierarchy to specify the value stored in the
discriminator column for a given entity. If you do not set
@DiscriminatorValue on a class, the fully
qualified class name is used.

5.1.6.2. Joined subclass strategy

Each subclass can also be mapped to its own table. This is
called the table-per-subclass mapping strategy. An inherited state is
retrieved by joining with the table of the superclass. A discriminator
column is not required for this mapping strategy. Each subclass must,
however, declare a table column holding the object identifier. The
primary key of this table is also a foreign key to the superclass
table and described by the
@PrimaryKeyJoinColumns or the
<key> element.

Note

The table name still defaults to the non qualified class name.
Also if @PrimaryKeyJoinColumn is not set, the
primary key / foreign key columns are assumed to have the same names
as the primary key columns of the primary table of the
superclass.

5.1.6.3. Table per class strategy

A third option is to map only the concrete classes of an
inheritance hierarchy to tables. This is called the
table-per-concrete-class strategy. Each table defines all persistent
states of the class, including the inherited state. In Hibernate, it
is not necessary to explicitly map such inheritance hierarchies. You
can map each class as a separate entity root. However, if you wish use
polymorphic associations (e.g. an association to the superclass of
your hierarchy), you need to use the union subclass mapping.

5.1.6.4. Inherit properties from superclasses

This is sometimes useful to share common properties through a
technical or a business superclass without including it as a regular
mapped entity (ie no specific table for this entity). For that purpose
you can map them as @MappedSuperclass.

In database, this hierarchy will be represented as an
Order table having the id,
lastUpdate and lastUpdater
columns. The embedded superclass property mappings are copied into
their entity subclasses. Remember that the embeddable superclass is
not the root of the hierarchy though.

Note

Properties from superclasses not mapped as
@MappedSuperclass are ignored.

Note

The default access type (field or methods) is used, unless you
use the @Access annotation.

Note

The same notion can be applied to
@Embeddable objects to persist properties from
their superclasses. You also need to use
@MappedSuperclass to do that (this should not be
considered as a standard EJB3 feature though)

Note

It is allowed to mark a class as
@MappedSuperclass in the middle of the mapped
inheritance hierarchy.

Note

Any class in the hierarchy non annotated with
@MappedSuperclass nor @Entity
will be ignored.

You can override columns defined in entity superclasses at the
root entity level using the @AttributeOverride
annotation.

In this example, name will be in
MainCat. storyPart1 will be in
Cat1 and storyPart2 will be in
Cat2. Cat1 will be joined to
MainCat using the cat_id as a
foreign key, and Cat2 using id
(ie the same column name, the MainCat id column
has). Plus a unique constraint on storyPart2 has
been set.

There is also additional tuning accessible via the
@org.hibernate.annotations.Table
annotation:

fetch: If set to JOIN, the default,
Hibernate will use an inner join to retrieve a secondary table
defined by a class or its superclasses and an outer join for a
secondary table defined by a subclass. If set to
SELECT then Hibernate will use a sequential
select for a secondary table defined on a subclass, which will be
issued only if a row turns out to represent an instance of the
subclass. Inner joins will still be used to retrieve a secondary
defined by the class and its superclasses.

inverse: If true, Hibernate will not try
to insert or update the properties defined by this join. Default
to false.

optional: If enabled (the default),
Hibernate will insert a row only if the properties defined by this
join are non-null and will always use an outer join to retrieve
the properties.

foreignKey: defines the Foreign Key name
of a secondary table pointing back to the primary table.

schema (optional): overrides the schema
name specified by the root
<hibernate-mapping> element.

catalog (optional): overrides the
catalog name specified by the root
<hibernate-mapping> element.

fetch (optional - defaults to
join): if set to join, the
default, Hibernate will use an inner join to retrieve a
<join> defined by a class or its
superclasses. It will use an outer join for a
<join> defined by a subclass. If set to
select then Hibernate will use a sequential
select for a <join> defined on a
subclass. This will be issued only if a row represents an
instance of the subclass. Inner joins will still be used to
retrieve a <join> defined by the class
and its superclasses.

inverse (optional - defaults to
false): if enabled, Hibernate will not insert
or update the properties defined by this join.

optional (optional - defaults to
false): if enabled, Hibernate will insert a
row only if the properties defined by this join are non-null. It
will always use an outer join to retrieve the properties.

For example, address information for a person can be mapped to a
separate table while preserving value type semantics for all
properties:

This feature is often only useful for legacy data models. We
recommend fewer tables than classes and a fine-grained domain model.
However, it is useful for switching between inheritance mapping
strategies in a single hierarchy, as explained later.

5.1.7. Mapping one to one and one to many associations

To link one entity to an other, you need to map the association
property as a to one association. In the relational model, you can
either use a foreign key or an association table, or (a bit less common)
share the same primary key value between the two entities.

To mark an association, use either
@ManyToOne or
@OnetoOne.

@ManyToOne and @OneToOne
have a parameter named targetEntity which describes
the target entity name. You usually don't need this parameter since the
default value (the type of the property that stores the association) is
good in almost all cases. However this is useful when you want to use
interfaces as the return type instead of the regular entity.

Setting a value of the cascade attribute to any
meaningful value other than nothing will propagate certain operations to
the associated object. The meaningful values are divided into three
categories.

comma-separated combinations of operation names:
cascade="persist,merge,evict" or
cascade="all,delete-orphan". See Section 11.11, “Transitive persistence” for a full explanation. Note
that single valued many-to-one associations do not support orphan
delete.

By default, single point associations are eagerly fetched in JPA
2. You can mark it as lazily fetched by using
@ManyToOne(fetch=FetchType.LAZY) in which case
Hibernate will proxy the association and load it when the state of the
associated entity is reached. You can force Hibernate not to use a proxy
by using @LazyToOne(NO_PROXY). In this case, the
property is fetched lazily when the instance variable is first accessed.
This requires build-time bytecode instrumentation. lazy="false"
specifies that the association will always be eagerly fetched.

With the default JPA options, single-ended associations are loaded
with a subsequent select if set to LAZY, or a SQL
JOIN is used for EAGER associations. You can however
adjust the fetching strategy, ie how data is fetched by using
@Fetch. FetchMode can be
SELECT (a select is triggered when the association
needs to be loaded) or JOIN (use a SQL JOIN to load
the association while loading the owner entity). JOIN
overrides any lazy attribute (an association loaded through a
JOIN strategy cannot be lazy).

5.1.7.1. Using a foreign key or an association table

An ordinary association to another persistent class is declared
using a

@ManyToOne if several entities can
point to the the target entity

@OneToOne if only a single entity can
point to the the target entity

and a foreign key in one table is referencing the primary key
column(s) of the target table.

The @JoinColumn attribute is optional, the
default value(s) is the concatenation of the name of the relationship
in the owner side, _ (underscore), and the name of
the primary key column in the owned side. In this example
company_id because the property name is
company and the column id of Company is
id.

You can also map a to one association through an association
table. This association table described by the
@JoinTable annotation will contains a foreign key
referencing back the entity table (through
@JoinTable.joinColumns) and a a foreign key
referencing the target entity table (through
@JoinTable.inverseJoinColumns).

Note

You can use a SQL fragment to simulate a physical join column
using the @JoinColumnOrFormula /
@JoinColumnOrformulas annotations (just like
you can use a SQL fragment to simulate a property column via the
@Formula annotation).

You can mark an association as mandatory by using the
optional=false attribute. We recommend to use Bean
Validation's @NotNull annotation as a better
alternative however. As a consequence, the foreign key column(s) will
be marked as not nullable (if possible).

When Hibernate cannot resolve the association because the
expected associated element is not in database (wrong id on the
association column), an exception is raised. This might be
inconvenient for legacy and badly maintained schemas. You can ask
Hibernate to ignore such elements instead of raising an exception
using the @NotFound annotation.

Sometimes, you want to link one entity to an other not by the
target entity primary key but by a different unique key. You can
achieve that by referencing the unique key column(s) in
@JoinColumn.referenceColumnName.

update, insert (optional - defaults to
true): specifies that the mapped columns
should be included in SQL UPDATE and/or
INSERT statements. Setting both to
false allows a pure "derived" association
whose value is initialized from another property that maps to
the same column(s), or by a trigger or other application.

property-ref (optional): the name of a
property of the associated class that is joined to this foreign
key. If not specified, the primary key of the associated class
is used.

unique (optional): enables the DDL
generation of a unique constraint for the foreign-key column. By
allowing this to be the target of a
property-ref, you can make the association
multiplicity one-to-one.

not-null (optional): enables the DDL
generation of a nullability constraint for the foreign key
columns.

optimistic-lock (optional - defaults to
true): specifies that updates to this
property do or do not require acquisition of the optimistic
lock. In other words, it determines if a version increment
should occur when this property is dirty.

lazy (optional - defaults to
proxy): by default, single point associations
are proxied. lazy="no-proxy" specifies that
the property should be fetched lazily when the instance variable
is first accessed. This requires build-time bytecode
instrumentation. lazy="false" specifies that
the association will always be eagerly fetched.

not-found (optional - defaults to
exception): specifies how foreign keys that
reference missing rows will be handled.
ignore will treat a missing row as a null
association.

entity-name (optional): the entity name
of the associated class.

formula (optional): an SQL expression
that defines the value for a computed
foreign key.

Setting a value of the cascade attribute to
any meaningful value other than none will propagate
certain operations to the associated object. The meaningful values are
divided into three categories. First, basic operations, which include:
persist, merge, delete, save-update, evict, replicate, lock
and refresh; second, special values:
delete-orphan; and third,all
comma-separated combinations of operation names:
cascade="persist,merge,evict" or
cascade="all,delete-orphan". See Section 11.11, “Transitive persistence” for a full explanation. Note that
single valued, many-to-one and one-to-one, associations do not support
orphan delete.

Here is an example of a typical many-to-one
declaration:

<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

The property-ref attribute should only be
used for mapping legacy data where a foreign key refers to a unique
key of the associated table other than the primary key. This is a
complicated and confusing relational model. For example, if the
Product class had a unique serial number that is
not the primary key. The unique attribute controls
Hibernate's DDL generation with the SchemaExport tool.

5.1.7.2. Sharing the primary key with the associated entity

The second approach is to ensure an entity and its associated
entity share the same primary key. In this case the primary key column
is also a foreign key and there is no extra column. These associations
are always one to one.

Note

Many people got confused by these primary key based one to one
associations. They can only be lazily loaded if Hibernate knows that
the other side of the association is always present. To indicate to
Hibernate that it is the case, use
@OneToOne(optional=false).

class (optional - defaults to the
property type determined by reflection): the name of the
associated class.

cascade (optional): specifies which
operations should be cascaded from the parent object to the
associated object.

constrained (optional): specifies that
a foreign key constraint on the primary key of the mapped table
and references the table of the associated class. This option
affects the order in which save() and
delete() are cascaded, and determines whether
the association can be proxied. It is also used by the schema
export tool.

formula (optional): almost all
one-to-one associations map to the primary key of the owning
entity. If this is not the case, you can specify another column,
columns or expression to join on using an SQL formula. See
org.hibernate.test.onetooneformula for an
example.

lazy (optional - defaults to
proxy): by default, single point associations
are proxied. lazy="no-proxy" specifies that
the property should be fetched lazily when the instance variable
is first accessed. It requires build-time bytecode
instrumentation. lazy="false" specifies that
the association will always be eagerly fetched. Note
that if constrained="false", proxying is
impossible and Hibernate will eagerly fetch the
association.

entity-name (optional): the entity name
of the associated class.

Primary key associations do not need an extra table column. If
two rows are related by the association, then the two table rows share
the same primary key value. To relate two objects by a primary key
association, ensure that they are assigned the same identifier
value.

For a primary key association, add the following mappings to
Employee and Person
respectively:

<one-to-one name="person" class="Person"/>

<one-to-one name="employee" class="Employee" constrained="true"/>

Ensure that the primary keys of the related rows in the PERSON
and EMPLOYEE tables are equal. You use a special Hibernate identifier
generation strategy called foreign:

A newly saved instance of Person is assigned
the same primary key value as the Employee instance
referred with the employee property of that
Person.

5.1.8. Natural-id

Although we recommend the use of surrogate keys as primary keys,
you should try to identify natural keys for all entities. A natural key
is a property or combination of properties that is unique and non-null.
It is also immutable. Map the properties of the natural key as
@NaturalId or map them inside the
<natural-id> element. Hibernate will generate
the necessary unique key and nullability constraints and, as a result,
your mapping will be more self-documenting.

5.1.9. Any

There is one more type of property mapping. The
@Any mapping defines a polymorphic association to
classes from multiple tables. This type of mapping requires more than
one column. The first column contains the type of the associated entity.
The remaining columns contain the identifier. It is impossible to
specify a foreign key constraint for this kind of association. This is
not the usual way of mapping polymorphic associations and you should use
this only in special cases. For example, for audit logs, user session
data, etc.

The @Any annotation describes the column
holding the metadata information. To link the value of the metadata
information and an actual entity type, The
@AnyDef and @AnyDefs
annotations are used. The metaType attribute allows
the application to specify a custom type that maps database column
values to persistent classes that have identifier properties of the type
specified by idType. You must specify the mapping
from values of the metaType to class names.

optimistic-lock (optional - defaults to
true): specifies that updates to this property
either do or do not require acquisition of the optimistic lock. It
defines whether a version increment should occur if this property
is dirty.

5.1.10. Properties

The <properties> element allows the
definition of a named, logical grouping of the properties of a class.
The most important use of the construct is that it allows a combination
of properties to be the target of a property-ref. It
is also a convenient way to define a multi-column unique constraint. For
example:

name: the logical name of the grouping.
It is not an actual property name.

insert: do the mapped columns appear in
SQL INSERTs?

update: do the mapped columns appear in
SQL UPDATEs?

optimistic-lock (optional - defaults to
true): specifies that updates to these
properties either do or do not require acquisition of the
optimistic lock. It determines if a version increment should occur
when these properties are dirty.

unique (optional - defaults to
false): specifies that a unique constraint
exists upon all mapped columns of the component.

The use of this outside the context of mapping legacy data is not
recommended.

5.1.11. Some hbm.xml specificities

The hbm.xml structure has some specificities naturally not present
when using annotations, let's describe them briefly.

5.1.11.1. Doctype

All XML mappings should declare the doctype shown. The actual
DTD can be found at the URL above, in the directory
hibernate-x.x.x/src/org/hibernate , or in
hibernate3.jar. Hibernate will always look for the
DTD in its classpath first. If you experience lookups of the DTD using
an Internet connection, check the DTD declaration against the contents
of your classpath.

5.1.11.1.1. EntityResolver

Hibernate will first attempt to resolve DTDs in its classpath.
It does this is by registering a custom
org.xml.sax.EntityResolver implementation with
the SAXReader it uses to read in the xml files. This custom
EntityResolver recognizes two different systemId
namespaces:

a hibernate namespace is recognized
whenever the resolver encounters a systemId starting with
http://www.hibernate.org/dtd/. The resolver
attempts to resolve these entities via the classloader which
loaded the Hibernate classes.

a user namespace is recognized whenever
the resolver encounters a systemId using a
classpath:// URL protocol. The resolver will
attempt to resolve these entities via (1) the current thread
context classloader and (2) the classloader which loaded the
Hibernate classes.

Where types.xml is a resource in the
your.domain package and contains a custom typedef.

5.1.11.2. Hibernate-mapping

This element has several optional attributes. The
schema and catalog attributes
specify that tables referred to in this mapping belong to the named
schema and/or catalog. If they are specified, tablenames will be
qualified by the given schema and catalog names. If they are missing,
tablenames will be unqualified. The default-cascade
attribute specifies what cascade style should be assumed for
properties and collections that do not specify a
cascade attribute. By default, the
auto-import attribute allows you to use unqualified
class names in the query language.

auto-import (optional - defaults to
true): specifies whether we can use
unqualified class names of classes in this mapping in the query
language.

package (optional): specifies a package
prefix to use for unqualified class names in the mapping
document.

If you have two persistent classes with the same unqualified
name, you should set auto-import="false". An
exception will result if you attempt to assign two classes to the same
"imported" name.

The hibernate-mapping element allows you to
nest several persistent <class> mappings, as
shown above. It is, however, good practice (and expected by some
tools) to map only a single persistent class, or a single class
hierarchy, in one mapping file and name it after the persistent
superclass. For example, Cat.hbm.xml,
Dog.hbm.xml, or if using inheritance,
Animal.hbm.xml.

5.1.11.3. Key

The <key> element is featured a few
times within this guide. It appears anywhere the parent mapping
element defines a join to a new table that references the primary key
of the original table. It also defines the foreign key in the joined
table:

property-ref (optional): specifies that
the foreign key refers to columns that are not the primary key
of the original table. It is provided for legacy data.

not-null (optional): specifies that the
foreign key columns are not nullable. This is implied whenever
the foreign key is also part of the primary key.

update (optional): specifies that the
foreign key should never be updated. This is implied whenever
the foreign key is also part of the primary key.

unique (optional): specifies that the
foreign key should have a unique constraint. This is implied
whenever the foreign key is also the primary key.

For systems where delete performance is important, we recommend
that all keys should be defined
on-delete="cascade". Hibernate uses a
database-level ON CASCADE DELETE constraint,
instead of many individual DELETE statements. Be
aware that this feature bypasses Hibernate's usual optimistic locking
strategy for versioned data.

The not-null and update
attributes are useful when mapping a unidirectional one-to-many
association. If you map a unidirectional one-to-many association to a
non-nullable foreign key, you must declare the
key column using <key
not-null="true">.

5.1.11.4. Import

If your application has two persistent classes with the same
name, and you do not want to specify the fully qualified package name
in Hibernate queries, classes can be "imported" explicitly, rather
than relying upon auto-import="true". You can also
import classes and interfaces that are not explicitly mapped:

<import class="java.lang.Object" rename="Universe"/>

<import
class="ClassName"
rename="ShortName"
/>

class: the fully qualified class name
of any Java class.

rename (optional - defaults to the
unqualified class name): a name that can be used in the query
language.

Note

This feature is unique to hbm.xml and is not supported in
annotations.

5.1.11.5. Column and formula elements

Mapping elements which accept a column
attribute will alternatively accept a
<column> subelement. Likewise,
<formula> is an alternative to the
formula attribute. For example:

Most of the attributes on column provide a
means of tailoring the DDL during automatic schema generation. The
read and write attributes allow
you to specify custom SQL that Hibernate will use to access the
column's value. For more on this, see the discussion of column read and write
expressions.

The column and formula
elements can even be combined within the same property or association
mapping to express, for example, exotic join conditions.

5.2. Hibernate types

5.2.1. Entities and values

In relation to the persistence service, Java language-level
objects are classified into two groups:

An entity exists independently of any other
objects holding references to the entity. Contrast this with the usual
Java model, where an unreferenced object is garbage collected. Entities
must be explicitly saved and deleted. Saves and deletions, however, can
be cascaded from a parent entity to its children.
This is different from the ODMG model of object persistence by
reachability and corresponds more closely to how application objects are
usually used in large systems. Entities support circular and shared
references. They can also be versioned.

An entity's persistent state consists of references to other
entities and instances of value types. Values are
primitives: collections (not what is inside a collection), components
and certain immutable objects. Unlike entities, values in particular
collections and components, are persisted and
deleted by reachability. Since value objects and primitives are
persisted and deleted along with their containing entity, they cannot be
independently versioned. Values have no independent identity, so they
cannot be shared by two entities or collections.

Until now, we have been using the term "persistent class" to refer
to entities. We will continue to do that. Not all user-defined classes
with a persistent state, however, are entities. A
component is a user-defined class with value
semantics. A Java property of type java.lang.String
also has value semantics. Given this definition, all types (classes)
provided by the JDK have value type semantics in Java, while
user-defined types can be mapped with entity or value type semantics.
This decision is up to the application developer. An entity class in a
domain model will normally have shared references to a single instance
of that class, while composition or aggregation usually translates to a
value type.

We will revisit both concepts throughout this reference
guide.

The challenge is to map the Java type system, and the developers'
definition of entities and value types, to the SQL/database type system.
The bridge between both systems is provided by Hibernate. For entities,
<class>, <subclass>
and so on are used. For value types we use
<property>,
<component>etc., that usually have a
type attribute. The value of this attribute is the
name of a Hibernate mapping type. Hibernate
provides a range of mappings for standard JDK value types out of the
box. You can write your own mapping types and implement your own custom
conversion strategies.

With the exception of collections, all built-in Hibernate types
support null semantics.

5.2.2. Basic value types

The built-in basic mapping types can be
roughly categorized into the following:

Type mappings from Java primitives or wrapper classes to
appropriate (vendor-specific) SQL column types.
boolean, yes_no and
true_false are all alternative encodings for
a Java boolean or
java.lang.Boolean.

string

A type mapping from java.lang.String to
VARCHAR (or Oracle
VARCHAR2).

date, time, timestamp

Type mappings from java.util.Date and
its subclasses to SQL types DATE,
TIME and TIMESTAMP (or
equivalent).

Type mappings from java.util.Locale,
java.util.TimeZone and
java.util.Currency to
VARCHAR (or Oracle
VARCHAR2). Instances of
Locale and Currency are
mapped to their ISO codes. Instances of
TimeZone are mapped to their
ID.

class

A type mapping from java.lang.Class to
VARCHAR (or Oracle
VARCHAR2). A Class is
mapped to its fully qualified name.

binary

Maps byte arrays to an appropriate SQL binary type.

text

Maps long Java strings to a SQL LONGVARCHAR or
TEXT type.

image

Maps long byte arrays to a SQL LONGVARBINARY.

serializable

Maps serializable Java types to an appropriate SQL binary
type. You can also indicate the Hibernate type
serializable with the name of a serializable
Java class or interface that does not default to a basic
type.

clob, blob

Type mappings for the JDBC classes
java.sql.Clob and
java.sql.Blob. These types can be
inconvenient for some applications, since the blob or clob
object cannot be reused outside of a transaction. Driver support
is patchy and inconsistent.

materialized_clob

Maps long Java strings to a SQL CLOB
type. When read, the CLOB value is
immediately materialized into a Java string. Some drivers
require the CLOB value to be read within
a transaction. Once materialized, the Java string is
available outside of the transaction.

materialized_blob

Maps long Java byte arrays to a SQL BLOB
type. When read, the BLOB value is
immediately materialized into a byte array. Some drivers
require the BLOB value to be read within
a transaction. Once materialized, the byte array is
available outside of the transaction.

Type mappings for what are considered mutable Java types.
This is where Hibernate makes certain optimizations appropriate
only for immutable Java types, and the application treats the
object as immutable. For example, you should not call
Date.setTime() for an instance mapped as
imm_timestamp. To change the value of the
property, and have that change made persistent, the application
must assign a new, nonidentical, object to the property.

Unique identifiers of entities and collections can be of any basic
type except binary, blob and
clob. Composite identifiers are also allowed. See
below for more information.

5.2.3. Custom value types

It is relatively easy for developers to create their own value
types. For example, you might want to persist properties of type
java.lang.BigInteger to VARCHAR
columns. Hibernate does not provide a built-in type for this. Custom
types are not limited to mapping a property, or collection element, to a
single table column. So, for example, you might have a Java property
getName()/setName() of type
java.lang.String that is persisted to the columns
FIRST_NAME, INITIAL,
SURNAME.

To implement a custom type, implement either
org.hibernate.UserType or
org.hibernate.CompositeUserType and declare
properties using the fully qualified classname of the type. View
org.hibernate.test.DoubleStringType to see the kind
of things that are possible.

Notice the use of <column> tags to map a
property to multiple columns.

The CompositeUserType,
EnhancedUserType,
UserCollectionType, and
UserVersionType interfaces provide support for more
specialized uses.

You can even supply parameters to a UserType in
the mapping file. To do this, your UserType must
implement the
org.hibernate.usertype.ParameterizedType interface.
To supply parameters to your custom type, you can use the
<type> element in your mapping files.

The UserType can now retrieve the value for the
parameter named default from the
Properties object passed to it.

If you regularly use a certain UserType, it is
useful to define a shorter name for it. You can do this using the
<typedef> element. Typedefs assign a name to a
custom type, and can also contain a list of default parameter values if
the type is parameterized.

It is also possible to override the parameters supplied in a
typedef on a case-by-case basis by using type parameters on the property
mapping.

Even though Hibernate's rich range of built-in types and support
for components means you will rarely need to use a custom type, it is
considered good practice to use custom types for non-entity classes that
occur frequently in your application. For example, a
MonetaryAmount class is a good candidate for a
CompositeUserType, even though it could be mapped as
a component. One reason for this is abstraction. With a custom type,
your mapping documents would be protected against changes to the way
monetary values are represented.

5.3. Mapping a class more than once

It is possible to provide more than one mapping for a particular
persistent class. In this case, you must specify an entity
name to disambiguate between instances of the two mapped
entities. By default, the entity name is the same as the class name.
Hibernate lets you specify the entity name when working with persistent
objects, when writing queries, or when mapping associations to the named
entity.

Note

This feature is not supported in Annotations

5.4. SQL quoted identifiers

You can force Hibernate to quote an identifier in the generated SQL
by enclosing the table or column name in backticks in the mapping
document. Hibernate will use the correct quotation style for the SQL
Dialect. This is usually double quotes, but the SQL
Server uses brackets and MySQL uses backticks.

5.5. Generated properties

Generated properties are properties that have their values generated
by the database. Typically, Hibernate applications needed to
refresh objects that contain any properties for which
the database was generating values. Marking properties as generated,
however, lets the application delegate this responsibility to Hibernate.
When Hibernate issues an SQL INSERT or UPDATE for an entity that has
defined generated properties, it immediately issues a select afterwards to
retrieve the generated values.

never (the default): the given property value is
not generated within the database.

insert: the given property value is generated on
insert, but is not regenerated on subsequent updates. Properties like
created-date fall into this category. Even though version and timestamp properties can be
marked as generated, this option is not available.

always: the property value is generated both on
insert and on update.

To mark a property as generated, use
@Generated.

5.6. Column transformers: read and write expressions

Hibernate allows you to customize the SQL it uses to read and write
the values of columns mapped to simple properties. For
example, if your database provides a set of data encryption functions, you
can invoke them for individual columns like this:

Hibernate applies the custom expressions automatically whenever the
property is referenced in a query. This functionality is similar to a
derived-property formula with two differences:

The property is backed by one or more columns that are
exported as part of automatic schema generation.

The property is read-write, not read-only.

The write expression, if specified, must contain
exactly one '?' placeholder for the value.

5.7. Auxiliary database objects

Auxiliary database objects allow for the CREATE and DROP of
arbitrary database objects. In conjunction with Hibernate's schema
evolution tools, they have the ability to fully define a user schema
within the Hibernate mapping files. Although designed specifically for
creating and dropping things like triggers or stored procedures, any SQL
command that can be run via a
java.sql.Statement.execute() method is valid (for
example, ALTERs, INSERTS, etc.). There are essentially two modes for
defining auxiliary database objects:

The first mode is to explicitly list the CREATE and DROP commands in
the mapping file:

As an Object/Relational Mapping solution, Hibernate deals with both the Java and JDBC representations of
application data. An online catalog application, for example, most likely has Product
object with a number of attributes such as a sku, name, etc. For these
individual attributes, Hibernate must be able to read the values out of the database and write them back. This
'marshalling' is the function of a Hibernate type, which is an implementation of the
org.hibernate.type.Type interface. In addition, a
Hibernate type describes various aspects of behavior of the Java type such as "how is
equality checked?" or "how are values cloned?".

Important

A Hibernate type is neither a Java type nor a SQL datatype; it provides a information about both.

When you encounter the term type in regards to Hibernate be aware that usage might
refer to the Java type, the SQL/JDBC type or the Hibernate type.

6.1.1. Basic value types

The norm for basic value types is that they map a single database value (column) to a single,
non-aggregated Java type. Hibernate provides a number of built-in basic types, which we will present
in the following sections by the Java type. Mainly these follow the natural mappings recommended in the
JDBC specification. We will later cover how to override these mapping and how to provide and use
alternative type mappings.

6.1.1.1. java.lang.String

org.hibernate.type.StringType

Maps a string to the JDBC VARCHAR type. This is the standard mapping for a string if
no Hibernate type is specified.

6.1.1.28. java.io.Serializable

org.hibernate.type.SerializableType

Maps implementors of java.lang.Serializable to a JDBC VARBINARY

Unlike the other value types, there are multiple instances of this type. It
gets registered once under java.io.Serializable.
Additionally it gets registered under the specific
java.io.Serializable implementation class names.

6.1.2. Composite types

Note

The Java Persistence API calls these embedded types, while Hibernate traditionally called them
components. Just be aware that both terms are used and mean the same thing in the scope of
discussing Hibernate.

Components represent aggregations of values into a single Java type. For example, you might have
an Address class that aggregates street, city, state, etc information or a Name class that
aggregates the parts of a person's Name. In many ways a component looks exactly like an entity. They
are both (generally speaking) classes written specifically for the application. They both might have
references to other application-specific classes, as well as to collections and simple JDK types. As
discussed before, the only distinguishing factory is the fact that a component does not own its own
lifecycle nor does it define an identifier.

6.1.3. Collection types

Important

It is critical understand that we mean the collection itself, not its contents.
The contents of the collection can in turn be basic, component or entity types (though not
collections), but the collection itself is owned.

6.2. Entity types

The definition of entities is covered in detail in Chapter 4, Persistent Classes. For the purpose of
this discussion, it is enough to say that entities are (generally application-specific) classes which
correlate to rows in a table. Specifically they correlate to the row by means of a unique identifier.
Because of this unique identifier, entities exist independently and define their own lifecycle. As an example,
when we delete a Membership, both the User and
Group entities remain.

Note

This notion of entity independence can be modified by the application developer using the concept of
cascades. Cascades allow certain operations to continue (or "cascade") across an association from
one entity to another. Cascades are covered in detail in Chapter 8, Association Mappings.

6.3. Significance of type categories

Why do we spend so much time categorizing the various types of types? What is the significance of the
distinction?

The main categorization was between entity types and value types. To review we said that entities, by
nature of their unique identifier, exist independently of other objects whereas values do not. An
application cannot "delete" a Product sku; instead, the sku is removed when the Product itself is
deleted (obviously you can update the sku of that Product to null to make it
"go away", but even there the access is done through the Product).

Nor can you define an association to that Product sku. You can
define an association to Product based on its sku, assuming sku is unique, but that
is totally different.

TBC...

6.4. Custom types

Hibernate makes it relatively easy for developers to create their own value types. For
example, you might want to persist properties of type java.lang.BigInteger to
VARCHAR columns. Custom types are not limited to mapping values to a single table
column. So, for example, you might want to concatenate together FIRST_NAME,
INITIAL and SURNAME columns into a java.lang.String.

There are 3 approaches to developing a custom Hibernate type. As a means of illustrating the different
approaches, lets consider a use case where we need to compose a java.math.BigDecimal
and java.util.Currency together into a custom Money class.

6.4.1. Custom types using org.hibernate.type.Type

The first approach is to directly implement the org.hibernate.type.Type
interface (or one of its derivatives). Probably, you will be more interested in the more specific
org.hibernate.type.BasicType contract which would allow registration of
the type (see Section 6.5, “Type registry”). The benefit of this registration is that whenever
the metadata for a particular property does not specify the Hibernate type to use, Hibernate will
consult the registry for the exposed property type. In our example, the property type would be
Money, which is the key we would use to register our type in the registry:

Important

6.4.2. Custom types using org.hibernate.usertype.UserType

Note

Both org.hibernate.usertype.UserType and
org.hibernate.usertype.CompositeUserType were originally
added to isolate user code from internal changes to the org.hibernate.type.Type
interfaces.

The second approach is the use the org.hibernate.usertype.UserType
interface, which presents a somewhat simplified view of the org.hibernate.type.Type
interface. Using a org.hibernate.usertype.UserType, our
Money custom type would look as follows:

There is not much difference between the org.hibernate.type.Type example
and the org.hibernate.usertype.UserType example, but that is only because
of the snippets shown. If you choose the org.hibernate.type.Type approach
there are quite a few more methods you would need to implement as compared to the
org.hibernate.usertype.UserType.

6.4.3. Custom types using org.hibernate.usertype.CompositeUserType

The third and final approach is the use the org.hibernate.usertype.CompositeUserType
interface, which differs from org.hibernate.usertype.UserType in that it
gives us the ability to provide Hibernate the information to handle the composition within the
Money class (specifically the 2 attributes). This would give us the capability,
for example, to reference the amount attribute in an HQL query. Using a
org.hibernate.usertype.CompositeUserType, our
Money custom type would look as follows:

6.5. Type registry

Internally Hibernate uses a registry of basic types (see Section 6.1.1, “Basic value types”) when
it needs to resolve the specific org.hibernate.type.Type to use in certain
situations. It also provides a way for applications to add extra basic type registrations as well as
override the standard basic type registrations.

To register a new type or to override an existing type registration, applications would make use of the
registerTypeOverride method of the org.hibernate.cfg.Configuration
class when bootstrapping Hibernate. For example, lets say you want Hibernate to use your custom
SuperDuperStringType; during bootstrap you would call:

7.1. Persistent collections

Naturally Hibernate also allows to persist collections. These
persistent collections can contain almost any other Hibernate type,
including: basic types, custom types, components and references to other
entities. The distinction between value and reference semantics is in this
context very important. An object in a collection might be handled with
"value" semantics (its life cycle fully depends on the collection owner),
or it might be a reference to another entity with its own life cycle. In
the latter case, only the "link" between the two objects is considered to
be a state held by the collection.

As a requirement persistent collection-valued fields must be
declared as an interface type (see Example 7.2, “Collection mapping using @OneToMany and @JoinColumn”). The actual interface
might be java.util.Set,
java.util.Collection,
java.util.List, java.util.Map,
java.util.SortedSet,
java.util.SortedMap or anything you like ("anything you
like" means you will have to write an implementation of
org.hibernate.usertype.UserCollectionType).

Notice how in Example 7.2, “Collection mapping using @OneToMany and @JoinColumn” the instance variable
parts was initialized with an instance of
HashSet. This is the best way to initialize collection
valued properties of newly instantiated (non-persistent) instances. When
you make the instance persistent, by calling persist(),
Hibernate will actually replace the HashSet with an
instance of Hibernate's own implementation of Set. Be
aware of the following error:

The persistent collections injected by Hibernate behave like
HashMap, HashSet,
TreeMap, TreeSet or
ArrayList, depending on the interface type.

Collections instances have the usual behavior of value types. They
are automatically persisted when referenced by a persistent object and are
automatically deleted when unreferenced. If a collection is passed from
one persistent object to another, its elements might be moved from one
table to another. Two entities cannot share a reference to the same
collection instance. Due to the underlying relational model,
collection-valued properties do not support null value semantics.
Hibernate does not distinguish between a null collection reference and an
empty collection.

Note

7.2. How to map collections

Using annotations you can map Collections,
Lists, Maps and
Sets of associated entities using @OneToMany and
@ManyToMany. For collections of a basic or embeddable type use
@ElementCollection. In the simplest case a collection mapping looks like
this:

Without describing any physical mapping (no
@JoinColumn or @JoinTable),
a unidirectional one to many with join table is used. The table name is
the concatenation of the owner table name, _, and the other side table
name. The foreign key name(s) referencing the owner table is the
concatenation of the owner table, _, and the owner primary key column(s)
name. The foreign key name(s) referencing the other side is the
concatenation of the owner property name, _, and the other side primary
key column(s) name. A unique constraint is added to the foreign key
referencing the other side table to reflect the one to many.

Lets have a look now how collections are mapped using Hibernate
mapping files. In this case the first step is to chose the right mapping
element. It depends on the type of interface. For example, a
<set> element is used for mapping properties of
type Set.

In Example 7.4, “Mapping a Set using <set>” a
one-to-many association links the
Product and Part entities. This
association requires the existence of a foreign key column and possibly an
index column to the Part table. This mapping loses
certain semantics of normal Java collections:

An instance of the contained entity class cannot belong to more
than one instance of the collection.

An instance of the contained entity class cannot appear at more
than one value of the collection index.

Looking closer at the used <one-to-many>
tag we see that it has the following options.

not-found (optional - defaults to
exception): specifies how cached identifiers
that reference missing rows will be handled.
ignore will treat a missing row as a null
association.

entity-name (optional): the entity name
of the associated class, as an alternative to
class.

The <one-to-many> element does not need to
declare any columns. Nor is it necessary to specify the
table name anywhere.

Warning

If the foreign key column of a
<one-to-many> association is declared
NOT NULL, you must declare the
<key> mapping
not-null="true" or use a bidirectional
association with the collection mapping marked
inverse="true". See Section 7.3.2, “Bidirectional associations”.

table (optional - defaults to property
name): the name of the collection table. It is not used for
one-to-many associations.

schema (optional): the name of a table
schema to override the schema declared on the root element

lazy (optional - defaults to
true): disables lazy fetching and specifies
that the association is always eagerly fetched. It can also be
used to enable "extra-lazy" fetching where most operations do not
initialize the collection. This is suitable for large
collections.

inverse (optional - defaults to
false): marks this collection as the "inverse"
end of a bidirectional association.

sort (optional): specifies a sorted
collection with natural sort order or a given
comparator class.

order-by (optional): specifies a table
column or columns that define the iteration order of the
Map, Set or bag, together
with an optional asc or
desc.

where (optional): specifies an arbitrary
SQL WHERE condition that is used when
retrieving or removing the collection. This is useful if the
collection needs to contain only a subset of the available
data.

optimistic-lock (optional - defaults to
true): specifies that changes to the state of
the collection results in increments of the owning entity's
version. For one-to-many associations you may want to disable this
setting.

mutable (optional - defaults to
true): a value of false
specifies that the elements of the collection never change. This
allows for minor performance optimization in some cases.

After exploring the basic mapping of collections in the preceding
paragraphs we will now focus details like physical mapping considerations,
indexed collections and collections of value types.

7.2.1. Collection foreign keys

On the database level collection instances are distinguished by
the foreign key of the entity that owns the collection. This foreign key
is referred to as the collection key column, or
columns, of the collection table. The collection key column is mapped by
the @JoinColumn annotation respectively the
<key> XML element.

There can be a nullability constraint on the foreign key column.
For most collections, this is implied. For unidirectional one-to-many
associations, the foreign key column is nullable by default, so you may
need to specify

@JoinColumn(nullable=false)

or

<key column="productSerialNumber" not-null="true"/>

The foreign key constraint can use ON DELETE
CASCADE. In XML this can be expressed via:

<key column="productSerialNumber" on-delete="cascade"/>

In annotations the Hibernate specific annotation @OnDelete has to
be used.

7.2.2. Indexed collections

In the following paragraphs we have a closer look at the indexed
collections List and Map
how the their index can be mapped in Hibernate.

7.2.2.1. Lists

Lists can be mapped in two different ways:

as ordered lists, where the order is not materialized in the
database

as indexed lists, where the order is materialized in the
database

To order lists in memory, add
@javax.persistence.OrderBy to your property. This
annotation takes as parameter a list of comma separated properties (of
the target entity) and orders the collection accordingly (eg
firstname asc, age desc, weight asc nulls last), if the string
is empty, the collection will be ordered by the primary key of the target
entity.

To store the index value in a dedicated column, use the
@javax.persistence.OrderColumn annotation on
your property. This annotations describes the column name and
attributes of the column keeping the index value. This column is
hosted on the table containing the association foreign key. If the
column name is not specified, the default is the name of the
referencing property, followed by underscore, followed by
ORDER (in the following example, it would be
orders_ORDER).

Note

We recommend you to convert the legacy @org.hibernate.annotations.IndexColumn
usages to the JPA standard @javax.persistence.OrderColumn.

If you are leveraging a custom list index base (maybe currently using the
org.hibernate.annotations.IndexColumn.literal attribute), you can
specify this using the @org.hibernate.annotations.ListIndexBase in conjunction
with @javax.persistence.OrderColumn. The default base is 0 like in Java.

Looking again at the Hibernate mapping file equivalent, the
index of an array or list is always of type integer
and is mapped using the <list-index> element.
The mapped column contains sequential integers that are numbered from
zero by default.

column_name (required): the name of
the column holding the collection index values.

base (optional - defaults to
0): the value of the index column that
corresponds to the first element of the list or array.

If your table does not have an index column, and you still wish
to use List as the property type, you can map the
property as a Hibernate <bag>. A bag does
not retain its order when it is retrieved from the database, but it
can be optionally sorted or ordered.

7.2.2.2. Maps

The question with Maps is where the key
value is stored. There are several options. Maps can borrow their keys
from one of the associated entity properties or have dedicated columns
to store an explicit key.

To use one of the target entity property as a key of the map,
use @MapKey(name="myProperty"), where
myProperty is a property name in the target entity.
When using @MapKey without the name attribute, the
target entity primary key is used. The map key uses the same column as
the property pointed out. There is no additional column defined to
hold the map key, because the map key represent a target property. Be
aware that once loaded, the key is no longer kept in sync with the
property. In other words, if you change the property value, the key
will not change automatically in your Java model.

Note

We recommend you to migrate from
@org.hibernate.annotations.MapKey /
@org.hibernate.annotation.MapKeyManyToMany to
the new standard approach described above

Using Hibernate mapping files there exists equivalent concepts
to the descibed annotations. You have to use
<map-key>,
<map-key-many-to-many> and
<composite-map-key>.
<map-key> is used for any basic type,
<map-key-many-to-many> for an entity
reference and <composite-map-key> for a
composite type.

The collection table holding the collection data is set using the
@CollectionTable annotation. If omitted the
collection table name defaults to the concatenation of the name of the
containing entity and the name of the collection attribute, separated by
an underscore. In our example, it would be
User_nicknames.

The column holding the basic type is set using the
@Column annotation. If omitted, the column name
defaults to the property name: in our example, it would be
nicknames.

But you are not limited to basic types, the collection type can be
any embeddable object. To override the columns of the embeddable object
in the collection table, use the
@AttributeOverride annotation.

Note

in @AttributeOverride, you must use the
value. prefix to override properties of the
embeddable object used in the map value and the
key. prefix to override properties of the
embeddable object used in the map key.

column (optional): the name of the
column holding the collection element values.

formula (optional): an SQL formula used
to evaluate the element.

type (required): the type of the
collection element.

7.3. Advanced collection mappings

7.3.1. Sorted collections

Hibernate supports collections implementing
java.util.SortedMap and
java.util.SortedSet. With annotations you declare a
sort comparator using @Sort. You chose between the
comparator types unsorted, natural or custom. If you want to use your
own comparator implementation, you'll also have to specify the
implementation class using the comparator attribute.
Note that you need to use either a SortedSet or a
SortedMap interface.

Tip

If you want the database itself to order the collection elements,
use the order-by attribute of set,
bag or map mappings. This solution
is implemented using LinkedHashSet or
LinkedHashMap and performs the ordering in the SQL
query and not in the memory.

Troop has a bidirectional one to many
relationship with Soldier through the
troop property. You don't have to (must not) define
any physical mapping in the mappedBy side.

To map a bidirectional one to many, with the one-to-many side as
the owning side, you have to remove the mappedBy
element and set the many to one @JoinColumn as
insertable and updatable to false. This solution is not optimized and
will produce additional UPDATE statements.

Example 7.22. Bidirectional association with one to many side as
owner

How does the mappping of a bidirectional mapping look like in
Hibernate mapping xml? There you define a bidirectional one-to-many
association by mapping a one-to-many association to the same table
column(s) as a many-to-one association and declaring the many-valued end
inverse="true".

Mapping one end of an association with
inverse="true" does not affect the operation of
cascades as these are orthogonal concepts.

A many-to-many association is defined logically using the
@ManyToMany annotation. You also have to describe the
association table and the join conditions using the
@JoinTable annotation. If the association is
bidirectional, one side has to be the owner and one side has to be the
inverse end (ie. it will be ignored when updating the relationship
values in the association table):

In this example @JoinTable defines a
name, an array of join columns, and an array of
inverse join columns. The latter ones are the columns of the association
table which refer to the Employee primary key
(the "other side"). As seen previously, the other side don't have to
(must not) describe the physical mapping: a simple
mappedBy argument containing the owner side property
name bind the two.

As any other annotations, most values are guessed in a many to
many relationship. Without describing any physical mapping in a
unidirectional many to many the following rules applied. The table name
is the concatenation of the owner table name, _ and the
other side table name. The foreign key name(s) referencing the owner
table is the concatenation of the owner table name, _
and the owner primary key column(s). The foreign key name(s) referencing
the other side is the concatenation of the owner property name,
_, and the other side primary key column(s). These are
the same rules used for a unidirectional one to many
relationship.

A Store_City is used as the join table. The
Store_id column is a foreign key to the
Store table. The implantedIn_id
column is a foreign key to the City table.

Without describing any physical mapping in a bidirectional many to
many the following rules applied. The table name is the concatenation of
the owner table name, _ and the other side table name.
The foreign key name(s) referencing the owner table is the concatenation
of the other side property name, _, and the owner
primary key column(s). The foreign key name(s) referencing the other
side is the concatenation of the owner property name,
_, and the other side primary key column(s). These are
the same rules used for a unidirectional one to many
relationship.

Changes made only to the inverse end of the association are
not persisted. This means that Hibernate has two
representations in memory for every bidirectional association: one link
from A to B and another link from B to A. This is easier to understand
if you think about the Java object model and how a many-to-many
relationship in Javais created:

Example 7.28. Effect of inverse vs. non-inverse side of many to many
associations

category.getItems().add(item); // The category now "knows" about the relationship
item.getCategories().add(category); // The item now "knows" about the relationship
session.persist(item); // The relationship won't be saved!
session.persist(category); // The relationship will be saved

The non-inverse side is used to save the in-memory representation
to the database.

7.3.3. Bidirectional associations with indexed collections

There are some additional considerations for bidirectional
mappings with indexed collections (where one end is represented as a
<list> or <map>) when
using Hibernate mapping files. If there is a property of the child class
that maps to the index column you can use
inverse="true" on the collection mapping:

If there is no such property on the child class, the association
cannot be considered truly bidirectional. That is, there is information
available at one end of the association that is not available at the
other end. In this case, you cannot map the collection
inverse="true". Instead, you could use the following
mapping:

A second approach is to remodel the association as an entity
class. This is the most common approach. A final alternative is to use
composite elements, which will be discussed later.

7.3.5. Using an <idbag>

The majority of the many-to-many associations and collections of
values shown previously all map to tables with composite keys, even
though it has been suggested that entities should have synthetic
identifiers (surrogate keys). A pure association table does not seem to
benefit much from a surrogate key, although a collection of composite
values might. For this reason Hibernate provides a
feature that allows you to map many-to-many associations and collections
of values to a table with a surrogate key.

The <idbag> element lets you map a
List (or Collection) with bag
semantics. For example:

An <idbag> has a synthetic id generator,
just like an entity class. A different surrogate key is assigned to each
collection row. Hibernate does not, however, provide any mechanism for
discovering the surrogate key value of a particular row.

The update performance of an <idbag>
supersedes a regular <bag>. Hibernate can
locate individual rows efficiently and update or delete them
individually, similar to a list, map or set.

In the current implementation, the native
identifier generation strategy is not supported for
<idbag> collection identifiers.

For more examples and a complete explanation of a parent/child
relationship mapping, see Chapter 23, Example: Parent/Child for more
information. Even more complex association mappings are covered in the
next chapter.

8.1. Introduction

Association mappings are often the most difficult thing to implement correctly. In
this section we examine some canonical cases one by one, starting
with unidirectional mappings and then bidirectional cases.
We will use Person and Address in all
the examples.

Associations will be classified by multiplicity and whether or not they map to an intervening
join table.

Nullable foreign keys are not considered to be good practice in traditional data
modelling, so our examples do not use nullable foreign keys. This is not a
requirement of Hibernate, and the mappings will work if you drop the
nullability constraints.

8.2. Unidirectional associations

8.2.1. Many-to-one

A unidirectional many-to-one association is the most
common kind of unidirectional association.

If you use a List, or other indexed collection,
set the key column of the foreign key to not null.
Hibernate will manage the association from the collections side to maintain the index
of each element, making the other side virtually inverse by setting
update="false" and insert="false":

If the underlying foreign key column is NOT NULL, it
is important that you define not-null="true" on the
<key> element of the collection mapping.
Do not only
declare not-null="true" on a possible nested
<column> element, but on the <key>
element.

8.6. More complex association mappings

More complex association joins are extremely rare.
Hibernate handles more complex situations by using
SQL fragments embedded in the mapping document. For example, if a table
with historical account information data defines
accountNumber, effectiveEndDate
and effectiveStartDatecolumns, it would be mapped as follows:

In a more complex example, imagine that the association between
Employee and Organization is maintained
in an Employment table full of historical employment data.
An association to the employee's most recent employer,
the one with the most recent startDate, could be mapped in the following way:

Chapter 9. Component Mapping

The notion of a component is re-used in several different contexts and purposes
throughout Hibernate.

9.1. Dependent objects

A component is a contained object that is persisted as a value type and not an entity
reference. The term "component" refers to the object-oriented notion of composition
and not to architecture-level components. For example, you can model a person like this:

The person table would have the columns pid,
birthday,
initial,
first and
last.

Like value types, components do not support shared references. In other words, two
persons could have the same name, but the two person objects would contain two independent
name objects that were only "the same" by value. The null value semantics of a component are
ad hoc. When reloading the containing object, Hibernate will assume
that if all component columns are null, then the entire component is null. This is suitable for most purposes.

The properties of a component can be of any Hibernate type (collections, many-to-one
associations, other components, etc). Nested components should not
be considered an exotic usage. Hibernate is intended to support a fine-grained
object model.

The <component> element allows a <parent>
subelement that maps a property of the component class as a reference back to the
containing entity.

Important

If you define a Set of composite elements, it is
important to implement equals() and
hashCode() correctly.

Composite elements can contain components but not collections. If your
composite element contains
components, use the <nested-composite-element>
tag. This case is a collection of components which
themselves have components. You may want to consider if
a one-to-many association is more appropriate. Remodel the
composite element as an entity, but be aware that even though the Java model
is the same, the relational model and persistence semantics are still
slightly different.

A composite element mapping does not support null-able properties
if you are using a <set>. There is no separate primary key column
in the composite element table. Hibernate
uses each column's value to identify a record when deleting objects,
which is not possible with null values. You have to either use only
not-null properties in a composite-element or choose a
<list>, <map>,
<bag> or <idbag>.

A special case of a composite element is a composite element with a nested
<many-to-one> element. This mapping allows
you to map extra columns of a many-to-many association table to the
composite element class. The following is a many-to-many association
from Order to Item, where
purchaseDate, price and
quantity are properties of the association:

There cannot be a reference to the purchase on the other side for
bidirectional association navigation. Components are value types and
do not allow shared references. A single Purchase can be in the
set of an Order, but it cannot be referenced by the Item
at the same time.

Composite elements can appear in queries using the same syntax as
associations to other entities.

9.3. Components as Map indices

The <composite-map-key> element allows you to map a
component class as the key of a Map. Ensure that you override
hashCode() and equals() correctly on
the component class.

9.4. Components as composite identifiers

You can use a component as an identifier of an entity class. Your component
class must satisfy certain requirements:

It must implement java.io.Serializable.

It must re-implement equals() and
hashCode() consistently with the database's
notion of composite key equality.

Note

In Hibernate, although the second requirement is not an absolutely hard
requirement of Hibernate, it is recommended.

You cannot use an IdentifierGenerator to generate composite keys.
Instead the application must assign its own identifiers.

Use the <composite-id> tag, with nested
<key-property> elements, in place of the usual
<id> declaration. For example, the
OrderLine class has a primary key that depends upon
the (composite) primary key of Order.

The semantics of a <dynamic-component> mapping are identical
to <component>. The advantage of this kind of mapping is
the ability to determine the actual properties of the bean at deployment time just
by editing the mapping document. Runtime manipulation of the mapping document is
also possible, using a DOM parser. You can also access, and change, Hibernate's
configuration-time metamodel via the Configuration object.

10.1. The three strategies

In addition, Hibernate supports a fourth, slightly different kind of
polymorphism:

implicit polymorphism

It is possible to use different mapping strategies for different
branches of the same inheritance hierarchy. You can then make use of implicit
polymorphism to achieve polymorphism across the whole hierarchy. However,
Hibernate does not support mixing <subclass>,
<joined-subclass> and
<union-subclass> mappings under the same root
<class> element. It is possible to mix together
the table per hierarchy and table per subclass strategies under the
the same <class> element, by combining the
<subclass> and <join>
elements (see below for an example).

It is possible to define subclass, union-subclass,
and joined-subclass mappings in separate mapping documents directly beneath
hibernate-mapping. This allows you to extend a class hierarchy by adding
a new mapping file. You must specify an extends attribute in the subclass mapping,
naming a previously mapped superclass. Previously this feature made the ordering of the mapping
documents important. Since Hibernate, the ordering of mapping files is irrelevant when using the
extends keyword. The ordering inside a single mapping file still needs to be defined as superclasses
before subclasses.

Four tables are required. The three subclass tables have primary
key associations to the superclass table so the relational model
is actually a one-to-one association.

10.1.3. Table per subclass: using a discriminator

Hibernate's implementation of table per subclass
does not require a discriminator column. Other object/relational mappers use a
different implementation of table per subclass that requires a type
discriminator column in the superclass table. The approach taken by
Hibernate is much more difficult to implement, but arguably more
correct from a relational point of view. If you want to use
a discriminator column with the table per subclass strategy, you
can combine the use of <subclass> and
<join>, as follows:

Three tables are involved for the subclasses. Each table defines columns for
all properties of the class, including inherited properties.

The limitation of this approach is that if a property is mapped on the
superclass, the column name must be the same on all subclass tables.
The identity generator strategy is not allowed in union subclass inheritance.
The primary key seed has to be shared across all unioned subclasses
of a hierarchy.

If your superclass is abstract, map it with abstract="true".
If it is not abstract, an additional table (it defaults to
PAYMENT in the example above), is needed to hold instances
of the superclass.

Notice that the Payment interface
is not mentioned explicitly. Also notice that properties of Payment are
mapped in each of the subclasses. If you want to avoid duplication, consider
using XML entities
(for example, [ <!ENTITY allproperties SYSTEM "allproperties.xml"> ]
in the DOCTYPE declaration and
%allproperties; in the mapping).

The disadvantage of this approach is that Hibernate does not generate SQL
UNIONs when performing polymorphic queries.

For this mapping strategy, a polymorphic association to Payment
is usually mapped using <any>.

10.1.7. Mixing implicit polymorphism with other inheritance mappings

Since the subclasses
are each mapped in their own <class> element, and since
Payment is just an interface), each of the subclasses could
easily be part of another inheritance hierarchy. You can still use polymorphic
queries against the Payment interface.

Once again, Payment is not mentioned explicitly. If we
execute a query against the Payment interface, for
example from Payment, Hibernate
automatically returns instances of CreditCardPayment
(and its subclasses, since they also implement Payment),
CashPayment and ChequePayment, but
not instances of NonelectronicTransaction.

10.2. Limitations

There are limitations to the "implicit polymorphism" approach to
the table per concrete-class mapping strategy. There are somewhat less
restrictive limitations to <union-subclass>
mappings.

The following table shows the limitations of table per concrete-class
mappings, and of implicit polymorphism, in Hibernate.

Hibernate is a full object/relational mapping solution that not only
shields the developer from the details of the underlying database management
system, but also offers state management of objects.
This is, contrary to the management of SQL statements in
common JDBC/SQL persistence layers, a natural object-oriented view of
persistence in Java applications.

In other words, Hibernate application developers should always think
about the state of their objects, and not necessarily
about the execution of SQL statements. This part is taken care of by
Hibernate and is only relevant for the application developer when tuning the
performance of the system.

11.1. Hibernate object states

Hibernate defines and supports the following object states:

Transient - an object is transient if it
has just been instantiated using the new operator,
and it is not associated with a Hibernate Session.
It has no persistent representation in the database and no identifier
value has been assigned. Transient instances will be destroyed by the
garbage collector if the application does not hold a reference
anymore. Use the Hibernate Session to make an
object persistent (and let Hibernate take care of the SQL statements
that need to be executed for this transition).

Persistent - a persistent instance has a
representation in the database and an identifier value. It might just
have been saved or loaded, however, it is by definition in the scope
of a Session. Hibernate will detect any changes
made to an object in persistent state and synchronize the state with
the database when the unit of work completes. Developers do not
execute manual UPDATE statements, or
DELETE statements when an object should be made
transient.

Detached - a detached instance is an object
that has been persistent, but its Session has been
closed. The reference to the object is still valid, of course, and the
detached instance might even be modified in this state. A detached
instance can be reattached to a new Session at a
later point in time, making it (and all the modifications) persistent
again. This feature enables a programming model for long running units
of work that require user think-time. We call them
application transactions, i.e., a unit of work
from the point of view of the user.

We will now discuss the states and state transitions (and the
Hibernate methods that trigger a transition) in more detail.

11.2. Making objects persistent

Newly instantiated instances of a persistent class are considered
transient by Hibernate. We can make a transient
instance persistent by associating it with a
session:

If Cat has a generated identifier, the identifier
is generated and assigned to the cat when
save() is called. If Cat has an
assigned identifier, or a composite key, the identifier
should be assigned to the cat instance before calling
save(). You can also use persist()
instead of save(), with the semantics defined in the
EJB3 early draft.

persist() makes a transient instance
persistent. However, it does not guarantee that the identifier value
will be assigned to the persistent instance immediately, the
assignment might happen at flush time. persist()
also guarantees that it will not execute an INSERT
statement if it is called outside of transaction boundaries. This is
useful in long-running conversations with an extended
Session/persistence context.

save() does guarantee to return an
identifier. If an INSERT has to be executed to get the identifier (
e.g. "identity" generator, not "sequence"), this INSERT happens
immediately, no matter if you are inside or outside of a transaction.
This is problematic in a long-running conversation with an extended
Session/persistence context.

Alternatively, you can assign the identifier using an overloaded
version of save().

If the object you make persistent has associated objects (e.g. the
kittens collection in the previous example), these
objects can be made persistent in any order you like unless you have a
NOT NULL constraint upon a foreign key column. There is
never a risk of violating foreign key constraints. However, you might
violate a NOT NULL constraint if you
save() the objects in the wrong order.

Usually you do not bother with this detail, as you will normally use
Hibernate's transitive persistence feature to save
the associated objects automatically. Then, even NOT
NULL constraint violations do not occur - Hibernate will take
care of everything. Transitive persistence is discussed later in this
chapter.

11.3. Loading an object

The load() methods of Session
provide a way of retrieving a persistent instance if you know its
identifier. load() takes a class object and loads the
state into a newly instantiated instance of that class in a persistent
state.

Be aware that load() will throw an unrecoverable
exception if there is no matching database row. If the class is mapped
with a proxy, load() just returns an uninitialized
proxy and does not actually hit the database until you invoke a method of
the proxy. This is useful if you wish to create an association to an
object without actually loading it from the database. It also allows
multiple instances to be loaded as a batch if
batch-size is defined for the class mapping.

If you are not certain that a matching row exists, you should use
the get() method which hits the database immediately
and returns null if there is no matching row.

How much does Hibernate load from the database and how many SQL
SELECTs will it use? This depends on the
fetching strategy. This is explained in Section 20.1, “Fetching strategies”.

11.4. Querying

If you do not know the identifiers of the objects you are looking
for, you need a query. Hibernate supports an easy-to-use but powerful
object oriented query language (HQL). For programmatic query creation,
Hibernate supports a sophisticated Criteria and Example query feature (QBC
and QBE). You can also express your query in the native SQL of your
database, with optional support from Hibernate for result set conversion
into objects.

11.4.1. Executing queries

HQL and native SQL queries are represented with an instance of
org.hibernate.Query. This interface offers methods
for parameter binding, result set handling, and for the execution of the
actual query. You always obtain a Query using the
current Session:

A query is usually executed by invoking list().
The result of the query will be loaded completely into a collection in
memory. Entity instances retrieved by a query are in a persistent state.
The uniqueResult() method offers a shortcut if you
know your query will only return a single object. Queries that make use
of eager fetching of collections usually return duplicates of the root
objects, but with their collections initialized. You can filter these
duplicates through a Set.

11.4.1.1. Iterating results

Occasionally, you might be able to achieve better performance by
executing the query using the iterate() method.
This will usually be the case if you expect that the actual entity
instances returned by the query will already be in the session or
second-level cache. If they are not already cached,
iterate() will be slower than
list() and might require many database hits for a
simple query, usually 1 for the initial select
which only returns identifiers, and n additional
selects to initialize the actual instances.

11.4.1.3. Scalar results

Queries can specify a property of a class in the
select clause. They can even call SQL aggregate
functions. Properties or aggregates are considered "scalar" results
and not entities in persistent state.

11.4.1.4. Bind parameters

Methods on Query are provided for binding
values to named parameters or JDBC-style ?
parameters. Contrary to JDBC, Hibernate numbers parameters
from zero. Named parameters are identifiers of the form
:name in the query string. The advantages of named
parameters are as follows:

named parameters are insensitive to the order they occur in
the query string

Note that an open database connection and cursor is required for
this functionality. Use
setMaxResult()/setFirstResult()
if you need offline pagination functionality.

11.4.1.7. Externalizing named queries

Queries can also be configured as so called named queries using
annotations or Hibernate mapping documents.
@NamedQuery and @NamedQueries
can be defined at the class level as seen in Example 11.1, “Defining a named query using
@NamedQuery” . However their
definitions are global to the session factory/entity manager factory
scope. A named query is defined by its name and the actual query
string.

The actual program code is independent of the query language
that is used. You can also define native SQL queries in metadata, or
migrate existing queries to Hibernate by placing them in mapping
files.

Also note that a query declaration inside a
<hibernate-mapping> element requires a global
unique name for the query, while a query declaration inside a
<class> element is made unique automatically
by prepending the fully qualified name of the class. For example
eg.Cat.ByNameAndMaximumWeight.

11.4.2. Filtering collections

A collection filter is a special type of
query that can be applied to a persistent collection or array. The query
string can refer to this, meaning the current
collection element.

The returned collection is considered a bag that is a copy of the
given collection. The original collection is not modified. This is
contrary to the implication of the name "filter", but consistent with
expected behavior.

Observe that filters do not require a from
clause, although they can have one if required. Filters are not limited
to returning the collection elements themselves.