Chapter 1. Setting up an annotations project. 第1章アノテーションプロジェクトのセットアップ

1.1. Requirements 必要要件

Hibernate Annotations の廃物を Hibernate の website からダウンロードして解凍してね。
このリリースは Hibernate Core 3.2.0 GA 以降が必要だよ。
このリリースは Hibernate Core 3.2.0 から 3.2.2.GA で動いたよ。
JDK5.0 以上をインストールしてね。古い JDK で XDoclet を使ってアノテーションを利用することはできるけど、このドキュメントでは JDK5.0 についてしか書かないよ。XDocletは自分で調べてね。

1.2. Configuration 設定

最初にクラスパスの設定だよ。（もちろん最初にお好きなIDEでプロジェクトを作ってね。）

Hibernate3 core の全部と必要なサードパーティーのライブラリをコピーしてね。（Hibernate の lib/README.txt を見てね。）
Hibernate Annotations 配布物にある hibernate-annotations.jar, lib/hibernate-comons-annotations.jar and lib/ejb3-persistence.jar を自分のクラスパスにコピーしてね。

Hibernate Validator を使いたいなら、それもダウンロードして hibernate-validator.jar をクラスパスに追加してね。
Hibernate Search を使いたいなら、それもダウンロードして hibernate-search.jar と lucene-core-x.y.z.jar を（略

Hibarnate を起動する、HibernateUtils という小さなラッパークラスをお勧めするよ。もしかしたら、他の Hibernate のドキュメントで見たことあるかもしれないね。Annotation を使うために、次みたいにするといいよ。*1

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

ここで面白いのは AnnotationConfiguration の使い方だよ。パッケージとアノテートされるクラスは XMLファイル（普通は hibernate.cfg.xml）で宣言されるよ。次のは、さっきの宣言に対応するよ。

<!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>

hbm.xml を使う方法とアノテーションを混ぜることもできるよ。リソースファイルは、hbm ファイルか、EJB3 デプロイメントディスクリプタか、どっちか選べるよ。

もう一個の方法で、プログラムで定義することもできるよ。

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

ほかにも、Hibernate EntityManager を使う方法もあるよ。詳細は別のドキュメントを見てね。

それぞれに違いはないので、hibernate.propertiesや、hibernate.cfg.xml, programmatic APIs、その他、なんでも好きな方法を使えばいいよ。アノテーションと、これまでの hbm.cfg.xml も、同じセッションファクトリで混ぜて使えるよ。だけど、同じクラスにアノテーションと hbm.xml はできないよ。エンティティの階層のマッピングでは、hbm とアノテーションは混ぜて使えないよ。

hbm ファイルからアノテーションへの移行を楽にするために、設定の重複を検出してくれるよ。HBM ファイルは、アノテーションより優先されるよ。hibernate.mapping.precedence でその優先順位を変えれるよ。デフォルトは hbm, class となってるから、class, hbm とすると、アノテーションが優先されるよ。

1.3. Properties プロパティ

Hibernate core プロパティ以外に、Hibernate Annotations は、次のプロパティを見るよ。

プロパティ	定義
hibernate.validator.apply_to_ddl	データベーススキーマ生成のリファインに Hibernate Validator を使うよ。デフォルトは true

*1:本家ではnew AnnotationConfiguration()の後に"."が抜けているようなので追記しました。