First, set up your classpath (after you have created a new project in your favorite IDE):

Alternatively, import your pom.xml in your favorite IDE and let the dependencies be resolved automatically,

We recommend you use Hibernate Validator and the Bean Validation specification capabilities as its integration with Java Persistence 2 has been standardized. Download Hibernate Validator 4 or above from the Hibernate website and add hibernate-validator.jar and validation-api.jar in your classpath. Alternatively add the following dependency in your pom.xml.

<project>

  ...

  <dependencies>

    <dependency>

      <groupId>org.hibernate</groupId>

      <artifactId>hibernate-validator</artifactId>

      <version>${hibernate-validator-version}</version>

    </dependency>

    ...

  </dependencies>

  ...

</project>

If you wish to use Hibernate Search, download it from the Hibernate website and add hibernate-search.jar and its dependencies in your classpath. Alternatively add the following dependency in your pom.xml.

<project>

  ...

  <dependencies>

    <dependency>

      <groupId>org.hibernate</groupId>

      <artifactId>hibernate-search</artifactId>

      <version>${hibernate-search-version}</version>

    </dependency>

    ...

  </dependencies>

  ...

</project>

We recommend you use the JPA 2 APIs to bootstrap Hibernate (see the Hibernate EntityManager documentation for more information). If you use Hibernate Core and its native APIs read on.

If you boot Hibernate yourself, make sure to use the AnnotationConfiguration class instead of the Configuration class. Here is an example using the (legacy) HibernateUtil approach:

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()

                    .configure().buildSessionFactory();

        } catch (Throwable ex) {

            // Log exception!

            throw new ExceptionInInitializerError(ex);

        }

    }


    public static Session getSession()

            throws HibernateException {

        return sessionFactory.openSession();

    }

}

            

Interesting here is the use of AnnotationConfiguration. The packages and annotated classes are declared in your regular XML configuration file (usually hibernate.cfg.xml). Here is the equivalent of the above declaration:

<!DOCTYPE hibernate-configuration PUBLIC

    "-//Hibernate/Hibernate Configuration DTD 3.0//EN"

    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

  <session-factory>

    <mapping package="test.animals"/>

    <mapping class="test.Flight"/>

    <mapping class="test.Sky"/>

    <mapping class="test.Person"/>

    <mapping class="test.animals.Dog"/>



    <mapping resource="test/animals/orm.xml"/>

  </session-factory>

</hibernate-configuration>

Note that you can mix the legacy hbm.xml use and the annotation approach. The resource element can be either an hbm file or an EJB3 XML deployment descriptor. The distinction is transparent for your configuration process.

Alternatively, you can define the annotated classes and packages using the programmatic API

sessionFactory = new AnnotationConfiguration()
                    .addPackage("test.animals") //the fully qualified package name
                    .addAnnotatedClass(Flight.class)
                    .addAnnotatedClass(Sky.class)
                    .addAnnotatedClass(Person.class)
                    .addAnnotatedClass(Dog.class)
                    .addResource("test/animals/orm.xml")

                    .configure()

                    .buildSessionFactory();

There is no other difference in the way you use Hibernate APIs with annotations, except for this startup routine change or in the configuration file. You can use your favorite configuration method for other properties ( hibernate.properties, hibernate.cfg.xml, programmatic APIs, etc).

To ease the migration process from hbm files to annotations, the configuration mechanism detects the mapping duplication between annotations and hbm files. HBM files are then prioritized over annotated metadata on a class to class basis. You can change the priority using hibernate.mapping.precedence property. The default is hbm, class, changing it to class, hbm will prioritize the annotated classes over hbm files when a conflict occurs.

On top of the Hibernate Core properties, Hibernate Annotations reacts to the following one.

Hibernate Annotations 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 properly 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.

The logging categories interesting for Hibernate Annotations are:

For further category configuration refer to the Logging in the Hibernate Core documentation.