Hibernate Annotations
Reference Guide
Version: 3.2.0 CR1
Table of Contents
Preface ............................................................................................................................................iv
1. Setting up an annotations project ................................................................................................1
1.1. Requirements .....................................................................................................................1
1.2. Configuration .....................................................................................................................1
2. Entity Beans ................................................................................................................................ 3
2.1. Intro ..................................................................................................................................3
2.2. Mapping with EJB3 Annotations .........................................................................................3
2.2.1. Declaring an entity bean ..........................................................................................3
2.2.1.1. Defining the table .........................................................................................3
2.2.1.2. Versioning for optimistic locking ...................................................................4
2.2.2. Mapping simple properties .......................................................................................4
2.2.2.1. Declaring basic property mappings ................................................................ 4
2.2.2.2. Declaring column attributes ........................................................................... 5
2.2.2.3. Embedded objects (aka components) ..............................................................6
2.2.2.4. Non-annotated property defaults .................................................................... 8
2.2.. Mapping identifier properties .....................................................................................8
2.2.4. Mapping inheritance .............................................................................................. 11
2.2.4.1. Table per class ............................................................................................ 11
2.2.4.2. Single table per class hierarchy .................................................................... 11
2.2.4.3. Joined subclasses ........................................................................................ 12
2.2.4.4. Inherit properties from superclasses ............................................................. 12
2.2.5. Mapping entity bean associations/relationships ........................................................ 14
2.2.5.1. One-to-one ................................................................................................. 14
2.2.5.2. Many-to-one ............................................................................................... 15
2.2.5.3. Collections ................................................................................................. 16
2.2.5.4. Transitive persistence with cascading ........................................................... 22
2.2.5.5. Association fetching ................................................................................... 22
2.2.6. Mapping composite primary and foreign keys ......................................................... 22
2.2.7. Mapping secondary tables ...................................................................................... 24
2.3. Mapping Queries .............................................................................................................. 24
2.3.1. Mapping EJBQL/HQL queries ............................................................................... 24
2.3.2. Mapping native queries .......................................................................................... 25
2.4. Hibernate Annotation Extensions ...................................................................................... 28
2.4.1. Entity ................................................................................................................... 29
2.4.2. Identifier ............................................................................................................... 30
2.4.3. Property ................................................................................................................ 30
2.4.3.1. Access type ................................................................................................ 30
2.4.3.2. Formula ..................................................................................................... 32
2.4.3.3. Type .......................................................................................................... 32
2.4.3.4. Index ......................................................................................................... 33
2.4.3.5. @Parent ..................................................................................................... 33
2.4.3.6. Generated properties ................................................................................... 33
2.4.4. Inheritance ............................................................................................................ 33
2.4.5. Single Association related annotations .................................................................... 34
2.4.5.1. Lazy options and fetching modes ................................................................. 34
2.4.6. Collection related annotations ................................................................................ 35
2.4.6.1. Parameter annotations ................................................................................. 35
2.4.6.2. Extra collection types .................................................................................. 35
Hibernate 3.2.0 CR1 ii
2.4.7. Cache ................................................................................................................... 38
2.4.8. Filters ................................................................................................................... 38
2.4.9. Queries ................................................................................................................. 39
3. Overriding metadata through XML .......................................................................................... 40
3.1. Principles ......................................................................................................................... 40
3.1.1. Global level metadata ............................................................................................ 40
3.1.2. Entity level metadata ............................................................................................. 40
3.1.3. Property level metadata .......................................................................................... 43
3.1.4. Association level metadata ..................................................................................... 43
4. Hibernate Validator .................................................................................................................. 45
4.1. Constraints ...................................................................................................................... 45
4.1.1. What is a constraint? .............................................................................................. 45
4.1.2. Built in constraints ................................................................................................. 45
4.1.3. Error messages ...................................................................................................... 46
4.1.4. Writing your own constraints ................................................................................. 47
4.1.5. Annotating your domain model .............................................................................. 48
4.2. Using the Validator framework ......................................................................................... 49
4.2.1. Database schema-level validation ........................................................................... 49
4.2.2. Hibernate event-based validation ............................................................................ 50
4.2.3. Application-level validation ................................................................................... 50
4.2.4. Validation informations ......................................................................................... 50
5. Hibernate Lucene Integration ................................................................................................... 52
5.1. Using Lucene to index your entities ................................................................................... 52
5.1.1. Annotating your domain model .............................................................................. 52
5.1.2. Enabling automatic indexing .................................................................................. 52
Hibernate Annotations
Hibernate 3.2.0 CR1 iii
Preface
Hibernate, like all other object/relational mapping tools, requires metadata that governs the transformation of
data from one representation to the other (and vice versa). In Hibernate 2.x, mapping metadata is most of the
time declared in XML text files. Another option is XDoclet, utilizing Javadoc source code annotations and a
preprocessor at compile time. The same kind of annotation support is now available in the standard JDK, al-
though more powerful and better supported by tools. IntelliJ IDEA, and Eclipse for example, support auto-
completion and syntax highlighting of JDK 5.0 annotations. Annotations are compiled into the bytecode and
read at runtime (in Hibernate's case on startup) using reflection, so no external XML files are needed.
The EJB3 specification recognizes the interest and the success of the transparent object/relational mapping
paradigm. The EJB3 specification standardizes the basic APIs and the metadata needed for any object/relational
persistence mechanism. Hibernate EntityManager implements the programming interfaces and lifecycle rules
as defined by the EJB3 persistence specification. Together with Hibernate Annotations, this wrapper imple-
ments a complete (and standalone) EJB3 persistence solution on top of the mature Hibernate core. You may use
a combination of all three together, annotations without EJB3 programming interfaces and lifecycle, or even
pure native Hibernate, depending on the business and technical needs of your project. You can at all times fall
back to Hibernate native APIs, or if required, even to native JDBC and SQL.
Please note that this documentation is based on a preview release of the Hibernate Annotations that follows the
public final draft of EJB 3.0/JSR-220 persistence annotations. This work is already very close to the final con-
cepts in the new specification. Our goal is to provide a complete set of ORM annotations, including EJB3
standard annotations as well as Hibernate3 extensions for cases not covered by the specification. Eventually
you will be able to create all possible mappings with annotations. See the JIRA road mapsection for more in-
formation.
The EJB3 Public final draft has change some annotations, please refer to http://www.hibernate.org/371.html as
a migration guide from previous versions of Hibernate Annotations.
Hibernate 3.2.0 CR1 iv
Chapter 1. Setting up an annotations project
1.1. Requirements
• Download and unpack the Hibernate Annotations distribution from the Hibernate website.
• This preview release requires Hibernate 3.2.0.CR2 and above. Do not use this release of Hibernate Annota-
tions with an older version of Hibernate 3.x!
• This release is known to work on Hibernate core 3.2.0.CR2
• Make sure you have JDK 5.0 installed. You can of course continue using XDoclet and get some of the be-
nefits of annotation-based metadata with older JDK versions. Note that this document only describes JDK
5.0 annotations and you have to refer to the XDoclet documentation for more information.
1.2. Configuration
First, set up your classpath (after you have created a new project in your favorite IDE):
• Copy all Hibernate3 core and required 3rd party library files (see lib/README.txt in Hibernate).
• Copy hibernate-annotations.jar and lib/ejb3-persistence.jar from the Hibernate Annotations dis-
tribution to your classpath as well.
• To use the Chapter 5, Hibernate Lucene Integration, add the lucene jar file.
We also recommend a small wrapper class to startup Hibernate in a static initializer block, known as Hibern-
ateUtil. You might have seen this class in various forms in other areas of the Hibernate documentation. For
Annotation support you have to enhance this helper class as follows:
package hello;
import org.hibernate.*;
import org.hibernate.cfg.*;
import test.*;
import test.animals.Dog;
public class HibernateUtil {
private static final SessionFactory sessionFactory;
static {
try {
sessionFactory = new AnnotationConfiguration().buildSessionFactory();
} catch (Throwable ex) {
// Log exception!
throw new ExceptionInInitializerError(ex);
}
}
public static Session getSession()
throws HibernateException {
return sessionFactory.openSession();
}
}
Hibernate 3.2.0 CR1 1
