Hibernate Core リファレンスガイド

JBoss Enterprise Application Platform 5

JBoss Enterprise Application Platform 5 向け

エディッション 5.1.2

Red Hat Documentation Group

概要

JBoss Enterprise Application Platform 5 およびそのパッチリリース向けの Hibernate Core リファレンスガイドです。

はじめに

オブジェクト指向のソフトウェアやリレーショナルデータベースの使用は、今日のエンタープライズ環境では非常に煩雑で時間のかかる作業となります。Hibernate は Java 環境用のオブジェクト/リレーショナルマッピングツールです。オブジェクト/リレーショナルマッピング (ORM) とはデータ表現をオブジェクトモデルから SQL ベースのスキーマによるリレーショナルデータモデルにマッピングする技術のことを指します。
Hibernate は Java クラスからデータベーステーブルへのマッピング (および Java データタイプから SQL データタイプへのマッピング) を行うだけでなく、 データのクエリや検索機能も提供します。 SQL や JDBC での手作業によるデータ処理時間を短縮できるため、 開発に要する時間を大幅に削減することが可能になります。
Hibernate の目標は、一般的なデータ永続性に関する開発者のプログラム作業を95 % 軽減することです。 Hibernate データベース内でビジネスロジックを実現するストアドプロシージャのみを使用するデータ処理中心のアプリケーションに対しては最適ではないかもしれませんが、 Java ベースの中間層でのビジネスロジックやオブジェクト指向のドメインモデルを使用する場合に最も実用的です。 Hibernate は開発者がベンダー固有の SQL コードを除去したりカプセル化できるようにするため、 表形式からオブジェクトのグラフへ結果セットを変換する一般的な作業を行う際に便利です。
Hibernate 及びオブジェクト/リレーショナルマッピング、 あるいは Java が不慣れな方は、次の手順を行ってください。
  1. ステップバイステップのチュートリアル 1章チュートリアル をお読みください。 チュートリアルのソースコードはディストリビューションの doc/reference/tutorial/ ディレクトリにあります。
  2. Hibernate が使用できる環境について理解するため、2章アーキテクチャをお読みください。
  3. Hibernate ディストリビューション内の eg/ ディレクトリを確認してください。 簡単なスタンドアロンアプリケーションが含まれています。 ご使用の JDBC ドライバを lib/ ディレクトリにコピーしてから、 ご使用のデータベースに対して適切な値を指定するため etc/hibernate.properties を編集します。 コマンドプロンプトでディストリビューションディレクトリ内より ant eg (Ant を使用) と入力します。 Windows の場合は build eg と入力します。
  4. 本参考文書は主な情報源としてご利用ください。 アプリケーションデザインに関する詳細や、 ステップバイステップのチュートリアルが必要な場合は、 Java Persistence with Hibernate (http://www.manning.com/bauer2) の参照をお薦めします。 また、 http://caveatemptor.hibernate.org より Java Persistence with Hibernate のサンプルアプリケーションをダウンロードすることができます。
  5. よくある質問とその答え (FAQ) は Hibernate ウェブサイトでご覧ください。
  6. サードパーティのデモ、 サンプル、 チュートリアルなどは Hibernate のウェブサイト上にリンクされています。
  7. Hibernate ウェブサイト上の Community Area はデザインのパターンやさまざまな統合ソリューション (Tomcat、 JBoss AS、 Struts、 EJB など)を検索する上で興味深いリソースになります。
質問がある場合は、 Hibernate ウェブサイト上にリンクされたユーザーフォーラムをご利用ください。 また、 バグ報告や機能のリクエストに関して JIRA 問題追跡システムを提供しています。 Hibernate, の開発に興味がある方は、 開発者用メーリングリストにご参加ください。 本ドキュメントの翻訳に興味がある方は、 開発者用メーリングリストよりご連絡ください。
Hibernate に関する商業用開発サポート、 実稼働サポート、 トレーニングについては JBoss Inc よりご利用頂けます (http://www.hibernate.org/SupportTraining/ を参照)。 Hibernate はプロフェッショナルなオープンソースプロジェクトであり、 JBoss Enterprise Middleware System (JEMS) スイート製品の重要なコンポーネントになります。

第1章 チュートリアル

本章は、インメモリデータベースを使用した簡単なアプリケーションから始まり、 Hibernate を段階的に説明する新規ユーザー向けの章です。 本チュートリアルは Michael Gloegl 氏が開発したチュートリアルよりも前のものを基にしています。 すべてのコードはプロジェクトソースの tutorials/web ディレクトリに格納されています。

重要

本チュートリアルは、 Java と SQL の知識があることを前提としています。 Java や SQL の知識に乏しい場合は、 これらの技術に関する知識を深めてから Hibernate について学ぶようにしてください。

注記

ディストリビューションの tutorial/eg プロジェクトソースディレクトリには他のサンプルアプリケーションも格納されています。

1.1. パート1 - 初めての Hibernate アプリケーション

この例では、参加したいイベントやイベントのホストに関する情報を保存するための小さなデータベースアプリケーションを設定します。

注記

どのデータベースをご利用いただいても構いませんが、ここでは HSQLDB (インメモリの Java データベース) を使用し、特定のデータベースサーバーのインストールや設定に関する説明を省略します。

1.1.1. 設定

最初に、 開発環境を設定する必要があります。 ここでは、 Maven など、 多くのビルドツールが推奨する「標準レイアウト」を使用します。 Maven にこの レイアウト を詳細に説明するリソースがあります。 このチュートリアルはWebアプリケーションであるため、src/main/java ディレクトリや src/main/resources ディレクトリ、 src/main/webapp ディレクトリを使用します。
本チュートリアルではMavenを使っており、遷移従属性の管理機能や多くのIDE機能を活用し、Maven記述子を元にプロジェクトを自動設定しています。
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://
maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.hibernate.tutorials</groupId>
  <artifactId>hibernate-tutorial</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>war</packaging>
  <name>First Hibernate Tutorial</name>
  <build>
<!--we dont want the version to be part of the generated war file name-->
  <finalName>${artifactId}</finalName>
<!--we dont want to use the jars maven provided, we want to use JBoss' ones-->
  <plugins>
    <plugin>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
        <packagingExcludes>WEB-INF/lib/*.jar</packagingExcludes>
      </configuration>
    </plugin>
  </plugins>

  </build>
    <dependencies> 
      <dependency> 
      <groupId>org.hibernate</groupId> 
      <artifactId>hibernate-core</artifactId> 
      <version>3.3.2.GA_CP04</version>
<!-- please check the release notes for the correct version you're using --> 
    </dependency> 
<!-- Because this is a web app, we also have a dependency on the servlet api. --> 
    <dependency> 
      <groupId>javax.servlet</groupId> 
      <artifactId>servlet-api</artifactId> 
      <version>2.5</version>
    </dependency> 
<!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend --> 
    <dependency> 
      <groupId>org.slf4j</groupId> 
      <artifactId>slf4j-simple</artifactId> 
      <version>1.5.8</version> 
    </dependency> 
<!-- Hibernate gives you a choice of bytecode providers between cglib and javassist --> 
    <dependency> 
      <groupId>javassist</groupId> 
      <artifactId>javassist</artifactId> 
      <version>3.12.0.GA</version> 
    </dependency> 
  </dependencies> 
</project>

注記

Maven の使用は必須ではありません。 Ant など別の技術を使用して本チュートリアルをビルドする場合でもレイアウトは同じになります。 手作業で必要な従属性すべてに対応する必要があることのみが異なります。 Ivy を使用して遷移的従属性の管理を提供する場合でも、 下記の従属性を使用します。 下記の従属性を使用しない場合、 明示的従属性と遷移的従属性をすべて見つけ、 プロジェクトのクラスパスに追加する必要があります。 Hibernate ディストリビューションバンドルから作業する場合、 hibernate3.jarlib/required ディレクトリの全アーチファクト、 lib/bytecode/cglib ディレクトリまたは lib/bytecode/javassist ディレクトリの全ファイルが対象となります。 また、 servlet-api jar と slf4j ロギングバックエンドの 1 つが必要となります。
このファイルを pom.xml としてプロジェクトルートディレクトリに保存します。

1.1.2. 最初のクラス

次にデータベースに格納するイベントを表すクラスを作成します。 これは、 一部のプロパティを持つ簡単な JavaBean クラスになります。
package org.hibernate.tutorial.domain;

import java.util.Date;

public class Event {
    private Long id;

    private String title;
    private Date date;

    public Event() {}

    public Long getId() {
        return id;
    }

    private void setId(Long id) {
        this.id = id;
    }

    public Date getDate() {
        return date;
    }

    public void setDate(Date date) {
        this.date = date;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }
}
このクラスは、 プロパティゲッターメソッドとセッタメソッドに対する標準の Java 命名規則やフィールドに対する private の可視性を使用します。 これが推奨設計となりますが、 必須ではありません。 Hibernate は直接フィールドにアクセスすることもでき、 アクセッサメソッドの利点は再ファクタリングの堅牢性になります。
id プロパティは、 特定イベントに対して固有の識別子の値を保持します。 Hibernate の機能を全て使用した場合、 すべての永続エントリクラス (それほど重要ではない依存クラスもあります) にこのような識別子プロパティが必要となります。 ほとんどのアプリケーション (特に Web アプリケーション) が識別子でオブジェクトを識別する必要があるため、 制限ではなく機能であると考えた方がよいでしょう。 しかし、 通常オブジェクトのアイデンティティは操作しないため、 セッタメソッドは private とするべきです。 オブジェクトが保存される時に Hibernate のみが識別子を割り当てます。 Hibernate は public、 private、 protected のアクセッサメソッドにアクセスでき、 public、 private、 protected のフィールドに直接アクセスできます。 選択は任意であるため、 アプリケーション設計にあわせて選択することができます。
引数のないコンストラクタはすべての永続クラスに必須です。Hibernate は Java Reflection を使用してオブジェクトを作成しなければなりません。コンストラクタを private にすることは可能ですが、ランタイム時にプロキシを生成し、バイトコードのインスツルメントなしで効率的にデータを読み出しするため、パッケージや public の可視性は必要となります。
このファイルを src/main/java/org/hibernate/tutorial/domain ディレクトリに保存します。

1.1.3. マッピングファイル

Hibernate は、どのように永続クラスのオブジェクトをロードし格納すればよいかを知る必要があります。ここで Hibernate マッピングファイルが登場します。マッピングファイルは、データベース内のどのテーブルにアクセスしなければならないか、そのテーブルのどのカラムを使うべきかを、 Hibernate に教えます。
マッピングファイルの基本的な構造はこのようになります:
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="org.hibernate.tutorial.domain">
[...]
</hibernate-mapping>
Hibernate DTD は非常に高機能です。 エディターや IDE の XML マッピング要素や属性を自動補完するために使用することができます。 要素や属性の全体を確認し、 デフォルトや一部コメントを閲覧するには、 テキストエディタで DTD ファイルを開くのが最も簡単な方法です。 Hibernate は Web より DTD ファイルをロードしませんが、 最初にアプリケーションのクラスパスより検索します。 DTD ファイルは hibernate-core.jar に含まれています (ディストリビューションバンドルを使用する場合は hibernate3.jar にも含まれています)。

重要

これ以降の例ではコードを短くするために DTD 宣言を省略します。 当然ですがこれはオプションではありません。
2つの hibernate-mapping タグの間に class 要素があるようにします。 すべての永続エンティティクラスは SQL データベース内のテーブルへのマッピングを必要とします (繰り返しになりますが、 ファーストクラスエンティティではない依存クラスが後で存在する可能性があります)。
<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">

    </class>

</hibernate-mapping>
これまで、 Event クラスのオブジェクトを EVENTS テーブルへ永続し、 ロードする方法を Hibernate に指示しました。これにより、各インスタンスはテーブルの行によって表されるようになりました。次に、固有の識別子プロパティをテーブルの主キーへマッピングします。この識別子の処理を考慮したくないため、代理主キー列に対する Hibernate の識別子生成戦略を設定します。
<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
    </class>

</hibernate-mapping>
id 要素は識別子プロパティの宣言です。 name="id" マッピング属性が JavaBean プロパティの名前を宣言し、 プロパティのアクセスに getId() メソッドと setId() メソッドを使用するよう Hibernate に指示します。 column 属性は、 主キーの値を保持する EVENTS テーブルの列を Hibernate に伝えます。
ネストされた generator 要素は識別子生成戦略 (識別子の値を生成する方法) を指定します。この例では、 設定されたデータベース方言に応じて移植性のレベルを提供する native を選択しています。 Hibernate はデータベースによって生成され、グローバルに固有なアプリケーションによって割り当てられる識別子をサポートしています。識別子の値の生成は Hibernate の拡張ポイントの 1 つでもあり、 独自の戦略にプラグインすることができます。

注記

移植性という観点から考慮した場合、 native は最良の戦略とは見なされなくなりました。 詳細は 「識別子の生成」 を参照してください。
最後に、 残りのエンティティクラスプロパティに関して Hibernate に伝える必要があります。 デフォルトでは、 永続とされるクラスのプロパティはありません。
<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
        <property name="date" type="timestamp" column="EVENT_DATE"/>
        <property name="title"/>
    </class>

</hibernate-mapping>
id 要素の場合と同様に、 property 要素の name 属性が使用するゲッターメソッドとセッタメソッドを Hibernate に指示します。この例では、 Hibernate は、 getDate()setDate()getTitle()setTitle() のメソッドを検索します。

注記

date プロパティのマッピングには column 属性があり、 title プロパティにないのはなぜでしょうか。 column 属性がない場合、 Hibernate はデフォルトでプロパティ名を列名として使用します。 これは title に対しては問題ありませんが、 date はほとんどのデータベースでキーワードとして確保されています。 そのため、 違う名前にマップする必要があるのです。
title マッピングにも type 属性がありません。 マッピングファイルで宣言して使用する型は Java のデータ型ではなく、 SQL のデータベース型でもありません。 これらの型は Hibernateマッピング型 と呼ばれ、 Java から SQ Lのデータ型または SQ Lから Java のデータ型に変換するコンバータになります。 type 属性がマッピングに存在しない場合は、 Hibernate が正しい変換とデータ型を判断します。 場合によっては、 Java クラス上の Reflection を使用した自動検出のデフォルトが必要なデフォルトでないことがあり、 date 属性がこれに該当します。 java.util.Date のプロパティが SQL の datetimestamptime 列のいずれかへマップするべきであることを Hibernate は認識しません。 完全な日付と時間の情報は、 このプロパティを timestamp コンバータでマッピングして保持されます。

注記

マッピングファイルが処理される時に Hibernate は Reflection を使用してこのマッピング型を判断します。 これには時間とリソースを要するため、 起動時のパフォーマンスが重要な場合は、 使用する型を明示的に定義した方がよいでしょう。
このマッピングファイルを src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml として保存します。

1.1.4. Hibernate の設定

この時点で永続クラスとそのマッピングファイルが設定されたはずです。 次に Hibernate を設定します。 最初に HSQLDB が「サーバーモード」で実行するよう設定します。

注記

これは、 実行の合間にデータを維持するために行います。
Maven の実行プラグインを使用して mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial" を実行し、 HSQLDB サーバーを起動します。 これにより、 サーバーの起動とアプリケーションが後で接続する TCP/IP ソケットへのバインドを確認できます。 本チュートリアルの実行中に新たにデータベースを使用したい場合は、 HSQLDB をシャットダウンしてから target/data ディレクトリのファイルをすべて削除し、 HSQLDB を再度起動します。
アプリケーションの代わりに Hibernate がデータベースへ接続するため、 接続する方法を認識する必要があります。 本チュートリアルでは、 javax.sql.DataSource ではなくスタンドアロンの接続プールを使用します。 Hibernate は c3p0proxool の 2 つのサードバーティーによるオープンソース JDBC 接続プールをサポートしていますが、 本チュートリアルでは Hibernate にビルトインされている接続プールを使用します。

警告

Hibernate にビルトインされている接続プールは実稼働での使用には向いていません。
Hibernate の設定では、 単純な hibernate.properties ファイル、 高機能な hibernate.cfg.xml ファイル、 完全にプログラムを用いた設定を使用することができます。 XML 設定ファイルによる設定が最も一般的です。
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class">org.hsqldb.jdbcDriver</property>
        <property name="connection.url">jdbc:hsqldb:hsql://localhost</property>
        <property name="connection.username">sa</property>
        <property name="connection.password"></property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size">1</property>

        <!-- SQL dialect -->
        <property name="dialect">org.hibernate.dialect.HSQLDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class">thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class">org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql">true</property>

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto">update</property>

        <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration>

注記

この設定ファイルは異なる DTD を指定することに注意してください。
Hibernate のSessionFactory を設定します。 SessionFactory は特定のデータベースに対応するグローバルファクトリです。 複数のデータベースがある場合、 複数の設定ファイルに複数の <session-factory> 設定を使用するのが最も簡単です。
最初の 4 つの property 要素に JDBC 接続に必要な設定が含まれています。方言の property 要素は Hibernate が生成する SQL のバリアントを指定します。

注記

ほとんどの場合で Hibernate は使用する方言を正しく決定することができます。 詳細は 「方言の解決」 を参照してください。
永続コンテキストに対する Hibernate の自動管理は、 特にこのコンテキストで有用です。 hbm2ddl.auto オプションは、 データベーススキーマを直接データベースに自動生成する機能を有効にします。 設定オプションを削除するか、 SchemaExport Ant タスクでファイルをリダイレクトしてデータベーススキーマの自動生成を無効にすることもできます。 最後に、 永続クラスのマッピングファイルを設定に追加します。
このファイルを hibernate.cfg.xml として src/main/resources ディレクトリに保存します。

1.1.5. Maven によるビルド

Maven でチュートリアルをビルドします。 これには Maven をインストールする必要があります。 Maven は Maven ダウンロードページ よりダウンロードできます。 Maven はこれまでに作成した /pom.xml ファイルを読み取り、 基本的なプロジェクトタスクの一部を実行する方法を認識します。 最初に compile ゴールを実行し、 すべてをコンパイルできるようにします。
[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO]    task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------

1.1.6. スタートアップとヘルパ

Event オブジェクトの一部をロードしたり格納する準備ができましたが、 最初にインフラストラクチャコードで設定を完了する必要があります。 グローバルな org.hibernate.SessionFactory オブジェクトをビルドし、 アプリケーションコードで簡単にアクセスできるよう任意の場所に保存して Hibernate を起動する必要があります。 org.hibernate.Session インスタンスの取得には org.hibernate.SessionFactory を使用します。 org.hibernate.Session は単一スレッドの作業単位 (unit of work) を表します。 org.hibernate.SessionFactory は 1 度インスタンス化されるスレッドセーフのグローバルオブジェクトです。
起動やもっと簡単に SessionFactory へのアクセスできるように処理を行うHibernateUtil ヘルパークラスを作成します。
package org.hibernate.tutorial.util;

import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;

public class HibernateUtil {

    private static final SessionFactory sessionFactory = buildSessionFactory();

    private static SessionFactory buildSessionFactory() {
        try {
            // Create the SessionFactory from hibernate.cfg.xml
            return new Configuration().configure().buildSessionFactory();
        }
        catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
        }
    }

    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    }

}
このコードを src/main/java/org/hibernate/tutorial/util/HibernateUtil.java として保存します。
このクラスは、 静的初期化子にグローバルな org.hibernate.SessionFactory 参照を作成するだけでなく、 静的なシングルトンを使用することを表に見せません。アプリケーションサーバーや他の場所の JNDI より org.hibernate.SessionFactory 参照をルックアップするのと同様です。
設定で org.hibernate.SessionFactory に名前を付ける場合、 Hibernate はビルドされた名前で JNDI へバインドしようとします。このような場合、 JMX デプロイメントを使用し、 JMX 対応のコンテナによって HibernateService を JNDI へインスタンス化しバインドする方法を使用した方がよいでしょう。 このような高度なオプションについては後ほど説明します。
ここでロギングシステムを設定する必要があります。 Hibernate は commons logging を使用し、 Log4j と JDK 1.4 ロギングの 2 つを選択できます。 開発者の多くは Log4j を選択します。 Log4j の場合、 etc/ ディレクトリにある Hibernate ディストリビューションの log4j.propertieshibernate.cfg.xml の隣の src ディレクトリへコピーします。 設定例よりも詳細な出力を希望する場合は、 設定を変更することができます。 デフォルトでは Hibernate 起動メッセージは標準出力 (stdout) で表示されます。
これでチュートリアルのインフラストラクチャが完成したため、 Hibernate を使って実際の作業を行う準備が整いました。

1.1.7. オブジェクトのロードと格納

Hibernate を使って実際の作業を行う準備ができました。 最初に main() メソッドを持つ EventManager クラスを記述します。
package org.hibernate.tutorial;

import org.hibernate.Session;

import java.util.*;

import org.hibernate.tutorial.domain.Event;
import org.hibernate.tutorial.util.HibernateUtil;

public class EventManager {

    public static void main(String[] args) {
        EventManager mgr = new EventManager();

        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }

        HibernateUtil.getSessionFactory().close();
    }

    private void createAndStoreEvent(String title, Date theDate) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        session.save(theEvent);

        session.getTransaction().commit();
    }

}
createAndStoreEvent() に新しい Event オブジェクトが作成され、 Hibernate に渡されました。 この時点で Hibernate は SQL に対処し、 データベース上で INSERT を実行します。
org.hibernate.Session は単一の作業単位 (実行される単一のアトミックな作業) を表します。 ここでは、 分かりやすくするため Hibernate の org.hibernate.Session とデータベーストランザクション間の粒度を一対一とします。 実際に基礎となるトランザクションシステムからコードを保護するため、 Hibernate の org.hibernate.Transaction API を使用します。この例では JDBC ベースのトランザクションセマンティックを使用していますが、 JTA で実行することも可能です。
sessionFactory.getCurrentSession() は何を実行するのでしょうか。 org.hibernate.SessionFactory を取得した後、 どこでも何回でも呼び出すことができます。 getCurrentSession() メソッドは常に「現在」の作業単位を返します。 このメカニズムの設定オプションを src/main/resources/hibernate.cfg.xml の「スレッド」に切り替えたことを思い出してください。 この設定により、 現在の作業単位のコンテキストは、 アプリケーションを実行する現在の Java スレッドへバインドされます。

重要

Hibernate は現セッションの追跡に 3 つのメソッドを提供します。「スレッド」ベースのメソッドは実稼働の使用には向いておらず、 プロトタイプやチュートリアルのみに対して有用です。現セッションの追跡については後ほど詳しく説明します。
現在のスレッドに対して getCurrentSession() へ最初の呼び出しが実行された時に org.hibernate.Session が開始されます。 その後、 Hibernate によって現在のスレッドへバインドされます。 コミットやロールバックによってトランザクションが終了すると、 Hibernate はスレッドより自動的に org.hibernate.Session をアンバインドして閉じます。 getCurrentSession() を再度呼び出すと、 新しい org.hibernate.Session を取得し、 新しい作業単位 (unit of work) を開始することができます。
作業単位の範囲に関し、 Hibernate の org.hibernate.Session を使用して 1 つまたは複数のデータベース操作を実行するべきでしょうか。 前述の例では 1 つのorg.hibernate.Session を 1 つの操作に使用していますが、 これは単なる偶然です。 この例は単純であるため、 他の方法で表すことができないからです。 Hibernate の org.hibernate.Session の範囲は柔軟ですが、 データベース操作ごとに新しい Hibernate の org.hibernate.Session を使用しないようアプリケーションを設計するようにしてください。 次の例では 「操作毎のセッション」 が使用されていますが、 これはアンチパターンとして考慮するようにしてください。 本チュートリアルで後ほど使用する実際の Web アプリケーションを確認すると理解できるはずです。
トランザクションの処理と境界の詳細については、 11章トランザクションと並行性 を参照してください。 前の例ではエラー処理とロールバックを割愛しています。
mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store" を実行し、 Maven 実行プラグインを使用して必要なクラスパスの設定を持つクラスを呼び出します。

注記

最初に mvn compile を実行する必要がある場合があります。
これで Hibernate が起動するはずです。また、設定によっては大量のログ出力が表示されることがあります。最後の方に、以下の行が表示されます。
[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)
これは Hibernate によって実行された INSERT になります。
格納されたイベントを一覧表示するには、 main メソッドにオプションを追加します。
        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }
        else if (args[0].equals("list")) {
            List events = mgr.listEvents();
            for (int i = 0; i < events.size(); i++) {
                Event theEvent = (Event) events.get(i);
                System.out.println(
                        "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate()
                );
            }
        }
新しい listEvents() も追加されます。
    private List listEvents() {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        List result = session.createQuery("from Event").list();
        session.getTransaction().commit();
        return result;
    }
ここでは、 HQL (Hibernate Query Language) クエリを使用して、 データベースより既存の Event オブジェクトをすべてロードします。 Hibernate は適切な SQL を生成し、 データベースへ送信して Event オブジェクトにデータを追加します。 HQL でさらに複雑なクエリを作成することができます。 詳細は 14章HQL: Hibernate クエリ言語 を参照してください。
これで、 mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list" を実行し、 Maven 実行プラグインを使用して新しい機能を呼び出せるようになりました。

1.2. パート2 - 関連のマッピング

これまで、 単一の永続エンティティクラスを分離されたテーブルにマッピングしました。 これにクラスの関連を追加してみましょう。 アプリケーションに人物を追加し、 人物が参加するイベントのリストを保存します。

1.2.1. Person クラスのマッピング

Person クラスの最初の部分は次のようになります。
package org.hibernate.tutorial.domain;

public class Person {

    private Long id;
    private int age;
    private String firstname;
    private String lastname;

    public Person() {}

    // Accessor methods for all properties, private setter for 'id'

}
これを src/main/java/org/hibernate/tutorial/domain/Person.java というファイルに保存します。
次に、 src/main/resources/org/hibernate/tutorial/domain/Person.hbm.xml という新しいマッピングファイルを作成します。
<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Person" table="PERSON">
        <id name="id" column="PERSON_ID">
            <generator class="native"/>
        </id>
        <property name="age"/>
        <property name="firstname"/>
        <property name="lastname"/>
    </class>

</hibernate-mapping>
最後に、Event.hbm.xmlの既存のマッピングのすぐ後に、Hibernateの設定に新たなマッピングを追加します。
<mapping resource="events/Event.hbm.xml"/>
<mapping resource="events/Person.hbm.xml"/>
これら 2 つのエンティティ間の関連を作成します。 人物はイベントに参加でき、 イベントには参加者がいます。 ここで対応しなければならない設計上の問題は、 指向性、 多重度、 コレクション動作です。

1.2.2. 単方向 Set ベース関連

イベントのコレクションを Person クラスに追加すると、 Person#getEvents を呼び出して明示的なクエリを実行しなくても特定の人物に対するイベントを簡単にナビゲートすることができます。 複数値の関連は、 Java コレクションフレームワークのコントラクトの 1 つによって示されます。 この例ではコレクションに重複する要素がなく、 順序付けは関係ないため、 java.util.Set を選択しています。
public class Person {

    private Set events = new HashSet();

    public Set getEvents() {
        return events;
    }

    public void setEvents(Set events) {
        this.events = events;
    }
}
この関連をマッピングする前に、 逆側を考慮してみましょう。 両方向よりナビゲート可能にしたい場合は、 このまま単方向にするか Event 上に別のコレクションを作成することができます。 しかし、 機能的な観点から見ると、 これは必要ではありません。 明示的なクエリを実行して常に特定イベントの参加者を読み取ることができます。 これは設計者が自由に選択することができますが、 関連の多重度については明確です。 両側に 「多く」 の値があることを 「多対多」 関連と呼びます。 そのため、 Hibernate の多対多マッピングを使用します。
<class name="Person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="native"/>
    </id>
    <property name="age"/>
    <property name="firstname"/>
    <property name="lastname"/>

    <set name="events" table="PERSON_EVENT">
        <key column="PERSON_ID"/>
        <many-to-many column="EVENT_ID" class="Event"/>
    </set>

</class>
Hibernate は多様なコレクションマッピングをサポートしていますが、 最も一般的なのが set です。 多対多関連 (または n:m エンティティリレーションシップ) には、 関連テーブルが必要です。 このテーブルの各行は、 人物とイベント間のリンクを表します。 テーブル名は set 要素の table 属性を使用して宣言されます。 関連の識別子列名は、 人物側では key 要素、 イベント側では many-to-manycolumn 属性で定義されます。 Hibernate にコレクションにおけるオブジェクトのクラス (参照コレクションの逆側のクラス) を伝える必要もあります。
このマッピングのデータベーススキーマは以下のようになります。
    _____________        __________________
   |             |      |                  |       _____________
   |   EVENTS    |      |   PERSON_EVENT   |      |             |
   |_____________|      |__________________|      |    PERSON   |
   |             |      |                  |      |_____________|
   | *EVENT_ID   | <--> | *EVENT_ID        |      |             |
   |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  |
   |  TITLE      |      |__________________|      |  AGE        |
   |_____________|                                |  FIRSTNAME  |
                                                  |  LASTNAME   |
                                                  |_____________|

1.2.3. 関連を機能させる

EventManager の新しいメソッドで人物とイベントを結び付けましょう。
    private void addPersonToEvent(Long personId, Long eventId) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();

        Person aPerson = (Person) session.load(Person.class, personId);
        Event anEvent = (Event) session.load(Event.class, eventId);
        aPerson.getEvents().add(anEvent);

        session.getTransaction().commit();
    }
PersonEvent をロードした後、 普通のコレクションメソッドを使ってコレクションを変更します。 update()save() への明示的な呼び出しはありません。 Hibernate は、 コレクションが変更されたことや更新が必要なことを自動的に検出します。 これは自動ダーティチェック と呼ばれます。 オブジェクトの名前や日付プロパティを変更すると、 このチェックを試すことができます。 「永続」ステート (特定の Hibernate の org.hibernate.Session にバインドされている状態) である限り、 Hibernate は変更を監視し、 ライトビハインドで SQL を実行します。 通常、 作業単位の最後でのみ行われるデータベースでメモリステートを同期化するプロセスは「フラッシング」 と呼ばれます。 このコードでは、 作業単位はデータベーストランザクションのコミットまたはロールバックで終了します。
異なる作業単位で人物とイベントをロードすることもできます。 また、 永続ステートでない場合に org.hibernate.Session 外部のオブジェクトを変更することも可能です (以前永続状態であった場合、 ステートは「分離 (detached)」と呼ばれます)。 分離されている時でもコレクションを変更することが可能です。
    private void addPersonToEvent(Long personId, Long eventId) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();

        Person aPerson = (Person) session
                .createQuery("select p from Person p left join fetch p.events where p.id = :pid")
                .setParameter("pid", personId)
                .uniqueResult(); // Eager fetch the collection so we can use it detached
        Event anEvent = (Event) session.load(Event.class, eventId);

        session.getTransaction().commit();

        // End of first unit of work

        aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached

        // Begin second unit of work

        Session session2 = HibernateUtil.getSessionFactory().getCurrentSession();
        session2.beginTransaction();
        session2.update(aPerson); // Reattachment of aPerson

        session2.getTransaction().commit();
    }
update を呼び出すと、 新しい作業単位へバインドして分離オブジェクトを再び永続化します。 そのため分離状態の時に行われた変更をデータベースに保存することができます。 エンティティオブジェクトのコレクションに対して行われた変更 (追加や削除) はすべて保存の対象となります。
この例では無意味ですが、 これは独自のアプリケーションに取り入れることができる重要な概念です。 最後に EventManager の main メソッドへ新しいアクションを追加し、 コマンドラインから呼び出してください。 人物とイベントの識別子が必要な場合は save() メソッドが識別子を返します (識別子を返すには以前のメソッドの一部を変更しなければならない場合があります)。
        else if (args[0].equals("addpersontoevent")) {
            Long eventId = mgr.createAndStoreEvent("My Event", new Date());
            Long personId = mgr.createAndStorePerson("Foo", "Bar");
            mgr.addPersonToEvent(personId, eventId);
            System.out.println("Added person " + personId + " to event " + eventId);
        }
これは同等に重要な 2 つのクラスである 2 つのエンティティ間における関連の例です。 前述通り、 intjava.lang.String など、 通常 「比較的重要でない」 別のクラスや型が典型的なモデルに存在します。 これらのクラスは 「値型」 と呼ばれ、 値型のインスタンスは独自のアイデンティティを持たず、 エンティティ間で共有されません。 同じ名前の人物が 2 人存在しても、 2 人は同じ firstname オブジェクトを参照しません。 値型は JDK のみにありませんが、 Address クラスや MonetaryAmount クラスなどの依存クラスを記述することが可能です。 実際に、 Hibernate のアプリケーションではすべての JDK クラスが値型として考慮されます。
値型のコレクションを設計することもできます。 これは他のエンティティへの参照のコレクションとは概念的に異なりますが、 Java ではほぼ同様に見えます。

1.2.4. 値のコレクション

電子メールアドレスのコレクションを Person エンティティに追加してみましょう。これは、 java.lang.String インスタンスの java.util.Set として表されます。
    private Set emailAddresses = new HashSet();

    public Set getEmailAddresses() {
        return emailAddresses;
    }

    public void setEmailAddresses(Set emailAddresses) {
        this.emailAddresses = emailAddresses;
    }
Set のマッピングは次の通りです。
        <set name="emailAddresses" table="PERSON_EMAIL_ADDR">
            <key column="PERSON_ID"/>
            <element type="string" column="EMAIL_ADDR"/>
        </set>
以前のマッピングと比較して異なる点は、 element 部分の使い方です。 element の部分は、 コレクションに他のエンティティへの参照が含まれず、 要素が値型のコレクション (この例では string 型) であることを Hibernate に伝えます。 名前が小文字の場合、 Hibernate マッピング型かコンバーターであることが分かります。 ここでも、 set 要素の table 属性がコレクションのテーブル名を決定します。 key 要素はコレクションテーブルの外部キー列名を定義します。 element 要素の column 属性は、 電子メールアドレスの値が実際に保存される列名を定義します。
更新されたスキーマは次の通りです。
  _____________        __________________
 |             |      |                  |       _____________
 |   EVENTS    |      |   PERSON_EVENT   |      |             |       ___________________
 |_____________|      |__________________|      |    PERSON   |      |                   |
 |             |      |                  |      |_____________|      | PERSON_EMAIL_ADDR |
 | *EVENT_ID   | <--> | *EVENT_ID        |      |             |      |___________________|
 |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  | <--> |  *PERSON_ID       |
 |  TITLE      |      |__________________|      |  AGE        |      |  *EMAIL_ADDR      |
 |_____________|                                |  FIRSTNAME  |      |___________________|
                                                |  LASTNAME   |
                                                |_____________|
コレクションテーブルの主キーは、 両列を使った複合キーであることが分かります。 これは、 人物ごとに電子メールアドレスを重複できないことを意味し、 Java のセットに要求されるセマンティックとなります。
人物とイベントをリンクした時のように、 このコレクションに要素を追加してみましょう。 Java の同じコードになります。
    private void addEmailToPerson(Long personId, String emailAddress) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();

        Person aPerson = (Person) session.load(Person.class, personId);
        // adding to the emailAddress collection might trigger a lazy load of the collection
        aPerson.getEmailAddresses().add(emailAddress);

        session.getTransaction().commit();
    }
今回は、 fetch クエリを使用してコレクションを初期化しませんでした。 SQL ログを監視し、 eager フェッチで最適化してみます。

1.2.5. 双方向関連

次に双方向関連をマッピングします。 Java で両側から人物とイベントを関連付けします。 データベーススキーマは変わらないため、 多対多の多重度が維持されます。

注記

リレーショナルデータベースはネットワークプログラミング言語よりも柔軟性があり、ナビゲーションの方向が必要ありません。そのため、可能な方向でデータの閲覧や読み出しが可能です。
最初に Event クラスに参加者のコレクションを追加します。
    private Set participants = new HashSet();

    public Set getParticipants() {
        return participants;
    }

    public void setParticipants(Set participants) {
        this.participants = participants;
    }
Event.hbm.xml でこちら側の関連をマップします。
<set name="participants" table="PERSON_EVENT" inverse="true">
  <key column="EVENT_ID"/>
  <many-to-many column="PERSON_ID" class="org.hibernate.tutorial.domain.Person"/>
</set>
これらは両マッピングドキュメントの普通の set マッピングになります。keymany-to-many のカラム名が、 両方のマッピングドキュメントで入れ替えられていることに注目してください。ここで最も重要な追加項目は、Event のコレクションマッピングの set 要素にある inverse="true" 属性です。
これは、 2 つエンティティの関連に関する情報が必要な場合に、Hibernate は逆側の Person クラスを確認するべきであることを意味しています。 2 つのエンティティ間の双方向リンクがどのように作成されたか確認すると、 理解しやすいはずです。

1.2.6. 双方向リンクを機能させる

最初に、Hibernate は通常の Java のセマンティクスに影響を与えないことを念頭に置いてください。単方向の例ではどのように PersonEvent 間のリンクを作成したでしょうか。Event のインスタンスを Person のインスタンスであるイベントの参照のコレクションに追加しました。 このリンクを双方向にする場合は、逆側で同様の処理を行うため、 Person の参照を Event のコレクションに追加します。 このように 「両側でリンクを設定」 するプロセスは双方向リンクでは絶対に必要となります。
両側を正しく設定するため、 開発者の多くは保守的にプログラムを作成し、リンク管理メソッドを作成します (Person 内など)。
    protected Set getEvents() {
        return events;
    }

    protected void setEvents(Set events) {
        this.events = events;
    }

    public void addToEvent(Event event) {
        this.getEvents().add(event);
        event.getParticipants().add(this);
    }

    public void removeFromEvent(Event event) {
        this.getEvents().remove(event);
        event.getParticipants().remove(this);
    }
これでコレクションの get および set メソッドが保護されました。 これにより、 同じパッケージやサブクラスのクラスがメソッドへアクセスできるようにし、 それ以外のクラスが直接コレクションを変更できないようにします。 コレクションに対するこの手順を逆側でも行います。
inverse マッピング属性はどうするのでしょうか。 双方向リンクは Java にとって両側で参照を正しく設定することでしかありません。 しかし、 Hibernate は SQ Lの INSERT ステートメントと UPDATE ステートメントを正しく手配するための十分な情報を持っていません (制約違反を防ぐため)。 片側を関連付けるため、 逆側の「ミラー」として考慮するよう inverse は Hibernate に伝えます。 方向性ナビゲーションモデルを SQL データベーススキーマに変換する際に Hibernate が問題を解決するにはこれのみが必要となります。 ルールは明確です。 すべての双方向関連は片側を inverse とする必要があります。一対多関連では多の側を inverse とし、 多対多関連ではどちらかを inverse とする必要があります。

1.3. パート3 - EventManager Web アプリケーション

Hibernate の Web アプリケーションは、 スタンドアロンのアプリケーションのように SessionTransaction を使用します。しかし、一般的なパターンも一部便利です。 ここで EventManagerServlet を作成します。 このサーブレットは、 データベースに格納した全イベントを一覧表示でき、 新しいイベントを入力するため HTML フォームを提供します。

1.3.1. 基本的な Servlet の記述

最初に、 基本的なプロセスサーブレットを作成する必要があります。 サーブレットは HTTP の GET リクエストのみを処理するため、 doGet() メソッドのみを実装します。
package org.hibernate.tutorial.web;

// Imports

public class EventManagerServlet extends HttpServlet {

    protected void doGet(
            HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {

        SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" );

        try {
            // Begin unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction();

            // Process request and render page...

            // End unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit();
        }
        catch (Exception ex) {
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback();
            if ( ServletException.class.isInstance( ex ) ) {
                throw ( ServletException ) ex;
            }
            else {
                throw new ServletException( ex );
            }
        }
    }

}
このサーブレットを src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java として保存します。
ここで適用されるパターンは session-per-request (リクエスト毎のセッション) と呼ばれます。 サーブレットがリクエストを受け取ると、 SessionFactorygetCurrentSession() への最初の呼び出しにより、 新しい Hibernate の Session が開かれます。 その後、 データベースのトランザクションが開始されます。 データの読み書きに関わらず、 すべてのデータアクセスはトランザクション内で発生します。 アプリケーションで自動コミットを使用しないでください。
全データベース操作で新しい Hibernate Session を使用 しないでください 。全てのリクエストで機能する、1つの Hibernate Session を使用してください。自動的に現在の Java スレッドにバインドされるので、getCurrentSession() を使用してください。
次に、 リクエストの可能なアクションは処理され、 HTML の応答がレンダリングされます。 これについては後ほど説明します。
最後に、 処理とレンダリングが完了した時に作業単位を終了します。 処理中やレンダリング中に問題が発生した場合、 例外がスローされ、 データベーストランザクションがロールバックされます。 これにより、 session-per-request パターンが完了します。 全てのサーブレットにトランザクション境界のコードを書く代わりに、 サーブレットフィルタに記述することも可能です。 Open Session in View と呼ばれるこのパターンについては、 Hibernate の Web サイトや Wiki を参照してください。 サーブレットではなく JSP でビューのレンダリングを考慮している場合、 すぐにこのパターンについての情報が必要になるでしょう。

1.3.2. 処理とレンダリング

リクエストの処理とページのレンダリングを実装します。
        // Write HTML header
        PrintWriter out = response.getWriter();
        out.println("<html><head><title>Event Manager</title></head><body>");

        // Handle actions
        if ( "store".equals(request.getParameter("action")) ) {

            String eventTitle = request.getParameter("eventTitle");
            String eventDate = request.getParameter("eventDate");

            if ( "".equals(eventTitle) || "".equals(eventDate) ) {
                out.println("<b><i>Please enter event title and date.</i></b>");
            }
            else {
                createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
                out.println("<b><i>Added event.</i></b>");
            }
        }

        // Print page
       printEventForm(out);
       listEvents(out, dateFormatter);

       // Write HTML footer
       out.println("</body></html>");
       out.flush();
       out.close();
Java と HTML が混在するこのコーディングスタイルは、より複雑なアプリケーションでは拡張できないでしょう。本チュートリアルでは基本的な Hibernate の概念のみを説明しています。 コードは HTML のヘッダーとフッターを出力します。 このページ内には、イベントエントリの HTML フォームとデータベースの全イベントのリストが出力されます。 最初のメソッドは大変単純なメソッドで、 HTML のみを出力します。
    private void printEventForm(PrintWriter out) {
        out.println("<h2>Add new event:</h2>");
        out.println("<form>");
        out.println("Title: <input name='eventTitle' length='50'/><br/>");
        out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>");
        out.println("<input type='submit' name='action' value='store'/>");
        out.println("</form>");
    }
listEvents() メソッドは、現在のスレッドに結びつく Hibernate の Session を使用して、クエリを実行します。
    private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {

        List result = HibernateUtil.getSessionFactory()
                .getCurrentSession().createCriteria(Event.class).list();
        if (result.size() > 0) {
            out.println("<h2>Events in database:</h2>");
            out.println("<table border='1'>");
            out.println("<tr>");
            out.println("<th>Event title</th>");
            out.println("<th>Event date</th>");
            out.println("</tr>");
            Iterator it = result.iterator();
            while (it.hasNext()) {
                Event event = (Event) it.next();
                out.println("<tr>");
                out.println("<td>" + event.getTitle() + "</td>");
                out.println("<td>" + dateFormatter.format(event.getDate()) + "</td>");
                out.println("</tr>");
            }
            out.println("</table>");
        }
    }
最後に、 store アクションが createAndStoreEvent() メソッドを呼び出します。このメソッドでも現在のスレッドの Session を利用します。
    protected void createAndStoreEvent(String title, Date theDate) {
        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);

        HibernateUtil.getSessionFactory()
                .getCurrentSession().save(theEvent);
    }
これでサーブレットが完成しました。 サーブレットへのリクエストは、 1 つの SessionTransaction で処理されます。 スタンドアロンアプリケーションの最初のように、 Hibernate は自動的にこれらのオブジェクトを現在の実行スレッドにバインドすることができます。 これにより、 開発者が自由にコードをレイヤー分けでき、 好きな方法で SessionFactory へのアクセスができるようになります。 通常、 開発者はより洗練されたデザインを使用して、 データアクセスコードをデータアクセスオブジェクトに移動するでしょう (DAO パターン)。 これ以外の例は、 Hibernate の Wiki を参照してください。

1.3.3. デプロイとテスト

テスト向けにこのアプリケーションをデプロイするには、 WAR (Web ARchive) を作成する必要があります。 最初に WAR 記述子を src/main/webapp/WEB-INF/web.xml として定義しなければなりません。
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name>Event Manager</servlet-name>
        <servlet-class>org.hibernate.tutorial.web.EventManagerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Event Manager</servlet-name>
        <url-pattern>/eventmanager</url-pattern>
    </servlet-mapping>
</web-app>
ビルドとデプロイを実行するには、プロジェクトディレクトリの mvn package を呼び出し、hibernate-tutorial.war ファイルを $JBOSS_HOME/server/$CONFIG/deployディレクトリにコピーします。
一度デプロイして JBoss が起動すれば、http://localhost:8080/hibernate-tutorial/eventmanager でアプリケーションへアクセスします。($JBOSS_HOME/server/$CONFIG/log/server.log の)サーバーログを見て、最初のリクエストが利用中のサーブレットをヒットすると(HibernateUtilにある静的初期化子が呼び出されると)Hibernate が初期化されることを確認し、例外が発生した場合は詳細出力を取得してください。

1.4. 要約

本チュートリアルでは簡単なスタンドアロンの Hibernate アプリケーションと小規模の Web アプリケーションを記述するための基本を紹介しました。 その他のチュートリアルは Hibernate の Web サイト をご覧ください。

第2章 アーキテクチャ

2.1. 概観

下図は Hibernate アーキテクチャのハイレベルビューになります。
本書の範囲では、使用可能なランタイムアーキテクチャすべての詳細なビューは取り上げません。Hibernate は柔軟なため、複数のアプローチをサポートしています。ここでは、「最低限」のアーキテクチャと「包括的」なアーキテクチャの 2 つの極端な例を説明します。
下図は Hibernate がデータベースと設定データを使用して永続サービスや永続オブジェクトをアプリケーションに提供する方法を示しています。
「最低限」のアーキテクチャはアプリケーションが独自の JDBC 接続を提供し、独自のトランザクションを管理します。この方法では、Hibernate API の最低限のサブセットが使用されます。
「包括的」なアーキテクチャは、基盤となる JDBC や JTA の API から離れてアプリケーションを抽象化し、 Hibernate が詳細を管理できるようにします。
図内で示されているオブジェクトの定義は次のようになります。
SessionFactory (org.hibernate.SessionFactory)
1 つのデータベースに対するコンパイルされたマッピングのスレッドセーフで不変のキャッシュです。Session のファクトリであり、ConnectionProvider のクライアントです。SessionFactory は、プロセスやクラスタレベルのトランザクション間で再利用可能なデータの任意 (2 次) キャッシュを保持することができます。
Session (org.hibernate.Session)
アプリケーションと永続ストアとの会話を表す、シングルスレッドで短命のオブジェクトです。JDBC コネクションをラッピングする Transaction のファクトリです。Session は、オブジェクトグラフをナビゲーションする時、あるいは識別子でオブジェクトをルックアップする時に使用される永続オブジェクト(必須)の1 次キャッシュを保持します。
永続オブジェクトとコレクション
永続ステートとビジネス関数を持つ、短命で単一スレッドのオブジェクトです。 通常の JavaBean や POJO である場合もあります。1つの Session のみに関連付けされます。Session が閉じられると分離され、すべてのアプリケーション層で使用可能です (プレゼンテーションへまたはプレゼンテーションから直接データ転送オブジェクトとしてなど)。
一時オブジェクトやコレクションおよび分離オブジェクトやコレクション
現在、Session と関連していない、永続クラスのインスタンスです。アプリケーションによってインスタンス化され、まだ永続化されていない場合や、閉じられた Session によってインスタンス化されている場合があります。
トランザクション (org.hibernate.Transaction)
(オプション) アトミックな作業単位を指定するためにアプリケーションが使用する単一スレッドで短命なオブジェクトです。基盤となる JDBC、JTA、CORBA トランザクションよりアプリケーションを抽象化します。場合によっては Session が複数の トランザクション にわたることがあります。基盤となる API やトランザクション の使用に拘らずトランザクション境界は常に必須となります。
ConnectionProvider (org.hibernate.connection.ConnectionProvider)
(オプション) JDBC 接続のファクトリおよびプールです。基盤となる DatasourceDriverManager よりアプリケーションを抽象化します。アプリケーションには公開されませんが、開発者が拡張および/または実装することは可能です。
TransactionFactory (org.hibernate.TransactionFactory)
(オプション) Transaction インスタンスのファクトリです。アプリケーションには公開されませんが、開発者が拡張および/または実装することは可能です。
拡張インターフェース (Extension Interface)
永続層の挙動をカスタマイズできるようにするため、Hibernate には多くのオプションの拡張インタフェースが用意されています。詳細は API ドキュメントを参照してください。
「最低限」のアーキテクチャでは、アプリケーションは TransactionTransactionFactoryConnectionProvider の API を迂回して JTA や JDBC と直接通信します。

2.2. インスタンスのステート

永続クラスのインスタンスは、3 つのステートの 1 つとなります。これらのステートは 永続コンテキスト の関係によって定義されます。Hibernate の Session オブジェクトが永続コンテキストです。3 つのステートは次のようになります。
transient (一時)
このステートのインスタンスは永続インスタンスに関連付けられていません。 また、永続 ID や主キーの値を持っていません。
persistent (永続)
このステートのインスタンスは現在永続コンテキストに関連付けられています。永続 ID (主キーの値) を持ち、データベースに対応する行を持つことができます。特定の永続コンテキストにおいてHibernate は、オブジェクトのインメモリの場所に関し、永続 ID が Java ID と同等であることを保証します。
detached (分離)
このステートのインスタンスは、過去に永続コンテキストに関連付けられていましたが、永続コンテキストが閉じられたか、インスタンスが他のプロセスによってシリアライズされています。永続 ID を持ち、データベースに対応する行を持つことができます。分離インスタンスでは、Hibernate は 永続 ID と Java ID の関係を保証しません。

2.3. JMX との統合

JMX は Java コンポーネント管理の J2EE 標準です。JMX 標準サービスより Hibernate を管理することができます。ディストリビューションの中に org.hibernate.jmx.HibernateService という MBean 実装が用意されています。
JBoss Application Server 上に Hibernate を JMX サービスとしてデプロイする方法の例は、JBoss ユーザーガイドを参照してください。JMX を使用してデプロイすると、JBoss AS は次の機能も提供します。
  • セッション管理: Hibernate の Session のライフサイクルは、自動的に JTA トランザクションの範囲にバインドすることができます。そのため、手作業で Session を開閉する必要がなくなり、この作業は JBoss EJB インターセプタによって行われます。また、コードのトランザクション境界を心配する必要もありません (移植可能な永続層を記述したい場合は、 オプションの Hibernate Transaction API を使用してください)。HibernateContext を呼び出して Session にアクセスします。
  • HAR デプロイメント: Hibernate SessionFactory の通常の設定オプションをすべてサポートするため、EAR ファイルか SAR ファイルの JBoss サービスデプロイメント記述子を使用して Hibernate JMX サービスはデプロイされます。しかし、デプロイメント記述子の全マッピングファイルに名前を付ける必要があります。オプションの HAR デプロイメントを使用すると、JBoss は HAR ファイルの全マッピングファイルを自動的に検出します。
これらのオプションについての詳細な情報は、JBoss AS ユーザーガイドを参考にしてください。
JMX サービスとして利用できる機能に、ランタイム時の Hibernate 統計があります。詳細は 「Hibernate 統計」 を参照してください。

2.4. JCA サポート

Hibernate は JCA コネクタとしても設定できます。詳細については、Web サイトを参照してください。現在、Hibernate JCA サポートは開発段階ですので注意してください。

2.5. コンテキストのセッション

Hibernate を使用するアプリケーションの多くに、コンテキストの範囲全般を通じてセッションが有効になるある種の「コンテキスト」のセッションが必要となります。しかし、通常アプリケーションごとにコンテキストを構成するものの定義は異なります。さらに、コンテキストにより、定義する「現在」の概念の範囲が異なります。バージョン 3.0 以前の Hibernate を使用するアプリケーションは、自作の ThreadLocal ベースのコンテキストセッションや HibernateUtil などのヘルパークラス、プロキシやインターセプションベースのコンテキストセッションを提供した Spring や Pico などのサードパーティフレームワークを使用していました。
バージョン 3.0.1 より、Hibernate には SessionFactory.getCurrentSession() メソッドが加わりました。当初は、JTA トランザクションを使用し、JTA トランザクションが現在のセッションの範囲とコンテキストを両方定義することが前提となっていました。多くのスタンドアロン JTA TransactionManager 実装が成熟の段階に入っているため、J2EE コンテナへデプロイされるか否かに関わらずアプリケーションは JTA トランザクション管理を使用すべきです。これにより、使用する必要があるのは JTA ベースのコンテキストセッションのみとなります。
バージョン 3.1 より SessionFactory.getCurrentSession() 背後の処理がプラグ可能になりました。また、拡張インターフェース org.hibernate.context.CurrentSessionContext と設定パラメータ hibernate.current_session_context_class が新たに追加され、現在のセッションを定義する範囲とコンテキストがプラグ可能になりました。
org.hibernate.context.CurrentSessionContext インターフェースの詳細な規約については Javadoc を参照してください。このインターフェースは、実装が現在のコンテキストセッションの追跡に関与する単一のメソッド currentSession() を定義します。Hibernate には、このインターフェースの追加設定不要な 3 つの実装が含まれています。
  • org.hibernate.context.JTASessionContext: JTA トランザクションにより現在のセッションが追跡され、範囲が決定されます。この処理は、以前の JTA のみの方法と全く同じになります。詳細は Javadoc を参照してください。
  • org.hibernate.context.ThreadLocalSessionContext: 実行スレッドによって現在のセッションが追跡されます。詳細は Javadoc を参照してください。
  • org.hibernate.context.ManagedSessionContext: 実行スレッドによって現在のセッションが追跡されますが、ユーザーがこのクラス上の静的メソッドを用いて Session インスタンスをバインドまたはアンバインドしなければなりません。この実装は Session の開閉やフラッシュを行いません。
最初の 2 つの実装は、「1 セッション 1 データベーストランザクション」プログラミングモデルを提供します。これは リクエスト毎のセッション (session-per-request) とも呼ばれます。Hibernate セッションの開始と終了は、 データベーストランザクションの期間によって定義されます。 JTA を使用せず、 通常の JSE でプログラムを用いたトランザクション境界を使用する場合、Hibernate Transaction API を使用して基盤のトランザクションシステムをコードから見えないようにしてください。JTA を使用する場合、JTA インターフェースを使用してトランザクションの境界を設定することができます。CMT をサポートする EJB を実行する場合、トランザクション境界は宣言的に定義されるため、コードにトランザクションやセッションの境界を決定する操作は必要ありません。詳細やコード例は 11章トランザクションと並行性 を参照してください。
hibernate.current_session_context_class 設定パラメータは、org.hibernate.context.CurrentSessionContext のどの実装を使うべきかを指定します。下位互換性のため、このパラメータが設定されず org.hibernate.transaction.TransactionManagerLookup が設定されていた場合、Hibernate は org.hibernate.context.JTASessionContext を使うことに注意してください。通常このパラメータの値には利用する実装クラスを指定するだけです。しかし、カスタマイズなしに利用可能な実装3つについては、「jta」、「thread」、「managed」というそれぞれの省略名も用意されています。

第3章 設定

Hibernate はさまざまな環境で動作するように設計されているため、 多くの設定パラメータが存在します。 ほとんどの設定パラメータは妥当なデフォルト値を持ち、 Hibernate の etc/ には、 さまざまなオプションを表示するサンプルの hibernate.properties ファイルがあります。 このサンプルファイルをクラスパス上に置き、 必要に応じてカスタマイズします。

3.1. プログラムによる設定

org.hibernate.cfg.Configuration のインスタンスは、 アプリケーションの Java 型から SQL データベースへのマッピングをすべて表します。 org.hibernate.cfg.Configuration は不変の org.hibernate.SessionFactory をビルドするために使用されます。 マッピングは複数の XML マッピングファイルよりコンパイルされます。
org.hibernate.cfg.Configuration インスタンスを取得するには、 直接インスタンス化し、 XML マッピングドキュメントを指定します。 マッピングファイルがクラスパスにある場合は、 addResource() を使用します。 例は次の通りです。
Configuration cfg = new Configuration()
    .addResource("Item.hbm.xml")
    .addResource("Bid.hbm.xml");
マップされたクラスを指定し、 Hibernate にマッピングドキュメントを検索させる方法もあります。
Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);
Hibernate は、 クラスパスにある /org/hibernate/auction/Item.hbm.xml/org/hibernate/auction/Bid.hbm.xml というマッピングファイルを検索します。 この方法により 、ハードコードされたファイル名を取り除きます。
また、 org.hibernate.cfg.Configuration は設定プロパティを設定できるようにします。 例は次の通りです。
Configuration cfg = new Configuration()
    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class)
    .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
    .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
    .setProperty("hibernate.order_updates", "true");
Hibernate に設定プロパティを渡す方法はこれだけではありません。 他にも次のような方法があります。
  1. java.util.Properties のインスタンスを Configuration.setProperties() に渡します。
  2. クラスパスのルートディレクトリに hibernate.properties という名前のファイルを置きます。
  3. java -Dproperty=value を使用して System プロパティを設定します。
  4. hibernate.cfg.xml<property> 要素を追加します (これについては後ほど説明します)。
すぐに開始したい場合は hibernate.properties が最も簡単な方法になります。
org.hibernate.cfg.ConfigurationSessionFactory の作成後に破棄される起動時のオブジェクトとなります。

3.2. SessionFactory を取得する

org.hibernate.cfg.Configuration によってすべてのマッピングが解析されると、 アプリケーションは org.hibernate.Session インスタンスのファクトリを取得する必要があります。すべてのアプリケーションスレッドにより共有されるよう、このファクトリは設計されています。
SessionFactory sessions = cfg.buildSessionFactory();
Hibernate では、アプリケーションは複数の org.hibernate.SessionFactory をインスタンス化することができます。これは、複数のデータベースを使用する場合に便利です。

3.3. JDBC 接続

org.hibernate.SessionFactoryが JDBC 接続を作成しプーリングすることが推奨されます。 この場合、 次のように簡単に org.hibernate.Session を開くことができます。
Session session = sessions.openSession(); // open a new Session
データベースへのアクセスが必要となるタスクを開始すると、 プールより JDBC 接続が取得されます。
その前に、 JDBC 接続のプロパティを Hibernate に渡す必要があります。 Hibernate のプロパティ名とセマンティックはすべて org.hibernate.cfg.Environment クラス上で定義されます。 JDBC 接続で最も重要となる設定は次の通りです。
次のプロパティを設定すると、 Hibernate は java.sql.DriverManager を使用して接続を取得し、 プーリングします。

表3.1 Hibernate JDBC プロパティ

プロパティ名 目的
hibernate.connection.driver_class JDBC ドライバクラス
hibernate.connection.url JDBC の URL
hibernate.connection.username データベースユーザー
hibernate.connection.password データベースユーザーのパスワード
hibernate.connection.pool_size プーリングされた接続の最大数
Hibernate 独自の接続プールアルゴリズムは非常に初歩的なものです。 これは、 ユーザーがすぐ Hibernate を使用できるようにするためのアルゴリズムで、 実稼働システムやパフォーマンステスト向けのものではありません。 最良のパフォーマンスや安定性を実現するには、 サードパーティーのプールを使用してください。 Hibernate の内部プールを無効にするには、 hibernate.connection.pool_size プロパティを接続プール固有の設定に置き換えます。 c3p0 を使用する場合の例は次のようになります。
C3P0 はオープンソースの JDBC 接続プールで、 Hibernate の lib ディレクトリにあります。 hibernate.c3p0.* プロパティを設定すると、 Hibernate は org.hibernate.connection.C3P0ConnectionProvider を接続プーリングに使用します。 Proxool を使用したい場合は、 パッケージ化された hibernate.properties と Hibernate の Web サイトを参照してください。
以下は c3p0 の hibernate.properties ファイルの例になります。
hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
アプリケーションサーバー内で使用する場合、 Hibernate を設定し、 JNDI に登録されているアプリケーションサーバーの javax.sql.Datasource より接続を取得するようにします。 最低でも次のプロパティを 1 つ設定する必要があります。

表3.2 Hibernate データソースプロパティ

プロパティ名 目的
hibernate.connection.datasource データソースの JNDI 名
hibernate.jndi.url JNDI プロバイダの URL (オプション)
hibernate.jndi.class JNDI InitialContextFactory のクラス (オプション)
hibernate.connection.username データベースユーザ (オプション)
hibernate.connection.password データベースユーザのパスワード (オプション)
次は、 アプリケーションサーバーが提供する JNDI データソースの hibernate.properties ファイルの例になります。
hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
    org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
JNDI データソースから取得した JDBC コネクションは、アプリケーションサーバーのコンテナ管理トランザクションに自動的に参加します。
任意の接続プロパティを提供するには、 hibernate.connnection を接続プロパティ名の前に追加します。 例えば、 hibernate.connection.charSet を使用した場合、 charSet 接続プロパティを指定できます。
JDBC 接続を取得するため独自のプラグイン戦略を定義するには、 org.hibernate.connection.ConnectionProvider インターフェースを実装し、 hibernate.connection.provider_class プロパティよりカスタム実装を指定します。

3.4. オプションの設定プロパティ

ランタイム時に Hibernate の挙動を制御する他のプロパティも複数あります。 これらのプロパティはすべて任意で、 妥当なデフォルト値を持っています。

警告

これらのプロパティの一部はシステムレベルのみのプロパティです。 システムレベルのプロパティは、 java -Dproperty=value または hibernate.properties でのみ設定可能で、 上記の他の方法では設定できません。

表3.3 Hibernate 設定プロパティ

プロパティ名 目的
hibernate.dialect 特定のリレーショナルデータベースに対して最適化された SQL を Hibernate が生成できるようにする、 Hibernate org.hibernate.dialect.Dialect のクラス名です。
例: full.classname.of.Dialect
ほとんどの場合で、 Hibernate は JDBC ドライバによって返された JDBC metadata を基に適切な org.hibernate.dialect.Dialect 実装を選択することができます。
hibernate.show_sql 発行されたすべての SQL をコンソールに出力します。これはログカテゴリの org.hibernate.SQLdebug を設定する方法の代替手段です。
例: true | false
hibernate.format_sql ログとコンソールで SQL のプリティプリントを行います。
例: true | false
hibernate.default_schema 非修飾テーブル名を生成された SQL のスキーマやテーブル空間で修飾します。
例: SCHEMA_NAME
hibernate.default_catalog 生成された SQL のカタログで非修飾テーブル名を修飾します。
例: CATALOG_NAME
hibernate.session_factory_name 作成後、 org.hibernate.SessionFactory は JNDI でこの名前へ自動的にバインドされます。
例: jndi/composite/name
hibernate.max_fetch_depth 単一終端関連 (一対一、多対一) に対し、 外部結合によるフェッチツリーの最大の「深さ」を設定します。 0 を指定すると、 デフォルトの外部結合フェッチが無効になります。
例: 推奨される 0 から 3 までの値
hibernate.default_batch_fetch_size 関連の Hibernate バッチフェッチのデフォルトサイズを設定します。
例: 推奨される値は 4816 です。
hibernate.default_entity_mode この SessionFactory から開かれたすべてのセッションに対するエンティティ表示のデフォルトモードを設定します。
dynamic-mapdom4jpojo
hibernate.order_updates 更新された項目の主キー値によって SQL の更新を順番付けするよう Hibernate を強制します。 これにより、 並行性の高いシステムにおけるトランザクションのデッドロックが軽減されます。
例: true | false
hibernate.generate_statistics 有効の場合、 Hibernate はパフォーマンスチューニングに有効な統計情報を収集します。
例: true | false
hibernate.use_identifier_rollback 有効の場合、オブジェクトが削除されたときに識別子プロパティをリセットし、デフォルト値にしたものを生成します。
例: true | false
hibernate.use_sql_comments 有効の場合、 SQL 内にコメントを生成します。これはデバックを容易にします。デフォルトの値は false です。
例: true | false

表3.4 Hibernate JDBC とコネクションプロパティ

プロパティ名 目的
hibernate.jdbc.fetch_size 値が0でない場合、 JDBC フェッチサイズを決定します ( Statement.setFetchSize() を呼びます)。
hibernate.jdbc.batch_size 値が0でない場合、 Hibernate が JDBC2 バッチ更新を使用します。
例: 推奨される 5 から 30 までの値
hibernate.jdbc.batch_versioned_data JDBC ドライバが executeBatch() より正しい行数を返す場合は、 このプロパティを true に設定します。 通常、 このオプションを有効にすると安全です。 Hibernate は自動的にバージョン化されたデータにバッチ DML を使用します。 デフォルト値は false になります。
例: true | false
hibernate.jdbc.factory_class カスタム org.hibernate.jdbc.Batcher を選択します。 この設定プロパティはほとんどのアプリケーションには必要ありません。
例: classname.of.BatcherFactory
hibernate.jdbc.use_scrollable_resultset Hibernate による JDBC2 のスクロール可能な結果セットの使用を有効にします。 このプロパティはユーザーが提供する JDBC 接続を使用する場合のみ必要となります。 ユーザー提供による JDBC 接続を使用しない場合、 Hibernate は接続メタデータを使用します。
例: true | false
hibernate.jdbc.use_streams_for_binary JDBC に対しまたは JDBC より binaryserializable を読み書きする時にストリームを使用します。 システムレベルのプロパティです。
例: true | false
hibernate.jdbc.use_get_generated_keys 挿入の後にネーティブに生成されたキーを読み出すため、 JDBC3 PreparedStatement.getGeneratedKeys() の使用を有効にします。 JDBC3+ ドライバと JRE1.4+ を必要とし、 Hibernate の識別子ジェネレータに問題が発生する場合は false を設定します。 デフォルトでは、 設定メタデータを使用してドライバの能力を判断しようとします。
例: true|false
hibernate.connection.provider_class JDBC 接続を Hibernate に提供するカスタム org.hibernate.connection.ConnectionProvider のクラス名です。
例: classname.of.ConnectionProvider
hibernate.connection.isolation JDBC トランザクション分離レベルを設定します。 妥当な値は java.sql.Connection をチェックしてください。 データベースのほとんどはすべての分離レベルをサポートしておらず、 非標準の分離を追加で定義するデータベースもあります。
例: 1, 2, 4, 8
hibernate.connection.autocommit JDBC でプーリングされる接続の自動コミットを有効にします (非推奨)。
例: true | false
hibernate.connection.release_mode Hibernate が いつ JDBC 接続をリリースするか指定します。 デフォルトでは、 セッションが明示的に閉じられるか切断されるまで JDBC 接続が保持されます。 アプリケーションサーバーの JTA データソースの場合、 after_statement を使用して各 JDBC 呼び出しの後に積極的に接続をリリースします。 非 JTA 接続では、 after_transaction を使用して各トランザクションの最後に接続をリリースするとよいでしょう。 auto は JTA や CMT トランザクション戦略に対して after_statement を選択し、 JDBC トランザクション戦略に対して after_transaction を選択します。
例: auto (デフォルト) | on_close | after_transaction | after_statement
この設定は SessionFactory.openSession から返された Session のみに影響します。 SessionFactory.getCurrentSession より取得された Session では、 使用するために設定された CurrentSessionContext 実装がこれら Session の接続リリースモードを制御します。 詳細は「コンテキストのセッション」 を参照してください。
hibernate.connection.<propertyName> JDBC プロパティ <propertyName>DriverManager.getConnection() に渡します。
hibernate.jndi.<propertyName> プロパティ <propertyName> を JNDI InitialContextFactory に渡します。

表3.5 Hibernate キャッシュプロパティ

プロパティ名 目的
hibernate.cache.provider_class カスタム CacheProvider のクラス名です。
例: classname.of.CacheProvider
hibernate.cache.use_minimal_puts 書き込みを最小限にするために読み取りの頻度を増やし、 2 次キャッシュの操作を最適化します。 この設定はクラスタ化キャッシュで最も有用です。 Hibernate3 ではクラスタ化キャッシュ実装向けにデフォルトで有効になっています。
例: true|false
hibernate.cache.use_query_cache クエリキャッシュを有効にします。 各クエリをキャッシュ可能として設定する必要があります。
例: true|false
hibernate.cache.use_second_level_cache 2 次キャッシュを完全に無効にするため使用できます。 2 次キャッシュは <cache> マッピングを指定するクラスではデフォルトで有効になっています。
例: true|false
hibernate.cache.query_cache_factory カスタム QueryCache インターフェースのクラス名を指定します。デフォルトでは StandardQueryCache になります。
例: classname.of.QueryCache
hibernate.cache.region_prefix 二次キャッシュの領域名の接頭辞です。
例: prefix
hibernate.cache.use_structured_entries 二次キャッシュに格納するデータを、人が理解しやすいフォーマットにします。
例: true|false
hibernate.query.plan_cache_max_strong_references キャッシュで保持される強参照 (Strong reference) の最大数を設定します。
例: 128 (default)
hibernate.query.plan_cache_max_soft_references キャッシュで保持されるソフト参照 (Soft reference) の最大数を設定します。この値をInteger.MAX_VALUE に設定すると、5.1.1 以前のバージョンと同じ動作を複製します。
例: 2048 (default)

表3.6 Hibernate トランザクションプロパティ

プロパティ名 目的
hibernate.transaction.factory_class Hibernate Transaction API と一緒に使われる TransactionFactory のクラス名です。 (デフォルトでは JDBCTransactionFactory です)。
例: classname.of.TransactionFactory>
jta.UserTransaction アプリケーションサーバーから JTA UserTransaction を取得するために JTATransactionFactory に使われる JNDI 名です。
例: jndi/composite/name
hibernate.transaction. manager_lookup_class TransactionManagerLookup のクラス名です。 JTA 環境において、 JVM レベルのキャッシュを有効にする時や、 hilo ジェネレータが使用される時に必要となります。
例: classname.of.TransactionManagerLookup
hibernate.transaction. flush_before_completion 有効の場合、 トランザクションの completion フェーズの前に自動的にセッションをフラッシュします。 内蔵の自動セッションコンテキスト管理に適しています。 「コンテキストのセッション」 を参照してください。
例: true | false
hibernate.transaction. auto_close_session 有効の場合、 トランザクションの completion フェーズの後にセッションを自動的にクローズします。内蔵の自動セッションコンテキスト管理に適しています。 「コンテキストのセッション」 を参照してください。
例: true | false

表3.7 その他のプロパティ

プロパティ名 目的
hibernate. current_session_context_class 「現在の」 Session のスコーピングに対するカスタム戦略を提供します。 ビルトイン戦略に関する詳細は 「コンテキストのセッション」 を参照してください。
例: jta | thread | managed | custom.Class
hibernate.query.factory_class HQL パーサーの実装を選択します。
例: org.hibernate.hql.ast.ASTQueryTranslatorFactory または org.hibernate.hql.classic.ClassicQueryTranslatorFactory
hibernate.query.substitutions Hibernate クエリのトークンより SQL のトークンをマッピングするため使用します (トークンは関数やリテラル名になることがあります)。
例: hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC
hibernate.hbm2ddl.auto SessionFactory を生成された時に、 自動的にスキーマ DDL を有効にするか、 データベースにエクスポートします。 create-drop の場合、 SessionFactory が明示的に閉じられた時に、 データベーススキーマがドロップされます。
例: validate | update | create | create-drop
hibernate.cglib. use_reflection_optimizer ランタイム時のリフレクションの代わりに CGLIB の使用を有効にします (システムレベルのプロパティ)。 リフレクションはトラブルシューティングの時に役立つことがあります。 オプティマイザがオフになっている場合でも Hibernate は常に CGLIB を必要とします。 このプロパティは hibernate.cfg.xml に設定することができません。
例: true | false

3.4.1. SQL 方言

hibernate.dialect プロパティには、 常にデータベースの正しい org.hibernate.dialect.Dialect サブクラスを設定してください。方言を指定すると、Hibernate は上記一覧の他の一部プロパティに対して賢明なデフォルトを使用します。そのため、手作業で指定する必要がありません。

表3.8 Hibernate SQL Dialects (hibernate.dialect)

RDBMS 方言
DB2 org.hibernate.dialect.DB2Dialect
DB2 AS/400 org.hibernate.dialect.DB2400Dialect
DB2 OS390 org.hibernate.dialect.DB2390Dialect
PostgreSQL org.hibernate.dialect.PostgreSQLDialect
MySQL org.hibernate.dialect.MySQL5Dialect
MySQL with InnoDB org.hibernate.dialect.MySQL5InnoDialect
MySQL with MyISAM org.hibernate.dialect.MySQLMyISAMDialect
Oracle (any version) org.hibernate.dialect.Oracle8iDialect
Oracle 9i org.hibernate.dialect.Oracle9iDialect
Oracle 10g org.hibernate.dialect.Oracle10gDialect
Sybase org.hibernate.dialect.SybaseDialect
Sybase Anywhere org.hibernate.dialect.SybaseAnywhereDialect
Microsoft SQL Server org.hibernate.dialect.SQLServerDialect
Microsoft SQL Server 2008 org.hibernate.dialect.SQLServer2008Dialect
SAP DB org.hibernate.dialect.SAPDBDialect
Informix org.hibernate.dialect.InformixDialect
HypersonicSQL org.hibernate.dialect.HSQLDialect
Ingres org.hibernate.dialect.IngresDialect
Progress org.hibernate.dialect.ProgressDialect
Mckoi SQL org.hibernate.dialect.MckoiDialect
Interbase org.hibernate.dialect.InterbaseDialect
Pointbase org.hibernate.dialect.PointbaseDialect
FrontBase org.hibernate.dialect.FrontbaseDialect
Firebird org.hibernate.dialect.FirebirdDialect

3.4.2. 外部結合フェッチ

データベースが ANSI、 Oracle、 Sybase いずれかのスタイルの外部結合サポートしている場合、 外部結合フェッチによりデータベースを行き来するラウンドトリップの数が制限され、 通常パフォーマンスが向上されます。 しかし、 これによりデータベース自体が実行する作業が増える可能性があります。 外部結合フェッチは、 関係が 多対一、 一対多、 多対多、 一対一 で接続されるオブジェクトのグラフ全体を単一の SQL SELECT で読み出せるようにします。
hibernate.max_fetch_depth プロパティの値を 0 に設定すると、 外部結合フェッチを グローバル に無効にします。 1 以上の値を設定すると、 fetch="join" でマップされた 一対一 関係と多対一関係の外部結合フェッチが有効になります。
詳細は 「フェッチ戦略」 を参照してください。

3.4.3. バイナリストリーム

Oracle は JDBC ドライバとの間でやりとりされる byte 配列のサイズを制限します。 binaryserializable 型の大きなインスタンスを使用したい場合は、 hibernate.jdbc.use_streams_for_binary を有効にしてください。 ただし、 システムレベルの設定のみとなります

3.4.4. 2 次キャッシュとクエリキャッシュ

hibernate.cache が前に付くプロパティは、 Hibernate でプロセスやクラスタの範囲が決められた 2 次レベルキャッシュシステムを使用できるようにします。 詳細は 「2次レベルキャッシュ」 を参照してください。

3.4.5. クエリ言語の置き換え

hibernate.query.substitutions を使用すると、 新しい Hibernate クエリを定義できます。 例は次の通りです。
hibernate.query.substitutions true=1, false=0
これにより、 トークン truefalse が生成された SQL で整数リテラルに変換されます。
hibernate.query.substitutions toLowercase=LOWER
これは SQL の LOWER 関数の名前を変更できるようにします。

3.4.6. Hibernate 統計

hibernate.generate_statistics を有効にすると、 Hibernate は SessionFactory.getStatistics() より実行中のシステムを調節する際に、 有用な統計データを出力します。 JMX よりこれらの統計データを出力するよう Hibernate を設定することもできます。 詳細は org.hibernate.stats のインターフェースの Javadoc を参照してください。

3.5. ロギング

Hibernate はさまざまなシステムイベントをログに記録するため、 SLF4J (Simple Logging Facade for Java) を使用します。 SLF4J は、 選択したバインディングに応じてログ出力を複数のロギングフレームワーク (NOP、 Simple、 log4j バージョン 1.2、 JDK 1.4 ロギング、 JCL、 logback) に転送することができます。 ロギングを設定するには、 希望のバインディングの jar ファイル (Log4J の場合は slf4j-log4j12.jar) と、 クラスパス上に slf4j-api.jar が必要となります。 詳細は SLF4J の ドキュメント を参照してください。 Log4j を使用するには、 クラスパスに log4j.properties を置く必要もあります。 サンプルのプロパティファイルは、 Hibernate の src/ ディレクトリにあります。
Hibernate のログメッセージを理解できるようにしてください。 Hibernate のログはできる限り詳細で、 読みやすいようになっています。 トラブルシューティングでは必須となります。 重要なログのカテゴリは次の通りです。

表3.9 Hibernate ログカテゴリ

カテゴリ 機能
org.hibernate.SQL 実行したすべての SQL(DDL)ステートメントをロギングします。
org.hibernate.type すべての JDBC パラメータをロギングします。
org.hibernate.tool. hbm2ddl 実行したすべての SQL(DDL)ステートメントをロギングします。
org.hibernate.pretty session に関連するすべてのエンティティ(最大20)のフラッシュ時間をロギングします。
org.hibernate.cache すべてのニ次キャッシュの動作をロギングします。
org.hibernate. transaction トランザクションに関連する動作をロギングします。
org.hibernate.jdbc JDBC リソース取得をロギングします。
org.hibernate.hql. ast.AST HQL と SQL の AST のクエリパースをロギングします。
org.hibernate.secure すべての JAAS 分析をロギングします。
org.hibernate すべてをロギングします。 情報量は多くなりますが、 トラブルシューティングには便利です。
Hibernate でアプリケーションの開発時には、ほとんどの場合、カテゴリ org.hibernate.SQLdebug を有効にします。 debug の代わりにプロパティ hibernate.show_sql を有効にすることもできます。

3.6. NamingStrategy の実装

インターフェース org.hibernate.cfg.NamingStrategy はデータベースオブジェクトとスキーマ要素に対して「命名基準」を指定できるようにします。
Java の識別子からデータベース識別子を自動生成するためのルールや、 マッピングファイルの「論理的な」列とテーブル名を「物理的な」テーブルと列名に処理するためのルールを提供することが可能です。 この機能により、 マッピングドキュメントの詳細度を軽減し、 不要な繰り返し (TBL_の接頭辞など) が発生しないようにします。 Hibernate によって使用されるデフォルトの戦略は最小限になります。
マッピングを追加する前に Configuration.setNamingStrategy() を呼び出して異なる戦略を指定することができます。
SessionFactory sf = new Configuration()
    .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml")
    .buildSessionFactory();
org.hibernate.cfg.ImprovedNamingStrategy は組み込みの戦略で、 アプリケーションによってはここから始めるとよいでしょう。

3.7. XML 設定ファイル

もう1つの方法は hibernate.cfg.xml という名前のファイルで十分な設定を指定する方法です。このファイルは hibernate.properties ファイルの代わりとなります。もし両方のファイルがあれば、プロパティが置き換えられます。
XML 設定ファイルはデフォルトでは CLASSPATH のルートにあることが前提となります。 例は次の通りです。
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:hibernate/SessionFactory">

        <!-- properties -->
        <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
        <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql">false</property>
        <property name="transaction.factory_class">
            org.hibernate.transaction.JTATransactionFactory
        </property>
        <property name="jta.UserTransaction">java:comp/UserTransaction</property>

        <!-- mapping files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>

        <!-- cache settings -->
        <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
        <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
        <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>

    </session-factory>

</hibernate-configuration>
設定へのマッピングファイル名を外部化することがこの方法の利点となります。 Hibernate キャッシュの調整後は hibernate.cfg.xml もより便利になります。 hibernate.propertieshibernate.cfg.xml の使用を選択可能です。 前述の XML 構文を使用する利点以外は両者は同等となります。
XML 設定を使用すると、 Hibernate の起動は次の通り簡単です。
SessionFactory sf = new Configuration().configure().buildSessionFactory();
次を使用して異なる XML 設定を選択することもできます。
SessionFactory sf = new Configuration()
    .configure("catdb.cfg.xml")
    .buildSessionFactory();

3.8. J2EE アプリケーションサーバーとの統合

Hibernate は J2EE 構造と統合するポイントをサポートしています:
  • コンテナ管理データソース: Hibernate は JNDI が提供し、 コンテナが管理する JDBC 接続を使用できます。通常、 JTA 対応の TransactionManagerResourceManager がトランザクション管理 (CMT) がトランザクション管理を行い、 特に複数のデータソースにまたがる分散トランザクションを処理します。 プログラムを用いてトランザクション境界を指定することもできます (BMT)。 また、 コードの移植性を維持するためオプションの Hibernate Transaction API を使用することもできます。
  • 自動 JNDI バインディング: Hibernate は JNDI が立ち上がった後に SessionFactory を生成します。
  • JTA セッションバインディング: Hibernate Session は自動的に JTA トランザクションのスコープにバインドされることが可能です。 SessionFactory を JNDI からルックアップして、 現在の Session を取得します。 JTA トランザクションが完了した際、 Hibernate が Session をフラッシュし、 閉じます。 トランザクション境界は、 宣言的 (CMT) かプログラムの使用 (BMT/UserTransaction) になります。
  • JMX デプロイメント: JMX が使用可能なアプリケーションサーバー (JBoss AS など)の場合、 Hibernate を MBean としてデプロイすることが可能です。 これにより Configuration から SessionFactory をビルドする 1 行の起動コードが不要となります。 コンテナが HibernateService を起動し、 サービスの依存関係 (Hibernate 起動前にデータソースが使用可能でなければならないなど) に対応します。
環境に依存しますが、アプリケーションサーバーが "connection containment" の例外を出す場合、設定のオプション hibernate.connection.aggressive_release を true にしてください。

3.8.1. トランザクション戦略設定

Hibernate Session API は、 アーキテクチャ内のトランザクション境界システムに依存しません。 Hibernate が接続プールより直接 JDBC を使用するようにすると、 JDBC API を呼び出してトランザクションを開始および終了することができます。 J2EE アプリケーションサーバーで動作させる場合、 Bean 管理のトランザクションを使用し、 必要に応じて JTA API と UserTransaction を呼び出すことになるでしょう。
これら 2 つ (およびそれ以外) の環境でコードの移植性を維持するには、 基盤となるシステムをラッピングして隠すオプションの Hibernate Transaction API を推奨します。 Hibernate 設定プロパティの hibernate.transaction.factory_class を設定して Transaction インスタンスのファクトリクラスを指定する必要があります。
3 つの標準 (またはビルトイン) を選択できます。
org.hibernate.transaction.JDBCTransactionFactory
データベース (JDBC) トランザクションに委譲します(デフォルト)
org.hibernate.transaction.JTATransactionFactory
このコンテキスト (EJB セッション Bean メソッドなど) で既存のトランザクションが進行中である場合にコンテナ管理トランザクションへ委譲します。 そうでない場合は、 新しいトランザクションが開始され、 Bean 管理トランザクションが使用されます。
org.hibernate.transaction.CMTTransactionFactory
コンテナ管理 JTA トランザクションに委譲します
独自のトランザクション戦略 (CORBA トランザクションサービス向けなど) を定義することもできます。
Hibernate の機能の一部 (2 次キャッシュ、 JTA によるコンテキストセッションなど) は、 管理された環境の JTA TransactionManager へアクセスする必要があります。 アプリケーションサーバーでは、 J2EE は 1 つのメカニズムに標準化しないため、 Hibernate がTransactionManager への参照を取得する方法を指定する必要があります。

表3.10 JTA TransactionManager

Transaction Factory Application Server
org.hibernate.transaction. JBossTransactionManagerLookup JBoss
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

3.8.2. JNDI にバインドされた SessionFactory

JNDI にバインドされた Hibernate SessionFactory はファクトリのルックアップと新しい Session の作成を簡単にします。 JNDI にバインドされた Datasource には関連していませんが、 両方とも同じレジストリを使用します。
SessionFactory を JNDI 名前空間にバインドしたい場合は、 hibernate.session_factory_name プロパティを使用して名前 (java:hibernate/SessionFactory など) を指定します。 このプロパティを省略すると、 SessionFactory は JNDI にバインドされません。 これは、 読み取り専用の JNDI のデフォルト実装を持つ環境 (Tomcat 内など) で特に便利です。
SessionFactory を JNDI に登録するとき、 Hibernate は hibernate.jndi.url の値を使用し、hibernate.jndi.class をイニシャルコンテキストとして具体化します。何も設定しない場合は、デフォルトの InitialContext を使用します。
cfg.buildSessionFactory() を呼び出した後、 Hibernate は自動的に SessionFactory を JNDI に配置します。 これは、 HibernateService で JMX デプロイメントを使用しない限り、 この呼び出しがアプリケーションの起動コードかユーティリティクラスに存在することを意味します。
JNDI の SessionFactory や EJB、 他のクラスを使用する場合、 JNDI ルックアップを使用して SessionFactory を取得することができます。
管理された環境では SessionFactory を JNDI にバインドし、 管理されていない環境では static シングルトンを使用することが推奨されます。 また、 これらの詳細からアプリケーションコードを保護するため、 HibernateUtil.getSessionFactory() など、 ヘルパークラスの SessionFactory に対する実際のルックアップコードを非表示にすることが推奨されます。 このようなクラスは Hibernate の起動にも便利です。 詳細は第 1 章を参照してください。

3.8.3. JTA による現在のセッションコンテキストマネージメント

Hibernate の自動「現在」 Session 管理を使用すると、 最も簡単に Session とトランザクションを処理することができます。 コンテキストセッションの説明は 「コンテキストのセッション」 を参照してください。 現在の JTA トランザクションに関連する Hibernate Session がない場合に "jta" セッションコンテキストを使用すると、 最初に sessionFactory.getCurrentSession() を呼び出した時に Hibernate Session が開始され、 JTA トランザクションに関連付けられます。 "jta" コンテキストの getCurrentSession() より読み出された Session は、 トランザクションが完了する前に自動的にフラッシュし、 トランザクション完了後に閉じるよう設定されます。 また、 各ステートメントの後に積極的に JDBC 接続を開放するよう設定されます。 これにより、 関連する JTA トランザクションのライフサイクルによって Session が管理され、 ユーザーコードに管理に関する懸念が残らないようにします。 コードは UserTransaction よりプログラムを用いて JTA を使用するか、 Hibernate Transaction API を使用してトランザクション境界を設定することができます (移植可能なコードの場合は、 Hibernate Transaction API を使用してトランザクション境界を設定することが推奨されます)。 EJB コンテナ内で実行する場合は、 CMT による宣言的なトランザクション境界が推奨されます。

3.8.4. JMX デプロイメント

JNDI が SessionFactory を取得するには cfg.buildSessionFactory() 行を実行する必要があります。 これには、 static 初期化子ブロック内 (HibernateUtil 内のものなど) で行うか、 Hibernate を管理対象サービスとしてデプロイします。
Hibernate には、 JBoss AS など JMX 機能を持つアプリケーションサーバー上でのデプロイメント向けに、 org.hibernate.jmx.HibernateService が含まれています。 実際のデプロイメントや設定はベンダー固有となります 。JBoss 4.0.x 向けの jboss-service.xml の例は次のようになります。
<?xml version="1.0"?>
<server>

<mbean code="org.hibernate.jmx.HibernateService"
    name="jboss.jca:service=HibernateFactory,name=HibernateFactory">

    <!-- Required services -->
    <depends>jboss.jca:service=RARDeployer</depends>
    <depends>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>

    <!-- Bind the Hibernate service to JNDI -->
    <attribute name="JndiName">java:/hibernate/SessionFactory</attribute>

    <!-- Datasource settings -->
    <attribute name="Datasource">java:HsqlDS</attribute>
    <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>

    <!-- Transaction integration -->
    <attribute name="TransactionStrategy">
        org.hibernate.transaction.JTATransactionFactory</attribute>
    <attribute name="TransactionManagerLookupStrategy">
        org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
    <attribute name="FlushBeforeCompletionEnabled">true</attribute>
    <attribute name="AutoCloseSessionEnabled">true</attribute>

    <!-- Fetching options -->
    <attribute name="MaximumFetchDepth">5</attribute>

    <!-- Second-level caching -->
    <attribute name="SecondLevelCacheEnabled">true</attribute>
    <attribute name="CacheProviderClass">org.hibernate.cache.EhCacheProvider</attribute>
    <attribute name="QueryCacheEnabled">true</attribute>

    <!-- Logging -->
    <attribute name="ShowSqlEnabled">true</attribute>

    <!-- Mapping files -->
    <attribute name="MapResources">auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>

</mbean>

</server>
このファイルは META-INF ディレクトリにデプロイされ、 .sar 拡張子 (サービスアーカイブ) を持つ JAR ファイルにパッケージ化されます。 また、 Hibernate、 Hibernate が必要とするサードパーティーライブラリ、 コンパイルされた永続クラス、 マッピングファイルを同じアーカイブにパッケージ化する必要があります。 エンタープライズ Bean (通常はセッション Bean) は独自の JAR ファイルに保持することができますが、 この EJB JAR ファイルをメインサービスアーカイブに追加し、 単一の (ホット) デプロイ可能ユニットにすることができます。 JMX サービスや EJB デプロイメントに関する詳細は JBoss AS のドキュメントを参照してください。

第4章 永続クラス

永続クラスはビジネス上の問題のエンティティ (E コマースアプリケーションの顧客や注文など) を実装するアプリケーションのクラスです。 永続クラスのすべてのインスタンスが永続ステートであるわけではありません。 例えば、 インスタンスは一時的 (transient) であったり分離 (detached) 状態であることがあります。
これらのクラスが、 POJO (Plain Old Java Object) プログラミングモデルとしても知られる単純なルールに従うと、 Hibernate は最良の状態で動作します。 しかし、 これらのルールは難しいものではありません。 実際、 Hibernate3 は永続オブジェクトの性質に関する前提をほとんど持っていません。 ドメインモデルを他の方法で表現することもできます (Map インスタンスのツリーを使用するなど)。

4.1. 単純な POJO の例

多くの Java アプリケーションにはネコ科の動物を表現する永続クラスが必要となります。 例は次の通りです。
package eg;
import java.util.Set;
import java.util.Date;

public class Cat {
    private Long id; // identifier

    private Date birthdate;
    private Color color;
    private char sex;
    private float weight;
    private int litterId;

    private Cat mother;
    private Set kittens = new HashSet();

    private void setId(Long id) {
        this.id=id;
    }
    public Long getId() {
        return id;
    }

    void setBirthdate(Date date) {
        birthdate = date;
    }
    public Date getBirthdate() {
        return birthdate;
    }

    void setWeight(float weight) {
        this.weight = weight;
    }
    public float getWeight() {
        return weight;
    }

    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }

    void setSex(char sex) {
        this.sex=sex;
    }
    public char getSex() {
        return sex;
    }

    void setLitterId(int id) {
        this.litterId = id;
    }
    public int getLitterId() {
        return litterId;
    }

    void setMother(Cat mother) {
        this.mother = mother;
    }
    public Cat getMother() {
        return mother;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    public Set getKittens() {
        return kittens;
    }
    
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kitten.setMother(this);
    kitten.setLitterId( kittens.size() ); 
        kittens.add(kitten);
    }
}
永続クラスの主な 4 つのルールは以降の項で詳細に説明します。

4.1.1. 引数のないコンストラクタを実装する

Cat には引数のないコンストラクタがあります。 Hibernate が Constructor.newInstance() を使って永続クラスのインスタンス化を行えるように、 すべての永続クラスにはデフォルトコンストラクタ (public 以外でも問題ありません) がなければなりません。 Hibernate のランタイムプロキシ生成に対し、 少なくとも package の可視性を持つデフォルトコンストラクタが推奨されます。

4.1.2. 識別子プロパティを用意する(オプション)

Cat には id というプロパティがあります。 このプロパティはデータベーステーブルの主キー列へマッピングします。このプロパティの名前は何でも構いませんし、 型はどのようなプリミティブ型でも、 プリミティブの「ラッパー」型でも、 java.lang.Stringjava.util.Date でも構いません。レガシーデータベーステーブルに複合キーがある場合、これらの型のプロパティを持つユーザー定義のクラスを使用できます (本章の後に出てくる複合識別子の項を参照してください)。
識別子プロパティは厳密にはオプションです。これを省略して、 Hibernate に内部的にオブジェクトの識別子を追跡させることは可能です。しかしお勧めはしません。
実際に、 一部の機能は識別子プロパティを宣言するクラスだけが利用できます。
  • 分離オブジェクトの推移的な再追加 (カスケード更新やカスケードマージ) については、 「連鎖的な永続化」 を参照してください。
  • Session.saveOrUpdate()
  • Session.merge()
永続クラスには、 一貫した名前の識別子プロパティを宣言し、 null 値を取れる (プリミティブでない) 型を使用することが推奨されます。

4.1.3. final クラスにしない(オプション)

Hibernate の中心的な特徴である プロキシ は、永続クラスが final でないこと、またはメソッドを全部 public で宣言しているインターフェースが実装されているかに依存しています。
Hibernate でインターフェースを実装しない final クラスを永続化することはできますが、 遅延 (lazy) 関連フェッチに対してプロキシを使用できないため、 パフォーマンスチューニングのオプションが制限されます。
また、 final ではないクラスで public final メソッドを宣言しないようにしてください。 public final メソッドでクラスを使用した場合は、 lazy="false" と設定し、 明示的にプロキシを無効にしなければなりません。

4.1.4. 永続フィールドに対するアクセサとミューテータを定義する(オプション)

Cat はすべての永続フィールドに対してアクセサメソッドを宣言します。 他にも多くの ORM ツールが直接インスタンス変数を永続化します。 リレーショナルスキーマとクラスの内部データ構造間で間接化を提供した方がよいでしょう。 デフォルトでは、 Hibernate は JavaBean スタイルのプロパティを永続化し、 getFooisFoosetFoo 形式のメソッド名を認識します。 必要な場合、 特定のプロパティに対して直接フィールドアクセスへの切り替えが可能です。
プロパティは public で宣言する必要は ありません 。 Hibernate はデフォルトで、 protected もしくは private の get / set のペアを持つプロパティを永続化することができます。

4.2. 継承の実装

サブクラスも 1、 2 番目のルールを守らなければなりません。 サブクラスはスーパークラス Cat より識別子プロパティを継承します。 例は次の通りです。
package eg;

public class DomesticCat extends Cat {
        private String name;

        public String getName() {
                return name;
        }
        protected void setName(String name) {
                this.name=name;
        }
}

4.3. equals()hashCode() の実装

以下の場合、 equals() メソッドと hashCode() メソッドをオーバーライドしなければなりません。
  • 永続クラスのインスタンスを Set に置く場合 (多値関連を表すのに推奨される方法です)。 同時に
  • 分離インスタンスをセッションへ再追加する場合。
Hibernate は、永続 ID (データベースの行) と、 特定のセッション範囲内の Java ID のみ等価性を保証します。 異なるセッションで読み出されたインスタンスを混合する場合、 Set に意味のあるセマンティクスを持たせるためには equals()hashCode() を実装しなければなりません。
両方のオブジェクトの識別子値を比較して equals()/hashCode() を実装する方法が最も明白な方法です。値が同じ場合、 両方が同じデータベース行になります。 両方が Set に追加されると、 Set には 1 つの要素のみが存在することになります。残念ながらこの方法は生成された識別子には使用できません。 Hibernate は永続化されたオブジェクトへのみ識別子の値を割り当てます。 新たに作成されたインスタンスには識別子の値がありません。また、 インスタンスが保存されていない状態で現在 Set にある場合、 保存するとオブジェクトに識別子の値が割り当てられます。 equals()hashCode() が識別子の値を基にしている場合、 ハッシュコードが変更になり Set のコントラクトに違反することがあります。 この問題の詳細については、 Hibernate の Web サイトを参照してください。これは Hibernate の問題ではなく、オブジェクト識別と等価といった通常の Java セマンティックの問題になります。
ビジネスキーの等価性 を使用して、 equals()hashCode() を実装することが推奨されます。 ビジネスキーの等価性とは、 equals() メソッドがビジネスキーを構成するプロパティのみを比較することを意味します。 現実のインスタンスを識別するキーになります (自然な候補キー)。
public class Cat {

    ...
    public boolean equals(Object other) {
        if (this == other) return true;
        if ( !(other instanceof Cat) ) return false;

        final Cat cat = (Cat) other;

        if ( !cat.getLitterId().equals( getLitterId() ) ) return false;
        if ( !cat.getMother().equals( getMother() ) ) return false;

        return true;
    }

    public int hashCode() {
        int result;
        result = getMother().hashCode();
        result = 29 * result + getLitterId();
        return result;
    }

}
ビジネスキーはデータベースの主キー候補ほど安定性は必要ありません (「オブジェクト識別子を考える」 を参照してください)。 通常、 不変のプロパティや固有のプロパティがビジネスキーに適切な候補となります。

4.4. 動的モデル

注記

以下の機能は現在実験段階にあり、 近い将来変更される可能性があります。
必ずしも永続エンティティを実行時に POJO クラスや JavaBean オブジェクトとして表現する必要はありません。 Hibernate は動的モデル (実行時に MapMap を使用) や DOM4J ツリーとしてのエンティティの表現もサポートしています。 この方法では、 永続クラスを記述せず、 マッピングファイルのみを記述します。
デフォルトでは、 Hibernate は通常の POJO モードで動作します。 default_entity_mode 設定オプションを用いて、 特定の SessionFactory に対するデフォルトのエンティティ表現モードを設定することができます (表3.3「Hibernate 設定プロパティ」 を参照してください)。
次の例は Map を用いた表現になります。 最初に、 クラス名の代わりに (またはクラス名に加えて)、 マッピングファイルで entity-name を宣言する必要があります。
<hibernate-mapping>

    <class entity-name="Customer">

        <id name="id"
            type="long"
            column="ID">
            <generator class="sequence"/>
        </id>

        <property name="name"
            column="NAME"
            type="string"/>

        <property name="address"
            column="ADDRESS"
            type="string"/>

        <many-to-one name="organization"
            column="ORGANIZATION_ID"
            class="Organization"/>

        <bag name="orders"
            inverse="true"
            lazy="false"
            cascade="all">
            <key column="CUSTOMER_ID"/>
            <one-to-many class="Order"/>
        </bag>

    </class>
    
</hibernate-mapping>
ターゲットのクラス名を使用して関連が宣言されても、 関連のターゲット型も POJO ではなく動的なエンティティにすることができます。
SessionFactory のデフォルトのエンティティモードを dynamic-map に設定した後、実行時に MapMap を使用することができます。
Session s = openSession();
Transaction tx = s.beginTransaction();

// Create a customer
Map david = new HashMap();
david.put("name", "David");

// Create an organization
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");

// Link both
david.put("organization", foobar);

// Save both
s.save("Customer", david);
s.save("Organization", foobar);

tx.commit();
s.close();
動的マッピングの主な利点の1つとして、エンティティクラスの実装を必要としないにも拘らず、プロトタイピングのターンアラウンドタイム(TAT)が短い点が挙げられます。しかし、 コンパイル時の型チェックがないため、 実行時に多くの例外に対処することになります。 Hibernate マッピングの結果、 データベーススキーマが容易に正規化されるため、 後で適切なドメインモデル実装を追加することが可能になります。
エンティティ表現モードは Session ごとに設定することも可能です。
Session dynamicSession = pojoSession.getSession(EntityMode.MAP);

// Create a customer
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close();
...
// Continue on pojoSession
EntityMode を使った getSession() の呼び出しは SessionFactory ではなく Session API 上であることに注意してください。 これにより、 新しい Session は基盤となる JDBC 接続やトランザクション、 その他のコンテキスト情報を共有します。 そのため、 セカンダリ Session 上で flush()close() を呼び出す必要がなく、 トランザクションや接続の処理をプライマリの作業単位に委ねることができます。
XML 表現の能力についての詳細は 18章XML マッピング を参照してください。

4.5. Tuplizer

org.hibernate.tuple.Tuplizer とそのサブインターフェースは、 表現の org.hibernate.EntityMode に提供されたデータの特定の表現を管理します。 提供されたデータがデータ構造として考慮される場合、 Tuplizer はこのようなデータ構造を作成する方法や、 このようなデータ構造から値を抽出したり挿入する方法を認識します。 例えば、 POJO エンティティモードでは、 対応する Tuplizer はコンストラクタより POJO を作成する方法を認識します。 また、 定義されたプロパティアクセッサを使用して POJO プロパティにアクセスする方法も認識します。
org.hibernate.tuple.entity.EntityTuplizer インターフェースと org.hibernate.tuple.component.ComponentTuplizer インターフェースによって表現される 2 つのハイレベル型の Tuplizer があります。 EntityTuplizer はエンティティに関する前述のコントラクトを管理し、 ComponentTuplizer はコンポーネントに関する前述のコントラクトを管理します。
ユーザーは独自の Tuplizer を使用することもできます。 動的マップのエンティティモードの場合、 java.util.HashMap ではなく java.util.Map の実装が必要となることがあるでしょう。または、 デフォルトで使用されるプロキシ生成戦略ではなく、 他の戦略を定義する必要な場合もあるでしょう。 カスタムの Tuplizer を定義すると、 このような状況に対処することができます。Tuplizer の定義は管理するエンティティやコンポーネントのマッピングに結び付けられます。 顧客エンティティの例をもう一度見てみましょう。
<hibernate-mapping>
    <class entity-name="Customer">
        <!--
            Override the dynamic-map entity-mode
            tuplizer for the customer entity
        -->
        <tuplizer entity-mode="dynamic-map"
                class="CustomMapTuplizerImpl"/>

        <id name="id" type="long" column="ID">
            <generator class="sequence"/>
        </id>

        <!-- other properties -->
        ...
    </class>
</hibernate-mapping>


public class CustomMapTuplizerImpl
        extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {
    // override the buildInstantiator() method to plug in our custom map...
    protected final Instantiator buildInstantiator(
            org.hibernate.mapping.PersistentClass mappingInfo) {
        return new CustomMapInstantiator( mappingInfo );
    }

    private static final class CustomMapInstantiator
            extends org.hibernate.tuple.DynamicMapInstantitor {
        // override the generateMap() method to return our custom map...
        protected final Map generateMap() {
            return new CustomMap();
        }
    }
}

4.6. EntityNameResolvers

org.hibernate.EntityNameResolver インターフェースはエンティティインスタンスのエンティティ名を解決するためのコントラクトです。 このインターフェースは、 単一のメソッドである resolveEntityName を定義します。 resolveEntityName はエンティティインスタンスへ渡され、 適切なエンティティ名を返すはずです (null 値を使用できますが、 null はリゾルバがエンティティインスタンスのエンティティ名を解決する方法を認識しないことを意味します)。 通常、 動的モデルでは org.hibernate.EntityNameResolver が最も便利です。 プロキシされたインターフェースをドメインモデルとして使用するのが 1 つの例です。 Hibernate のテストスイートの org.hibernate.test.dynamicentity.tuplizer2 にこの使用例があります。 このパッケージにあるコードの一部は次の通りです。
/**
 * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as
 * the domain model and simply store persistent state in an internal Map.  This is an extremely
 * trivial example meant only for illustration.
 */
public final class DataProxyHandler implements InvocationHandler {
    private String entityName;
    private HashMap data = new HashMap();

    public DataProxyHandler(String entityName, Serializable id) {
        this.entityName = entityName;
        data.put( "Id", id );
    }

    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        String methodName = method.getName();
        if ( methodName.startsWith( "set" ) ) {
            String propertyName = methodName.substring( 3 );
            data.put( propertyName, args[0] );
        }
        else if ( methodName.startsWith( "get" ) ) {
            String propertyName = methodName.substring( 3 );
            return data.get( propertyName );
        }
        else if ( "toString".equals( methodName ) ) {
            return entityName + "#" + data.get( "Id" );
        }
        else if ( "hashCode".equals( methodName ) ) {
            return new Integer( this.hashCode() );
        }
        return null;
    }

    public String getEntityName() {
        return entityName;
    }

    public HashMap getData() {
        return data;
    }
}

/**
 *
 */
public class ProxyHelper {
    public static String extractEntityName(Object object) {
        // Our custom java.lang.reflect.Proxy instances actually bundle
        // their appropriate entity name, so we simply extract it from there
        // if this represents one of our proxies; otherwise, we return null
        if ( Proxy.isProxyClass( object.getClass() ) ) {
            InvocationHandler handler = Proxy.getInvocationHandler( object );
            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {
                DataProxyHandler myHandler = ( DataProxyHandler ) handler;
                return myHandler.getEntityName();
            }
        }
        return null;
    }

    // various other utility methods ....

}

/**
 * The EntityNameResolver implementation.
 * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be
 * resolved.  Since this particular impl can handle resolution for all of our entities we want to
 * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever
 * have one instance registered.  Why?  Well, when it comes time to resolve an entity name,
 * Hibernate must iterate over all the registered resolvers.  So keeping that number down
 * helps that process be as speedy as possible.  Hence the equals and hashCode impls
 */
public class MyEntityNameResolver implements EntityNameResolver {
    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();

    public String resolveEntityName(Object entity) {
        return ProxyHelper.extractEntityName( entity );
    }

    public boolean equals(Object obj) {
        return getClass().equals( obj.getClass() );
    }

    public int hashCode() {
        return getClass().hashCode();
    }
}

public class MyEntityTuplizer extends PojoEntityTuplizer {
    public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {
        super( entityMetamodel, mappedEntity );
    }

    public EntityNameResolver[] getEntityNameResolvers() {
        return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };
    }

    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {
        String entityName = ProxyHelper.extractEntityName( entityInstance );
        if ( entityName == null ) {
            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );
        }
        return entityName;
    }

    ...
}
org.hibernate.EntityNameResolver を登録するには、 ユーザーは次のいずれかを実行しなければなりません。
  1. getEntityNameResolvers メソッドを実装するカスタムの 「Tuplizer」 を実装します。
  2. registerEntityNameResolver メソッドを使用し、 org.hibernate.impl.SessionFactoryImpl (org.hibernate.SessionFactory の実装クラス) を用いて登録します。

第5章 基本的な O/R マッピング

5.1. マッピング宣言

オブジェクト/リレーショナルマッピングは通常 XML ドキュメントで定義します。マッピングドキュメントは、読みやすく手作業で編集しやすいようにデザインされています。マッピング言語は Java 中心、つまりテーブル宣言ではなく永続クラスの宣言に基づいて構築されています。
多くの Hibernate ユーザーは XML マッピングの記述を手作業で行いますが、XDoclet、Middlegen、AndroMDA など、マッピングドキュメントの生成ツールも多数存在することを覚えておいてください。
マッピング例から始めましょう:
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
      "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
          "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat"
            table="cats"
            discriminator-value="C">

                <id name="id">
                        <generator class="native"/>
                </id>

                <discriminator column="subclass"
                     type="character"/>

                <property name="weight"/>

                <property name="birthdate"
                    type="date"
                    not-null="true"
                    update="false"/>

                <property name="color"
                    type="eg.types.ColorUserType"
                    not-null="true"
                    update="false"/>

                <property name="sex"
                    not-null="true"
                    update="false"/>

                <property name="litterId"
                    column="litterId"
                    update="false"/>

                <many-to-one name="mother"
                    column="mother_id"
                    update="false"/>

                <set name="kittens"
                    inverse="true"
                    order-by="litter_id">
                        <key column="mother_id"/>
                        <one-to-many class="Cat"/>
                </set>

                <subclass name="DomesticCat"
                    discriminator-value="D">

                        <property name="name"
                            type="string"/>

                </subclass>

        </class>

        <class name="Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>
マッピングドキュメントの内容を説明します。ただし、ここでは Hibernate が実行時に使うドキュメント要素と属性についてのみ説明します。マッピングドキュメントは、いくつかの追加のオプション属性と要素を含んでいます(例えば not-null 属性)。それらはスキーマエクスポートツールが出力するデータベーススキーマに影響を与えるものです。

5.1.1. Doctype

XML マッピングのすべてにおいて、提示したようなドキュメント型を宣言すべきです。実際の DTD は、上記の URL の hibernate-x.x.x/src/org/hibernate ディレクトリ、または hibernate.jar 内にあります。まずHibernate は常に、そのクラスパス内で DTD を探し始めます。インターネット接続を利用して DTD ファイルを探す場合、クラスパスの内容を見て、DTD 宣言を確認してください。

5.1.1.1. エンティティリゾルバ

前述したように、Hibernate はまずクラスパス内で DTD を解決しようとします。org.xml.sax.EntityResolver のカスタム実装を XML ファイルを読み込むための SAXReader に登録することによって、DTD を解決します。このカスタムの EntityResolver は2つの異なるシステムIDの名前空間を認識します。
  • hibernate namespace は、リゾルバが http://hibernate.sourceforge.net/ で始まるシステム ID に到達したときに認識されます。そしてリゾルバは、Hibernate のクラスをロードしたクラスローダを用いて、これらのエンティティを解決しようとします。
  • user namespace は、リゾルバが URL プロトコルの classpath:// を使ったシステム ID に遭遇したときに、認識されます。そしてこのリゾルバは、(1) カレントスレッドのコンテキストクラスローダー、または (2) Hibernate のクラスをロードしたクラスローダを使って、これらのエンティティを解決しようとします。
下記は、ユーザー名前空間の使用例です:
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" [
    <!ENTITY types SYSTEM "classpath://your/domain/types.xml">
]>

<hibernate-mapping package="your.domain">
    <class name="MyEntity">
        <id name="id" type="my-custom-id-type">
            ...
        </id>
    <class>
    &types;
</hibernate-mapping>
ここで types.xmlyour.domain パッケージのリソースであり、カスタム 「カスタム型」 を含みます。

5.1.2. Hibernate-mapping

この要素にはいくつかオプション属性があります。schema 属性と catalog 属性は、このマッピングで参照するテーブルが、指定のスキーマと(または)カタログに属することを特定します。この属性が指定されると、テーブル名は与えられたスキーマ名とカタログ名で修飾されます。これらの属性が指定されていなければ、テーブル名は修飾されません。default-cascade 属性は、cascade 属性を指定していないプロパティやコレクションに、どのカスケードスタイルを割り当てるかを指定します。auto-import 属性は、クエリ言語内で非修飾のクラス名を、デフォルトで使えるようにします。
<hibernate-mapping
         schema="schemaName"                           1
         catalog="catalogName"                         2
         default-cascade="cascade_style"               3
         default-access="field|property|ClassName"     4
         default-lazy="true|false"                     5
         auto-import="true|false"                      6
         package="package.name"                        7
 />

1

schema(オプション):データベーススキーマの名前。

2

catalog (オプション):データベースカタログの名前。

3

default-cascade(オプション - デフォルトは none):デフォルトのカスケードスタイル。

4

default-access (オプション - デフォルトは property):Hibernate が全プロパティにアクセスする際に取るべき戦略。PropertyAccessor のカスタム実装の場合もある。

5

default-lazy (オプション - デフォルトは true ):lazy 属性が指定されていないクラスやコレクションマッピングに対するデフォルト値。

6

auto-import(オプション - デフォルトは true):クエリ言語にて、このマッピング内のクラスにある非修飾のクラス名を使えるかどうかを指定します。

7

package (オプション): マッピングドキュメント内で非修飾のクラス名に対して使用する、パッケージの接頭辞 (prefix) を指定します。
同じ非修飾名を持つ永続クラスが2つある場合、auto-import="false" を設定すべきです。2つのクラスに同じ「インポート」名を割り当てようとすると、Hibernate は例外を送出します。
hibernate-mapping 要素は、前述のようにいくつかの永続 <class> マッピングをネストできます。しかし、1つのマッピングファイルにただひとつの永続クラス、またはひとつのクラス階層にマッピングし、さらに永続スーパークラスの後に指定するようにします(ツールによってはこのようなマッピングファイルを想定しています)。例: Cat.hbm.xml , Dog.hbm.xml , または継承を使う場合 Animal.hbm.xml

5.1.3. Class

class 要素を使って、永続クラスを宣言できます。例えば、
<class
        name="ClassName"                               1
        table="tableName"                              2
        discriminator-value="discriminator_value"      3
        mutable="true|false"                           4
        schema="owner"                                 5
        catalog="catalog"                              6
        proxy="ProxyInterface"                         7
        dynamic-update="true|false"                    8
        dynamic-insert="true|false"                    9
        select-before-update="true|false"              10
        polymorphism="implicit|explicit"               11
        where="arbitrary sql where condition"          12
        persister="PersisterClass"                     13
        batch-size="N"                                 14
        optimistic-lock="none|version|dirty|all"       15
        lazy="true|false"                              16
        entity-name="EntityName"                       17
        check="arbitrary sql check condition"          18
        rowid="rowid"                                  19
        subselect="SQL expression"                     20
        abstract="true|false"                          21
        node="element-name"
/>

1

name (オプション):永続クラスまたはインターフェースの完全修飾 Java クラス名。この属性が抜けている場合、POJO 以外のエンティティに対するマッピングとして扱われます。

2

table (オプション - デフォルトは非修飾クラス名):データベーステーブルの名前

3

discriminator-value (オプション - デフォルトはクラス名): ポリモーフィックな動作に使われる個々のサブクラスを識別するための値。値は nullnot null のいずれかを取ります。

4

mutable (オプション、デフォルトは true ):そのクラスのインスタンスが更新可能(または不可能)であることを指定します。

5

schema (オプション): ルートの <hibernate-mapping> 要素で指定したスキーマ名をオーバーライドします。

6

catalog (オプション): ルートの <hibernate-mapping> 要素で指定したカタログ名をオーバーライドします。

7

proxy (オプション):lazyな初期化プロキシに使うインターフェースを指定します。クラス名そのものを指定することも可能です。

8

dynamic-update (オプション - デフォルトは false):UPDATE SQLを実行時に生成すべき点、また値を変更したカラムしか含むことができない点を指定します。

9

dynamic-insert(オプション, デフォルトは false ):INSERT SQLを実行時に生成し、値が null ではないカラムだけを含むべきであると指定します。

10

select-before-update (オプション、デフォルトは false): 実際にオブジェクトが変更されたか確実でない場合 Hibernate が SQL の UPDATE決して実行しない ことを指定します。一時オブジェクトが update() を使い、新しいセッションと関連付けられた時だけ、UPDATE が実際に必要かどうかを決定するために、 Hibernate が余分な SQL の SELECT を実行します。

11

polymorphism (オプション、デフォルトでは implicit ): 暗黙か明示の、どちらのクエリポリモーフィズムを使うか決定します。

12

where(オプション): このクラスのオブジェクトを検索するときに使用する、任意の SQL の WHERE 条件を指定します。

13

persister(オプション):カスタム ClassPersister を指定します。

14

batch-size (オプション、デフォルトは 1 ):識別子でこのクラスのインスタンスをフェッチするときの「バッチサイズ」を指定します。

15

optimistic-lock (オプション、デフォルトは version ): 楽観的ロック戦略を決定します。

(16)

lazy (オプション): lazy="false" と設定することで、遅延フェッチを無効にできます。

(17)

entity-name (オプション、デフォルトはクラス名):Hibernate3 ではクラスが複数回マッピングでき(場合によっては違うテーブルに対しても)、Java レベルで Map や XML で表現されるエンティティマッピングも可能です。これらの場合、エンティティに対して任意の名前を、明示的に付けなくてはなりません。 詳しくは 「動的モデル」18章XML マッピング を参照してください。

(18)

check (オプション):自動的にスキーマを生成するために、複数行の check 制約を生成するのに利用する SQL 式。

(19)

rowid (オプション):Hibernate はデータベース上でROWIDを利用可能です。例えば、Oracle であれば、このオプションに rowid を設定すると、 Hiberante は rowid の余分なカラムを使うことで更新を高速化することができます。ROWID は実装の詳細で、保存されたタプルの物理的な場所を表しています。

(20)

subselect (オプション):不変かつ読み取り専用であるエンティティをデータベースの副問合せ(subselect)にマッピングします。ベースのテーブルの代わりにビューを持ちたい場合は有用です。より詳しい情報は下記を参照してください。

(21)

abstract (オプション): <union-subclass> 階層内の抽象スーパークラスをマークするために使います。
指定の永続クラスがインターフェースであっても問題ありません。そのときは <subclass> 要素を使って、そのインターフェースを実装するクラスを宣言してください。static な内部クラスでも永続化できます。 eg.Foo$Bar といった標準形式を使ってクラス名を指定してください。
不変クラス mutable="false" では、アプリケーションによる更新や削除が出来ないことがあります。これにより、 Hibernate がパフォーマンスを少し改善することができます。
オプションの proxy 属性により、クラスの永続インスタンスの遅延初期化が可能になります。最初にHibernate は指定したインターフェースを実装する CGLIB プロキシを返します。この永続オブジェクトはプロキシのメソッドを呼び出すときにロードします。以下の「初期化コレクションとプロキシ」を参照してください。
暗黙的 ポリモーフィズムとは次の二つを意味しています。1つは、そのクラスのインスタンスが、スーパークラスや実装したインターフェース、またはクラスを指定するクエリーにより返されること、もう一つは、そのクラスのサブクラスのインスタンスがそのクラス自身を指定したクエリによって返されることです。また、 明示的 ポリモーフィズムとは、次の二つを意味しています。一つはクラスのインスタンスが、そのクラスを明示的に指定したクエリによってのみ返されることで、もう一つはクラスを指定したクエリが、 <class> 要素の中で <subclass><joined-subclass> とマッピングされているサブクラスのインスタンスだけを返すことです。ほとんどの用途ではデフォルトの polymorphism="implicit" が適切です。明示的なポリモーフィズムは、2つの違ったクラスが同じテーブルにマッピングされているときに有用です これによってテーブルカラムのサブセットを含む、「軽量な」クラスが可能になります。
persister 属性により、クラスに使われる永続化戦略をカスタマイズできます。例えば org.hibernate.persister.EntityPersister 自身のサブクラスを指定したり、またストアドプロシージャコール、フラットファイルへシリアライズ、LDAP などを通した永続性を実装する org.hibernate.persister.ClassPersister インターフェースの完全に新しい実装でさえも提供できます。Hashtable の「永続化」に関する簡単な例に関しては org.hibernate.test.CustomPersister を参照してください。
dynamic-updatedynamic-insert の設定はサブクラスに継承されません。そのため <subclass><joined-subclass> 要素を指定することも出来ます。これらの設定はパフォーマンスを向上させる事もありますが、落とすこともありますので、慎重に使用してください。
select-before-update を使用すると、通常パフォーマンスが落ちてしまいます。Session へ分離インスタンスのグラフを再追加する場合にデータベース更新のトリガを不必要に呼び出さずに済む点で、非常に有用です。
dynamic-update を有効にすれば、楽観ロック戦略を選ぶことになります:
  • version:バージョン/タイムスタンプカラムをチェックします。
  • all:すべてのカラムをチェックします。
  • dirty:変更したカラムをチェックし、同時更新できるようにします。
  • none:楽観ロックを使用しません。
Hibernate で楽観的ロック戦略を使う場合、バージョン/タイムスタンプカラムを使うことを 強く お勧めします。この戦略はパフォーマンスの観点からも最適であり、さらに分離インスタンスへの修正 (つまり Session.marge() が使われるとき) を正確に処理します。
Hibernate のマッピングにとってビューと普通のテーブルの間に違いはなく、データベースレベルでは透過的です。ただし、更新のあるビューの場合など特に、正しくビューをサポートしていない DBMS もあります。ビューを使いたくても、データベースで作成できないことがあります(例えば、レガシースキーマの場合)。この場合には、不変かつ読み取り専用のエンティティに与えられた SQL の副問合せ文をマップできます:
<class name="Summary">
    <subselect>
        select item.name, max(bid.amount), count(*)
        from item
        join bid on bid.item_id = item.id
        group by item.name
    </subselect>
    <synchronize table="item"/>
    <synchronize table="bid"/>
    <id name="name"/>
    ...
</class>
テーブルをこのエンティティと同期するように宣言してください。オートフラッシュが確実に起こるように、また導出エンティティに対するクエリが古いデータを返さないようにするためです。<subselect> は属性とネストしたマッピング属性のどちらでも利用できます。

5.1.4. id

マップされたクラスはデータベーステーブルの主キーカラムを定義 しなければなりません。ほとんどのクラスにはインスタンスのユニークな識別子を保持する JavaBeans スタイルのプロパティも持っています。<id> 要素は、そのプロパティから主キーカラムへのマッピングを定義します。
<id
        name="propertyName"                                           1
        type="typename"                                               2
        column="column_name"                                          3
        unsaved-value="null|any|none|undefined|id_value"              4
        access="field|property|ClassName">                            5
        node="element-name|@attribute-name|element/@attribute|."
 
        <generator class="generatorClass"/>
</id>

1

name(オプション):識別子プロパティの名前。

2

type(オプション):Hibernate の型を示す名前。

3

column(オプション - デフォルトはプロパティ名): 主キーカラムの名前。

4

unsaved-value(オプション - デフォルト値は 「sensible」):インスタンスが新しくインスタンス化された (保存されていない)ことを示す、識別子プロパティの値。以前の Session で保存またはロードされた一時的インスタンスと区別するために使います。

5

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
name 属性がない場合は、クラスには識別子プロパティがないものとみなされます。
unsaved-value 属性は Hibernate3 ではほとんどの場合、必要ではありません。
複合キーを持つレガシーデータにアクセスできるように、 <composite-id> という代替の宣言があります。しかし他の用途としては全くお奨めできません。

5.1.4.1. ジェネレータ

オプションの <generator> 子要素は、永続クラスのインスタンスのユニークな識別子を生成するために使う、 Java クラスを指定します。ジェネレータインスタンスの設定、もしくは初期化にパラメータが必要であれば、 <param> 要素を使って渡すことができます。
<id name="id" type="long" column="cat_id">
        <generator class="org.hibernate.id.TableHiLoGenerator">
                <param name="table">uid_table</param>
                <param name="column">next_hi_value_column</param>
        </generator>
</id>
すべてのジェネレータは、org.hibernate.id.IdentifierGenerator インターフェースを実装します。これはとても単純なインターフェースなので、専用の実装を独自に用意するアプリケーションもあるかもしれません。しかし Hibernate は組み込みの実装をいくつも用意しています。組み込みのジェネレータには以下のショートカット名があります:
increment
long , short , int 型の識別子を生成します。これらは他のプロセスが同じテーブルにデータを挿入しないときだけユニークです。クラスタ内では使わないでください
identity
DB2, MySQL, MS SQL Server, Sybase, HypersonicSQL の識別子カラムをサポートします。返される識別子の型は long , short , int のいずれかです。
sequence
DB2, PostgreSQL, Oracle, SAP DB, McKoi のシーケンスや、 Interbase のジェネレータを使用します。返される識別子の型は long , short , int のいずれかです。
hilo
long , short , int 型の識別子を効率的に生成する hi/lo アルゴリズムを使います。 hi 値のソースとして、テーブルとカラムを与えます(デフォルトではそれぞれ hibernate_unique_keynext_hi )。 hi/lo アルゴリズムは特定のデータベースに対してのみユニークな識別子を生成します。
seqhilo
long , short , int 型の識別子を効率的に生成する hi/lo アルゴリズムを使います。指定されたデータベースシーケンスを与えます。
uuid
( IP アドレスが使用される)ネットワーク内でユニークな文字列型の識別子を生成するために、 128 ビットの UUID アルゴリズムを使用します。UUID は長さ 32 の 16 進数字の文字列としてエンコードされます。
guid
MS SQL サーバーと MySQL でデータベースが生成する GUID 文字列を使用します。
native
基盤となるデータベースの性能により identitysequencehilo のいずれかを選択します。
assigned
save() が呼ばれる前に、アプリケーションがオブジェクトに識別子を割り当てられるようにします。<generator> 要素が指定されていなければ、これがデフォルトの戦略になります。
select
ユニークキーによる行の選択と主キーの値の取得により、データベーストリガが割り当てた主キーを取得します。
foreign
他の関連オブジェクトの識別子を使います。普通は、<one-to-one> 主キー関連と組み合わせて使います。
sequence-identity
実際の値の生成のためにデータベースシーケンスを使用する特別なシーケンス生成戦略ですが、JDBC3 getGeneratedKeys と結びついて、INSERT 文の実行の一部として生成された識別子の値を返します。この戦略は JDK 1.4 を対象とする Oracle 10g のドライバのみでサポートされています。これらの INSERT 文でのコメントは Oracle のドライバのバグにより無効にされていることに注意してください。

5.1.4.2. Hi/lo アルゴリズム

hiloseqhilo ジェネレータは、hi/lo アルゴリズムの2つの代替実装を提供します。1番目の実装は、次回に利用される「hi」値を保持する「特別な」データベーステーブルを必要とします。サポートされている場合、2番目の実装は、 Oracle スタイルのシーケンスを使います。
<id name="id" type="long" column="cat_id">
        <generator class="hilo">
                <param name="table">hi_value</param>
                <param name="column">next_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>
<id name="id" type="long" column="cat_id">
        <generator class="seqhilo">
                <param name="sequence">hi_value</param>
                <param name="max_lo">100</param>
        </generator>
</id>
残念ながら Hibernate へ独自の Connection を提供するときには、 hilo を使えません。Hibernate が JTA でリストされている接続を取得するためにアプリケーションサーバーのデータソースを使用する場合は、hibernate.transaction.manager_lookup_class を適切に設定しなければなりません。

5.1.4.3. UUID アルゴリズム

UUID には以下のものが含まれます:IP アドレス、JVM のスタートアップタイム(4分の1秒の正確さ)、システム時間、 JVM に対して一意のカウンタ値。 Java コードから MAC アドレスやメモリアドレスを取得することはできないため、これはJNI が使えないときの最良のオプションです。

5.1.4.4. 識別子カラムとシーケンス

識別子カラムをサポートしているデータベース(DB2, MySQL, Sybase, MS SQL)では、 identity キー生成が使えます。シーケンスをサポートするデータベース(DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB)では、 sequence スタイルのキー生成が使えます。どちらの戦略も、新しいオブジェクトを挿入するために、SQL クエリを2つ必要とします。例えば:
<id name="id" type="long" column="person_id">
        <generator class="sequence">
                <param name="sequence">person_id_sequence</param>
        </generator>
</id>
<id name="id" type="long" column="person_id" unsaved-value="0">
        <generator class="identity"/>
</id>
クロスプラットフォームの開発では、native 戦略は identitysequencehilo 戦略の中から1つを選択しますが、これは基盤となるデータベースの能力に依存します。

5.1.4.5. 識別子の割り当て

( Hibernate が生成するのではなく)アプリケーションに識別子を割り当てさせたい場合、assigned ジェネレータを使うことができます。この特別なジェネレータは、すでにオブジェクトの識別子プロパティに代入された値を識別子に使います。このジェネレータは主キーが代理キーの代わりに自然キーである場合に使用します。<generator> 要素を指定しない場合のデフォルトの動作になります。
assigned ジェネレータを選択すると、 Hibernate は unsaved-value="undefined" を使います。その結果、バージョンやタイムスタンプのプロパティがない場合や Interceptor.isUnsaved() を定義しなかった場合には、インスタンスが一時的(transient)なものであるのか、またはセッションから分離(detached)したものかどうかを決めるために、Hibernateは必ずデータベースを調べることになります。

5.1.4.6. トリガにより割り当てられた主キー

Hibernate はトリガを使って DDL を生成しません。これはレガシースキーマ用となっています。
<id name="id" type="long" column="person_id">
        <generator class="select">
                <param name="key">socialSecurityNumber</param>
        </generator>
</id>
上記の例の中で、socialSecurityNumber という名前のユニークな値のプロパティがあります。これはクラスにより、自然キーや、値がトリガにより生成される person_id という名前の代理キーとして定義されます。

5.1.5. 拡張型の識別子ジェネレータ

識別子生成の2つの側面の見直しが行われ、リリース 3.2.3 から新たな識別子ジェネレータが2つ登場しました。一点目は、データベースの移植性で、2点目は最適化です。ここでいう最適化とは、新たな識別子の値に対するリクエストすべてに関してデータベースをクエリする必要がないという意味です。これら2つのジェネレータは、前述した指定ジェネレータの一部の代わりとされており、3.3.x から組み込まれています。ただし、最新のリリースには含まれており、FQNで参照することができます。
1つ目のジェネレータは、org.hibernate.id.enhanced.SequenceStyleGeneratorで、まずはsequenceの代わりとされており、次に native よりも移植性が優れているジェネレータの提供を目的としています。通常identitysequence との間で選択するためなのですが、identitysequence は非常違ったセマンティクスを持っており、移植性を視野に入れるアプリケーションで微妙な問題を引き起こす可能性があるのです。しかし、org.hibernate.id.enhanced.SequenceStyleGenerator は違ったかたちで移植性を実現しています。データベース内のテーブルまたはシーケンスの中から選択し、使用される方言の性能に従い、インクリメント値を保存します。このジェネレータと native の違いは、テーブルベースとシーケンスベースのストレージは全く同じセマンティックを持つことです。実際、シーケンスは Hibernate がテーブルベースのジェネレータでエミュレートしようとしていることと全く同じです。このジェネレータにはいくつかの設定パラメーターが存在します:
  • sequence_name(オプション - デフォルトは hibernate_sequence ): 使用するシーケンスもしくはテーブル名
  • initial_valueオプション - デフォルトは 1): シーケンス / テーブルから取得される初期値。シーケンス作成の用語にすると、これは通常「STARTS WITH」で指定される節に似ています。
  • increment_size (オプション - デフォルトでは 1): シーケンス/テーブルへの後続の呼出が違う値。シーケンス作成の用語にすると、これは通常「INCREMENT BY」で指定される節に似ています。
  • force_table_use(オプション - デフォルトは false): 方言がシーケンスに対応する場合でも、補助構造としてテーブルの利用を強制すべきか?
  • value_column (オプション - デフォルトは next_val): テーブル構造にのみ該当。これは、値を保持する際に利用するテーブル上のカラム名です。
  • optimizer (オプション - デフォルトは none): 「識別子ジェネレータの最適化」を参照してください。
2つめのジェネレータは、org.hibernate.id.enhanced.TableGeneratorで、実際 org.hibernate.id.MultipleHiLoPerTableGeneratorのように機能するにもかかわらずtableジェネレータの代わりとされています。 次に、このジェネレータは、プラグ可能なオプティマイザの概念を利用する org.hibernate.id.MultipleHiLoPerTableGenerator の再実装とすることを目的としています。 必然的に、明確にキー付けされた行を複数利用することで、このジェネレータは様々なインクリメント値を同時に保持可能なテーブルを定義します。このジェネレータには様々な設定パラメータがあります:
  • table_name (オプション - デフォルトはhibernate_sequences): 使用されるテーブル名
  • value_column_name (オプション - デフォルトはnext_val): 値を保持するのに利用するテーブル上のカラム名。
  • segment_column_name (オプション - デフォルトはsequence_name): 「セグメントキー」を保持するのに利用するテーブル上のカラム名。 これはどのインクリメント値を利用するかを指定する値です。
  • segment_value (オプション - デフォルトは default): このジェネレータに対するインクリメント値を引き出したいと考えるセグメントの「セグメントキー」値。
  • segment_value_length (オプション - デフォルトは 255): スキーマ生成に使用;このセグメントキーコラムを作成するカラムサイズ。
  • initial_value (オプション - デフォルトは 1): テーブルから取得する初期値。
  • increment_size (オプション - デフォルトは 1): テーブルへの後続の呼出が異なる値。
  • optimizer (オプション - デフォルトは ): 「識別子ジェネレータの最適化」を参照してください。

5.1.6. 識別子ジェネレータの最適化

データベースに値を格納する識別子ジェネレータについて、新しい識別子の値を 生成するために呼出し毎(またはすべての呼出し)にデータベースをヒットするのは 効率がよくありません。代わりに、メモリ内のそれらを一つに集め、インメモリの値グループがいっぱいになったときにのみ データベースをヒットすることができます。これがプラグ可能なオプティマイザの役割です。現在、この操作をサポートするのは、 2つの拡張ジェネレータのみ (「拡張型の識別子ジェネレータ」 となっています。
  • none (通常、オプティマイザの指定がない場合これがデフォルトです。): この場合いかなる最適化も行われずすべてのリクエスト(およびリクエスト毎に)に対してデータベースをヒットします。
  • hilo: 値を取得するデータベースにて hi/lo アルゴリズムを適用します。 このオプティマイザに対するデータベースからの値はシーケンシャルとなります。 また、このオプティマイザについてデータベース構造から取得した値は、「グループ番号」 を示します。increment_size がメモリ内の値と乗じることで 「hi value」というグループを定義します。
  • pooled: hiloの場合、このオプティマイザは データベースへのヒット数を最小限に抑えようとします。しかし、ここでは、インメモリ のグループ化アルゴリズムと組み合わせた連続値ではなくデータベース構造に 「次のグループ」の開始値を格納するだけとなっています。ここでのincrement_size は、データベースから取った値を参照しています。

5.1.7. composite-id

<composite-id
        name="propertyName"
        class="ClassName"
        mapped="true|false"
        access="field|property|ClassName">
        node="element-name|."

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName class="ClassName" column="column_name"/>
        ......
</composite-id>
複合キーのあるテーブルに対し、識別子プロパティとしてクラスの複数のプロパティをマッピングすることができます。<composite-id> 要素は、子要素として <key-property> プロパティマッピングと <key-many-to-one> マッピングを受け入れます。
<composite-id>
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>
複合識別子の等価性を実装するためには、永続クラスが equals()hashCode() をオーバーライド しなければなりません 。また Serializable も実装しなければいけません。
残念ながら このアプローチは永続オブジェクトが自身の識別しであることを意味しています。オブジェクト自身を識別子とする以外に便利な「扱い方」はありません。複合キーに関連した永続状態を load() 出来るようになる前に、永続クラス自身をインスタンス化し、識別子プロパティを設定しなければなりません。組み込みの 複合識別子と呼ばれるこのアプローチは、本格的なアプリケーションには向いていません。
2つ目の方法は マップされた 複合識別子と呼ばれるもので、 <composite-id>エレメント内で指定した識別プロパティが永続クラスと分離した識別子クラスの両方に重複して存在します。
<composite-id class="MedicareId" mapped="true">
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id>
この例では、複合識別子クラス( MedicareId )とエンティティクラス自身の両方が、 medicareNumberdependent という名前のプロパティを持ちます。識別子クラスは、 equals()hashCode() をオーバライドし、 Serializable を実装しなくてはなりません。この方法の短所は、主にコードが重複するという点にあります。
次の属性はマッピングした複合識別子を指定するために使用します:
  • mapped (オプション - デフォルトは false ): マッピングした複合識別子が使用されることと、包含されたプロパティのマッピングが、エンティティクラスと複合識別子クラスの両方を参照することを示します。
  • class (オプション - ただしマッピングした複合識別子には必須): 複合識別子として使用するクラス。
3つ目のさらに便利な方法は、複合識別子を 「複合識別子としてのコンポーネント」 のコンポーネントクラスとして実装することです。下で記述している属性は、この代替方法にのみ適用されます:
  • name (オプション - このアプローチでは必須): 複合識別子を保持するコンポーネントタイプのプロパティ。詳細は9章を参照してください)。
  • access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。
  • class (オプション - デフォルトはリフレクションにより決定されるプロパティの型): 複合識別子として使われるコンポーネントのクラス。詳細は次の節を見てください。
この3つ目の方法は 識別子コンポーネント と呼び、ほとんどすべてのアプリケーションに対して推奨しています。

5.1.8. Discriminator

<discriminator> 要素は、 table-per-class-hierarchy マッピング戦略を使うポリモーフィックな永続化に必要であり、テーブルの識別子カラムを宣言します。識別子カラムは、ある特定の行に対して永続層がどのサブクラスをインスタンス化するかを伝えるマーカー値を含んでいます。利用できる一連の型は以下に制限されます: string , character , integer, byte , short , boolean , yes_no , true_false.
<discriminator
        column="discriminator_column"                       1
        type="discriminator_type"                           2
        force="true|false"                                  3
        insert="true|false"                                 4
        formula="arbitrary sql expression"                  5
/>

1

column(オプション - デフォルトは class ):識別子カラムの名前。

2

type (オプション - デフォルトは string ): Hibernate の型を示す名前。

3

force (オプション - デフォルトは false ):ルートクラスのすべてのインスタンスを検索する場合であっても、 Hibernate が使用可能な識別カラムの指定を「強制」します。

4

insert (オプション - デフォルトは true ):識別カラムがマッピングする複合識別子の一部であれば、 false と設定してください。Hibernate に SQL の INSERT 内のカラムを含ませないよう伝えます。

5

formula (オプション) 型が評価されるときに実行される任意の SQL 式。コンテンツベースの識別が可能になります。
識別カラムの実際の値は、 <class><subclass> 要素の discriminator-value 属性で指定されます。
永続クラスへマッピングされない「余分な」識別値を持つ行がテーブルにあれば、そのときに限り force 属性は有効です。ただし、普通はそういうことはありません。
formula 属性を使うと、行の型を評価するために任意の SQL 式を宣言できます:例えば、
<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="integer"/>

5.1.9. Version(オプション)

<version> 要素はオプションであり、テーブルがバージョンデータを含むことを示します。これは ロングトランザクション を使う予定であれば特に役立ちます。詳細は以下を参照してください。
<version
        column="version_column"                                       1
        name="propertyName"                                           2
        type="typename"                                               3
        access="field|property|ClassName"                             4
        unsaved-value="null|negative|undefined"                       5
        generated="never|always"                                      6
        insert="true|false"                                           7
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column (オプション - デフォルトはプロパティ名): バージョン番号を保持するカラムの名前。

2

name:永続クラスのプロパティ名。

3

type(オプション - デフォルトは integer):バージョン番号の型。

4

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。

5

unsaved-value (オプション - デフォルトは undefined ):インスタンスが新しくインスタンス化されたことを示す(保存されていないことを示す) バージョンプロパティの値。以前の Session で保存またはロードされた分離(Detached)インスタンスと区別するために使います。undefined は識別子プロパティの値が使われべきである点を指定します。

6

generated (オプション - デフォルトは never ): このバージョンのプロパティの値が、データベースによって生成されたことを指定します。詳細は「生成プロパティ」の議論を参照してください。

7

insert (オプション - デフォルトは true ): SQLの insert 文にバージョンカラムを含めるべきかどうかを指定します。データベースカラムのデフォルト値が 0 と定義される場合は、false に設定すると良いでしょう。
バージョン番号は Hibernate の longintegershorttimestampcalendar 型のいずれかです。
バージョンやタイムスタンプのプロパティは、分離されたインスタンスに対して null であってはなりません。そのためどのような unsaved-value 戦略が指定されても、 Hibernate は null のバージョンやタイムスタンプを持ったすべてのインスタンスを、一時的なものであると検知します。 null を許容するバージョンやタイムスタンプのプロパティを宣言することは、 Hibernate において過渡的に一時オブジェクトとすることを防ぐ簡単な方法です。特に識別子の割り当てや複合キーを使用しているときには特に有用です。

5.1.10. Timestamp(オプション)

オプションの <timestamp> 要素は、テーブルがタイムスタンプデータを含むことを示します。これはバージョン付けの代わりの方法として用意されています。タイムスタンプは楽観的ロックの中で安全性の低い実装ですが、時にアプリケーションがタイムスタンプを別の用途で使うこともあるかもしれません。
<timestamp
        column="timestamp_column"                                     1
        name="propertyName"                                           2
        access="field|property|ClassName"                             3
        unsaved-value="null|undefined"                                4
        source="vm|db"                                                5
        generated="never|always"                                      6
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column(オプション - デフォルトはプロパティ名): タイムスタンプを保持するカラムの名前。

2

name :永続クラスである Java の Date型または Timestamp 型 の、 JavaBeans スタイルプロパティの名前。

3

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

4

unsaved-value(オプション - デフォルトは null ):インスタンスが新しくインスタンス化された (保存されていない)ことを示すバージョンプロパティの値。以前の Session で保存またはロードされた分離(Detached)インスタンスと区別するために使われます。( undefined と指定すると、識別子プロパティの値を使う必要があります。

5

source (オプション - デフォルトは vm ): Hibernate はどこからタイムスタンプの値を取得するべきでしょうか?データベースからでしょうか、現在の JVM からでしょうか?データベースによるタイムスタンプは、 Hibernate が 「次の値」を決定するためにデータベースをヒットしなければならないため、オーバヘッドを招きます。しかしクラスタ環境では JVM から取得するより安全です。データベースの現在のタイムスタンプの取得をサポートするすべての Dialect が知られているわけではないことに注意してください。また一方で、精密さを欠くために、ロックで使用するには安全でないものもあります (例えば Oracle 8 )。

6

generated (オプション - デフォルトは never ): このタイムスタンプのプロパティの値が実際に、データベースによって生成されることを指定します。詳細は「生成プロパティ」 の議論を参照してください。

注記

<Timestamp><version type="timestamp"> と等価であることに注意してください。また、<timestamp source="db"><version type="dbtimestamp"> と等価であることに注意してください。

5.1.11. Property

<property> 要素は、クラスの永続的な JavaBean スタイルのプロパティを宣言します。
<property
        name="propertyName"                                           1
        column="column_name"                                          2
        type="typename"                                               3
        update="true|false"                                           4
        insert="true|false"                                           4
        formula="arbitrary SQL expression"                            5
        access="field|property|ClassName"                             6
        lazy="true|false"                                             7
        unique="true|false"                                           8
        not-null="true|false"                                         9
        optimistic-lock="true|false"                                  10
        generated="never|insert|always"                               11
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

1

name: 小文字で始まるプロパティ名。

2

column(オプション - デフォルトはプロパティ名): マッピングされたデータベーステーブルのカラムの名前。これはネストした <column> 要素でも指定できます。

3

type(オプション):Hibernate の型を示す名前。

4

update, insert(オプション - デフォルトは true ):マッピングされたカラムが SQL の UPDATE および/または INSERT に含まれることを指定します。両方をfalse に設定すると、同じカラムにマッピングされた他のプロパティやトリガや他のアプリケーション によって値が初期化された純粋な「導出」プロパティが可能になります。

5

formula(オプション):計算 プロパティのための値を定義する SQL 式。計算されたプロパティは自身のカラムへのマッピングがありません。

6

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

7

lazy (オプション - デフォルトは false ): インスタンス変数に最初にアクセスしたときに、プロパティを遅延して取得するよう指定します。バイトコード実装を作成する時間が必要になります。

8

unique (オプション):カラムにユニーク制約をつける DDL の生成を可能にします。また、property-ref のターゲットとすることもできます。

9

not-null (オプション):カラムに null 値を許可する DDL の生成を可能にします。

10

optimistic-lock (オプション - デフォルトは true ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。

11

generated (オプション - デフォルトは never ): プロパティの値が実際に、データベースによって生成されたことを指定します。 詳細は 「生成プロパティ」の議論を参照してください。
typename には以下の値が可能です:
  1. Hibernate の基本型の名前:例 integer, string, character, date, timestamp, float, binary, serializable, object, blob
  2. デフォルトの基本型の Java クラス名 :例 int, float, char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob など。
  3. シリアライズ可能な Java クラスの名前。
  4. カスタム型のクラス名:例 com.illflow.type.MyCustomType
型を指定しなければ、Hibernate は正しい Hibernate の型を推測するために、指定されたプロパティに対してリフレクションを使います。Hibernate はルール2, 3, 4をその順序に使い、getter プロパティの返り値のクラス名を解釈しようとします。しかしこれで常に十分であるとは限りません。場合によっては、 type 属性が必要な場合があります。例えば Hibernate.DATEHibernate.TIMESTAMP を区別するため、またはカスタム型を指定するためなどです。
access 属性で、実行時に Hibernate がどのようにプロパティにアクセスするかを制御できます。デフォルトでは Hibernate はプロパティの get/set のペアをコールします。access="field" と指定すれば、Hibernate はリフレクションを使い get/set のペアを介さずに、直接フィールドにアクセスします。インターフェース org.hibernate.property.PropertyAccessor を実装するクラスを指定することで、プロパティへのアクセスに独自の戦略を指定することができます。
特に強力な特徴は生成プロパティです。これらのプロパティは当然読み取り専用であり、プロパティの値はロード時に計算されます。計算を SQL 式として宣言すると、このプロパティはインスタンスをロードする SQL クエリの SELECT 句のサブクエリに変換されます:
<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>
特定のカラムのエイリアスを宣言することなく、エンティティ自身のテーブルを参照できることに注意してください。例では customerId がそれにあたります。 属性を使用したくない場合、ネストした <formula> マッピング要素を使えることにも注意してください。

5.1.12. Many-to-one

他の永続クラスへの通常の関連は many-to-one 要素を使って定義します。リレーショナルモデルは多対一関連です。つまりあるテーブルの外部キーは、ターゲットとなるテーブルの主キーカラムを参照しています。
<many-to-one
        name="propertyName"                                           1
        column="column_name"                                          2
        class="ClassName"                                             3
        cascade="cascade_style"                                       4
        fetch="join|select"                                           5
        update="true|false"                                           6
        insert="true|false"                                           6
        property-ref="propertyNameFromAssociatedClass"                7
        access="field|property|ClassName"                             8
        unique="true|false"                                           9
        not-null="true|false"                                         10
        optimistic-lock="true|false"                                  11
        lazy="proxy|no-proxy|false"                                   12
        not-found="ignore|exception"                                  13
        entity-name="EntityName"                                      14
        formula="arbitrary SQL expression"                            15
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        index="index_name"
        unique_key="unique_key_id"
        foreign-key="foreign_key_name"
/>

1

name:プロパティ名。

2

column (オプション):外部キーカラムの名前。ネストした <column> 要素によっても指定されます。

3

class(オプション - デフォルトはリフレクションにより決定されるプロパティの型):関連クラスの名前。

4

cascade(オプション):親オブジェクトから関連オブジェクトへ、どの操作をカスケードするかを指定します。

5

fetch(オプション - デフォルトは select ):外部結合フェッチと順次選択フェッチのどちらかを選択します。

6

update, insert(オプション - デフォルトは true ):マッピングされたカラムが SQL の UPDATE または INSERT 文に含まれることを指定します。両方をfalse に設定すると、その値が同じカラムにマッピングされた他のプロパティやトリガや他のアプリケーションによって初期化された純粋な「導出」プロパティが可能になります。

7

property-ref (オプション): 外部キーに結合された、 関連クラスのプロパティ名。指定されていない場合は、関連クラスの主キーを使用します。

8

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

9

unique(オプション):外部キーカラムに対してユニーク制約をつけた DDL の生成を可能にします。また、property-ref のターゲットにすることで、関連の多重度を効果的に一対一にします。

10

not-null (オプション): 外部キーカラムに対して、 null 値を許可する DDL の生成を可能にします。

11

optimistic-lock (オプション - デフォルトは true ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。

12

lazy (オプション - デフォルトは proxy ): デフォルトでは、多重度1の関連がプロキシとなります。 lazy="no-proxy" は、インスタンス変数に最初にアクセスしたときに、プロパティを遅延フェッチするよう指定します 。ビルド時にバイトコード実装が必要になります。 lazy="false" は関連を常に即時にフェッチするよう指定します。

13

not-found(オプション - デフォルトは exception): 参照先の行がない外部キーをどのように扱うかを指定します: ignore を指定すると、行がないことを関連がないものとして扱います。

14

entity-name (オプション):関連したクラスのエンティティ名。

15

formula (オプション): 計算された 外部キーに対して値を定義する SQL 式
cascade 属性に none 以外の意味のある値を設定すると、関連オブジェクトへある操作が伝播することになります。意味のある値は3つに分類することができます。1つ目は、 Hibernate の基本操作名のことで、 persist,merge, delete, save-update, evict, replicate, lock and refresh を含みます。2つ目は、特別な値でdelete-orphan、3つ目は操作名をカンマで区切った組み合わせのすべて(例:cascade="persist,merge,evict"cascade="all,delete-orphan")となっています。 詳しい説明は 「連鎖的な永続化」を参照してください。 値が一つの関連 (many-to-one と one-to-one関連) は、単独での削除 (orphan delete)をサポートしていないことに注意してください。
典型的な many-to-one 宣言は次の通りです。
<many-to-one name="product" class="Product" column="PRODUCT_ID"/>
property-ref 属性は、外部キーが関連テーブルのユニークキー(主キー以外)を参照しているレガシーデータをマップするためにだけ使うべきです。このリレーショナルモデルは複雑で分かりにくくなっています。例えば Product クラスが、主キーでないユニークなシリアルナンバーを持っていると仮定してみてください。unique 属性は SchemaExport ツールを使った Hibernate の DDL 生成を制御します。
<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>
以下のように OrderItem に対してマッピングを使えます:
<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>
しかし、これは推奨できません。
参照したユニークキーが、関連するエンティティの多数のプロパティから構成される場合、指定した <properties> 要素内で、参照するプロパティをマッピングするべきです。
参照したユニークキーがコンポーネントのプロパティである場合は、プロパティのパスを指定できます:
<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>

5.1.13. One-to-one

他の永続クラスへの一対一関連は、one-to-one 要素で定義します。
<one-to-one
        name="propertyName"                                           1
        class="ClassName"                                             2
        cascade="cascade_style"                                       3
        constrained="true|false"                                      4
        fetch="join|select"                                           5
        property-ref="propertyNameFromAssociatedClass"                6
        access="field|property|ClassName"                             7
        formula="any SQL expression"                                  8
        lazy="proxy|no-proxy|false"                                   9
        entity-name="EntityName"                                      10
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

1

name:プロパティ名。

2

class(オプション - デフォルトはリフレクションにより決定されるプロパティの型):関連クラスの名前。

3

cascade(オプション):親オブジェクトから関連オブジェクトへ、どの操作をカスケードするかを指定します。

4

constrained(オプション): マッピングされたテーブルの主キーに対する外部キー制約が、関連クラスのテーブルを参照することを指定します。このオプションは save()delete() がカスケードされる順序に影響し、そして関連がプロキシされるかどうかにも影響します 。そしてスキーマエクスポートツールにも使われます。

5

fetch(オプション - デフォルトは select ):外部結合フェッチと順次選択フェッチのどちらかを選択します。

6

property-ref(オプション):このクラスの主キーに結合された関連クラスのプロパティ名。指定されなければ、関連クラスの主キーが使われます。

7

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

8

formula (オプション): ほとんどすべての一対一関連は所有エンティティの 主キーへとマッピングされます。これ以外の稀な場合は、他のカラムや、 複数のカラム、 SQL 構文を使った結合するための式を指定できます。例は org.hibernate.test.onetooneformula を参照してください。

9

lazy (オプション - デフォルトは proxy ): デフォルトでは、多重度1の関連がプロキシとなります。 lazy="no-proxy" は、インスタンス変数に最初にアクセスしたときに、プロパティを遅延フェッチするよう指定します (ビルド時にバイトコード実装が必要になります)。lazy="false" は関連を常に即時にフェッチするよう指定します。 constrained="false" ならばプロキシは使用不可能となり、Hibernateは関連を即時にフェッチすることに注意してください。

10

entity-name (オプション):関連したクラスのエンティティ名。
一対一関連には2種類あります:
  • 主キー関連
  • ユニーク外部キー関連
主キー関連には、余分なテーブルカラムは必要ありません。2つの行が関連により関係していれば、2つのテーブルは同じ主キーの値を共有します。そのため2つのオブジェクトを主キー関連によって関連付けたい場合、確実に同じ識別子の値を代入しなければなりません。
主キー関連を行うためには、以下のマッピングを EmployeePerson のそれぞれに追加してください.
<one-to-one name="person" class="Person"/>
<one-to-one name="employee" class="Employee" constrained="true"/>
必ず、PERSON と EMPLOYEE テーブルの関係する行の主キーが同じであるように してください。ここでは、 foreign という特殊な Hibernate 識別子生成戦略を使います:
<class name="person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property">employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="employee"
        class="Employee"
        constrained="true"/>
</class>
新たに保存されたPerson のインスタンスが、そのPersonemployee プロパティで参照したEmployee インスタンス と同じ主キーの値を割り当てます。
もう1つの方法として、 Employee から Person へのユニーク制約を使った外部キー関連は以下のように表現することができます:
<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>
この関連は、以下の記述を Person のマッピングに追加することで双方向にすることができます:
<one-to-one name="employee" class="Employee" property-ref="person"/>

5.1.14. Natural-id

<natural-id mutable="true|false"/>
        <property ... />
        <many-to-one ... />
        ......
</natural-id>
主キーとして代理キーの使用を推奨しますが、すべてのエンティティに対して自然キーを識別するようにすべきです。自然キーはユニークかつ非 null な一つのプロパティ、またはプロパティの連結です。また、これは不変となっています。<natural-id> 要素内で自然キーのプロパティをマッピングします。 Hibernate は必然的にユニークなキーかつ null 値を許可する制約を生成し、その結果マッピングはより自己記述的になります。
エンティティの自然キープロパティの比較には、equals()hashCode() の実装をお勧めします。
このマッピングは自然主キーを使ったエンティティでの使用は視野にいれていません。
  • mutable (オプション、 デフォルトは false ): デフォルトでは、自然識別子プロパティは不変(定数)と想定されています。

5.1.15. Componentおよびdynamic-component

<component> 要素は、子オブジェクトのプロパティを親クラスのテーブルのカラムへマッピングします。代わりに、コンポーネントは自分のプロパティ、コンポーネント、コレクションを宣言することができます。以下の「コンポーネント」を見てください。
<component
        name="propertyName"                  1
        class="className"                    2
        insert="true|false"                  3
        update="true|false"                  4
        access="field|property|ClassName"    5
        lazy="true|false"                    6
        optimistic-lock="true|false"         7
        unique="true|false"                  8
        node="element-name|."
>
 
        <property ...../>
        <many-to-one .... />
        ........
</component>

1

name:プロパティ名。

2

class(オプション - デフォルトはリフレクションにより決定されるプロパティの型):コンポーネント(子)クラスの名前。

3

insert:マッピングされたカラムを SQL の INSERT に表しますか?

4

update:マッピングされたカラムが SQL の UPDATE に表しますか?

5

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

6

lazy (オプション - デフォルトは false ): インスタンス変数に最初にアクセスしたときに、コンポーネントを遅延してフェッチするよう指定します。ビルド時の バイトコード実装を作成する時間が必要になります。

7

optimistic-lock (オプション - デフォルトは true ): このプロパティの更新に、楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。

8

unique (オプション - デフォルトは false ): コンポーネントにあるマッピングされたカラムすべてに、ユニーク制約が存在するかを指定します。
子の <property> タグで、子のクラスのプロパティをテーブルカラムにマッピングします。
<component> 要素は、親エンティティへ戻る参照として、コンポーネントのクラスのプロパティをマッピングする <parent> サブ要素を許可します。
<dynamic-component> 要素は、 Map がコンポーネントとしてマッピングされることを可能にします。プロパティ名は map のキーを参照します。詳細は「動的コンポーネント」 を参照してください。

5.1.16. プロパティ

<properties> 要素はクラスのプロパティの指定された、論理的なグルーピングを可能にします。この構造の最も重要な使用方法は、 property-ref のターゲットになるプロパティの結合を許可することです。それはまた、複数カラムのユニーク制約を定義する簡単な方法でもあります。
<properties
        name="logicalName"                   1
        insert="true|false"                  2
        update="true|false"                  3
        optimistic-lock="true|false"         4
        unique="true|false"                  5
>
 
        <property ...../>
        <many-to-one .... />
        ........
</properties>

1

name : グルーピングの論理名。実際のプロパティ名では ありません

2

insert:マッピングされたカラムを SQL の INSERT に表しますか?

3

update:マッピングされたカラムが SQL の UPDATE に表しますか?

4

optimistic-lock (オプション - デフォルトは true ): これらのプロパティの更新に楽観的ロックの取得を要求するかどうかを指定します。このプロパティがダーティであるときにバージョンを増やすべきかを決定します。

5

unique (オプション - デフォルトは false ): コンポーネントにあるマッピングされたカラムすべてに、ユニーク制約が存在するかを指定します。
例えば、以下のような <properties> マッピングがあった場合:
<class name="Person">
    <id name="personNumber"/>

    ...
    <properties name="name"
            unique="true" update="false">
        <property name="firstName"/>
        <property name="initial"/>
        <property name="lastName"/>
    </properties>
</class>
主キーの代わりに Person テーブルにある このユニークキーを参照する、レガシーデータの関連を持つかもしれません:
<many-to-one name="person"
         class="Person" property-ref="name">
    <column name="firstName"/>
    <column name="initial"/>
    <column name="lastName"/>
</many-to-one>
しかし、このようなレガシーデータマッピングのコンテキスト外への使用は推奨しません。

5.1.17. Subclass

ポリモーフィックな永続化には、ルートの永続クラスの各サブクラスを定義する必要があります。table-per-class-hierarchy マッピング戦略では、<subclass> 定義が使われます。例えば、
<subclass
        name="ClassName"                               1
        discriminator-value="discriminator_value"      2
        proxy="ProxyInterface"                         3
        lazy="true|false"                              4
        dynamic-update="true|false"
        dynamic-insert="true|false"
        entity-name="EntityName"
        node="element-name"
        extends="SuperclassName">
 
        <property .... />
        .....
</subclass>

1

name:サブクラスの完全修飾されたクラス名。

2

discriminator-value(オプション - デフォルトはクラス名):個々のサブクラスを区別するための値。

3

proxy (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。

4

lazy (オプション、デフォルトは true ): lazy="false" とすると遅延フェッチが使用できません。
各サブクラスでは、永続プロパティとサブクラスを宣言します。<version><id> プロパティは、ルートクラスから継承されると仮定されます。階層構造におけるサブクラスは、ユニークな discriminator-value を定義しなければなりません。これが指定されていないと、完全修飾された Java クラス名が使われます。
継承のマッピングに関する情報は 9章継承マッピング  を参照してください。

5.1.18. Joined-subclass

各サブクラスを自身のテーブルへマッピングすることができ、これは、 table-per-subclass マッピング戦略と呼ばれています。継承した状態はスーパークラスのテーブルを使った結合で検索します。<joined-subclass> 要素を使用します。例えば、
<joined-subclass
        name="ClassName"                     1
        table="tablename"                    2
        proxy="ProxyInterface"               3
        lazy="true|false"                    4
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">
 
        <key .... >
 
        <property .... />
        .....
</joined-subclass>

1

name:サブクラスの完全修飾されたクラス名。

2

table :サブクラステーブルの名前。

3

proxy (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。

4

lazy (オプション、デフォルトは true ): lazy="false" と設定すると、遅延フェッチが無効になります。
このマッピング戦略には、識別カラムは必要ありません。しかし各サブクラスは <key> 要素を使い、オブジェクト識別子を保持するテーブルカラムを宣言しなければなりません。この章の初めのマッピングは以下のように書き直せます:
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat" table="CATS">
                <id name="id" column="uid" type="long">
                        <generator class="hilo"/>
                </id>
                <property name="birthdate" type="date"/>
                <property name="color" not-null="true"/>
                <property name="sex" not-null="true"/>
                <property name="weight"/>
                <many-to-one name="mate"/>
                <set name="kittens">
                        <key column="MOTHER"/>
                        <one-to-many class="Cat"/>
                </set>
                <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
                    <key column="CAT"/>
                    <property name="name" type="string"/>
                </joined-subclass>
        </class>

        <class name="eg.Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>
継承のマッピングに関する情報は 9章継承マッピング  を参照してください。

5.1.19. Union-subclass

3つ目の選択肢は、継承階層の具象クラスのみをテーブルにマッピングすることで、これは、table-per-concrete-class 戦略と呼ばれます。各テーブルは継承の状態を含めすべてのクラスの永続状態を定義します。Hibernate ではその様な継承階層が必要ではなく、単純に各クラスを、別々の <class> 宣言を使ってマッピングすることができます。しかしポリモーフィックな関連 (例えば階層のスーパークラスへの関連) を使いたい場合、<union-subclass> マッピングを使う必要があります。例えば、
<union-subclass
        name="ClassName"                     1
        table="tablename"                    2
        proxy="ProxyInterface"               3
        lazy="true|false"                    4
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        abstract="true|false"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">
 
        <property .... />
        ..... 
</union-subclass>

1

name:サブクラスの完全修飾されたクラス名。

2

table :サブクラステーブルの名前。

3

proxy (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。

4

lazy (オプション、デフォルトは true ): lazy="false" と設定すると、遅延フェッチが無効になります。
このマッピング戦略では識別カラムやキーカラムは必要ありません。
継承のマッピングに関する情報は 9章継承マッピング  を参照してください。

5.1.20. Join

テーブル間に一対一の関係があるとき、 <join> 要素を使うことで、1つのクラスのプロパティをいくつかのテーブルにマッピングすることができます。例えば、
<join
        table="tablename"                         1
        schema="owner"                            2
        catalog="catalog"                         3
        fetch="join|select"                       4
        inverse="true|false"                      5
        optional="true|false">                    6
 
        <key ... />
 
        <property ... />
        ...
</join>

1

table :結合したテーブルの名前。

2

schema (オプション): ルートの <hibernate-mapping> 要素で指定したスキーマ名をオーバーライドします。

3

catalog (オプション): ルートの <hibernate-mapping> 要素で指定したカタログ名をオーバーライドします。

4

fetch (オプション - デフォルトは join ): join を設定した場合、 Hibernate はデフォルトで、クラスやスーパークラスで定義された <join> を検索するのに内部結合を使い、サブクラスで定義された <join> を検索するのに外部結合を使います。select を設定した場合には、Hibernate はサブクラスで定義された <join> の選択に順次選択を使います。この場合、行がサブクラスのインスタンスを代表する場合にのみ発行されます。内部結合はクラスやそのスーパークラスで定義された <join> を検索するために使用します。

5

inverse (オプション - デフォルトは false ): 有効にすると、Hibernate はこの結合で定義されているプロパティに対し挿入や更新を行いません。

6

optional (オプション - デフォルトは false ): 有効にすると、 Hibernate はこの結合で定義されたプロパティが null でない場合にのみ行を挿入し、そのプロパティの検索には常に外部結合を使用します。
例えば、すべてのプロパティに対して値型のセマンティクスを保持しつつ、 人のアドレスの情報を別のテーブルにマッピングすることが可能です:
<class name="Person"
    table="PERSON">

    <id name="id" column="PERSON_ID">...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...
この特徴は通常、レガシーデータモデルに対してのみ有用ですが、推奨されるのは、クラスよりも テーブルを少なくし、きめの細かいドメインモデルを利用することです。しかし後で説明するように、1つのクラス階層で継承のマッピング戦略を切り替える時には有用です。

5.1.21. Key

このガイドで、今まで何度か <key> 要素が出てきましたが、親マッピング要素がオリジナルテーブルの主キーを参照する新規テーブルへの結合を定義 する場合、この要素はどこにでも出現し、結合テーブルでも外部キーを定義します。
<key
        column="columnname"                       1
        on-delete="noaction|cascade"              2
        property-ref="propertyName"               3
        not-null="true|false"                     4
        update="true|false"                       5
        unique="true|false"                       6
/>

1

column (オプション):外部キーカラムの名前。ネストした <column> 要素によっても指定されます。

2

on-delete (オプション - デフォルトは noaction): 外部キー制約がデータベースレベルでカスケード削除を有効にするかどうかを指定します。

3

property-ref (オプション): オリジナルテーブルの主キーではないカラムを参照する外部キーを指定します。これはレガシーデータに対して提供されます。

4

not-null (オプション): 外部キーカラムが null 値を許容しないことを指定します。このことは外部キーが主キーの一部であることを暗黙的に示します。

5

update (オプション): 外部キーを決して更新してはならないことを指定します。このことは外部キーが主キーの一部であることを暗黙的に示します。

6

unique (オプション): 外部キーがユニーク制約を持つべきであることを指定します。このことは外部キーが主キーの一部であることを暗黙的に示します、
削除のパフォーマンスが重要であるシステムには、すべてのキーを on-delete="cascade" と定義することを推奨します。そうすることで Hibernate は、多くのDELETE 文ではなくデータベースレベルの ON CASCADE DELETE 制約を使用します。この特徴はバージョン付けられたデータに対する Hibernate の通常の楽観的ロック戦略を無視するということに注意してください。
not-nullupdate 属性は、単方向一対多関連の時には有用です。単方向一対多関連を null を許容しない外部キーにマッピングするときは、 <key not-null="true"> を使ってキーカラムを宣言 しなくてはなりません

5.1.22. Column と formula 要素

column 属性を受け入れるマッピング要素は、代わりに<column> サブ要素を受け入れます。同様に <formula>formula 属性の 代わりとなります。例えば、
<column
        name="column_name"
        length="N"
        precision="N"
        scale="N"
        not-null="true|false"
        unique="true|false"
        unique-key="multicolumn_unique_key_name"
        index="index_name"
        sql-type="sql_type_name"
        check="SQL expression"
        default="SQL expression"/>
<formula>SQL expression</formula>
特殊な結合条件などを表現する、同様のプロパティや関連のマッピングの中で、 columnformula 属性を組み合わせることができます。
<many-to-one name="homeAddress" class="Address"
        insert="false" update="false">
    <column name="person_id" not-null="true" length="10"/>
    <formula>'MAILING'</formula>
</many-to-one>

5.1.23. Import

アプリケーションに同名の永続クラスが2つあり、Hibernate クエリで完全修飾された(パッケージの)名前を指定したくない場合は auto-import="true" に頼らず、明示的にクラスを 「インポート」することができます。また、明示的にマッピングされていないクラスやインターフェースもインポートできます。
<import class="java.lang.Object" rename="Universe"/>
<import
        class="ClassName"               1
        rename="ShortName"              2
/>

1

class: Java クラスの完全修飾されたクラス名。

2

rename(オプション - デフォルトは修飾されていないクラス名):クエリ言語で利用可能な名前。

5.1.24. Any

プロパティマッピングにはさらにもう1つの型があります。<any> マッピング要素は、複数のテーブルからクラスへのポリモーフィックな関連を定義します。この型のマッピングには必ず複数のカラムが必要です。1番目のカラムは関連エンティティの型を保持します。残りのカラムは識別子を保持します。この種類の関連には外部キー制約を指定することはできません。これは、ポリモーフィック な関連のマッピングをする通常の方法ではありません。ですから、 検査ログやユーザーセッションデータなど、特別な場合に限りこれを使うべきです。
meta-type により、アプリケーションはカスタム型を指定できます。このカスタム型はデータベースカラムの値を、id-type で指定した型の識別子プロパティを持った永続クラスへマッピングします。meta-type の値からクラス名へのマッピングを指定しなければなりません。
<any name="being" id-type="long" meta-type="string">
    <meta-value value="TBL_ANIMAL" class="Animal"/>
    <meta-value value="TBL_HUMAN" class="Human"/>
    <meta-value value="TBL_ALIEN" class="Alien"/>
    <column name="table_name"/>
    <column name="id"/>
</any>
<any
        name="propertyName"                       1
        id-type="idtypename"                      2
        meta-type="metatypename"                  3
        cascade="cascade_style"                   4
        access="field|property|ClassName"         5
        optimistic-lock="true|false"              6
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any>

1

name: プロパティ名。

2

id-type: 識別子の型。

3

meta-type(オプション - デフォルトは string ):ディスクリミネータマッピングで許されたいずれかの型。

4

cascade(オプション - デフォルトは none ): カスケードのスタイル。

5

access (オプション - デフォルトは property ): Hibernate がプロパティの値にアクセスするために使用する戦略。

6

optimistic-lock (オプション - デフォルトは true ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。このプロパティがダーティである場合にバージョンを増やすべきかを定義します。

5.2. Hibernate の型

5.2.1. エンティティと値

永続サービスに関して、Java言語レベルのオブジェクトは2つのグループに 分類されます。
エンティティはエンティティへの参照を保持する、他の オブジェクトから独立して存在します。参照されないオブジェクトがガベージコレクトされてしまう性質を持つ通常の Java モデルと、これを比べてみてください。 エンティティは明示的に保存および削除する必要があります。しかし、保存と削除は 親エンティティから子へ、保存と削除がカスケードされる ことがあります。これは到達可能性によるオブジェクト永続化の ODMG モデルとは異なっています。大規模なシステムでアプリケーションオブジェクトが普通どのように使われるかにより密接に対応します。エンティティは循環と参照の共有をサポートします。またそれらはバージョン付けすることもできます。
エンティティの永続状態は他のエンティティや 型のインスタンスへの参照から構成されます。値はプリミティブ、コレクション (コレクションの内部ではなく)、コンポーネント、不変オブジェクトです。エンティティとは違い、値は(特にコレクションとコンポーネントにおいて)、到達可能性による永続化や削除が 行われます 。値オブジェクトとプリミティブは、包含するエンティティと一緒に永続化や削除が行われるので、それらを独立にバージョン付けすることはできません。値には独立したアイデンティティがないので、2つのエンティティやコレクションがこれを共有することはできません。
これまで「永続クラス」という言葉をエンティティの意味で使ってきましたが、これからもそうしていきます。しかし、永続状態を持つユーザー定義のクラスのすべてがエンティティというわけではありません。 コンポーネント は値のセマンティクスを持つユーザー定義クラスです。java.lang.String 型のプロパティもまた値のセマンティクスを持ちます。この定義を前提とすると、 JDK で提供されているすべての Java の型 (クラス) が値のセマンティクスを持つといえます。一方ユーザー定義型は、エンティティや値型のセマンティクスとともにマッピングできます。この決定はアプリケーション開発者次第です。 ドメインモデルの エンティティクラスは通常、そのクラスの1つのインスタンスへ共有参照をしていますが、 一般的に合成集約や集約は、値型へ変換されます。
このリファレンスガイドの全体で何度もこの概念を取り上げます。
Java 型のシステム、および開発者が定義したエンティティと値型を SQL /データベース型のシステムにマッピングすることは困難ですが、Hibernate は2つのシステムの架け橋を提供します。エンティティに対しては <class><subclass> などを使用します。値型に対しては通常type 属性を持つ<property><component> などを使います。この属性の値は Hibernate の マッピング型 の名前です。Hibernate には、標準 JDK の値型に対して様々なマッピングが含まれています。自身のマッピング型を記述し、同様にカスタムの変換戦略を実装することができます。
コレクションを除いて、組み込みの Hibernate の型はすべて、 null セマンティクスをサポートします。

5.2.2. 基本的な型

組み込みの 基本的なマッピング型 は大まかに以下のように分けることができます。
integer, long, short, float, double, character, byte, boolean, yes_no, true_false
Java のプリミティブやラッパークラスから適切な(ベンダー固有の) SQL カラム型への型マッピング。 boolean, yes_notrue_false は、すべて Java の boolean または java.lang.Boolean の代替エンコードです。
string
java.lang.String から VARCHAR (または Oracle の VARCHAR2 )への型マッピング。
date, time, timestamp
java.util.Date とそのサブクラスから SQL 型の DATETIMETIMESTAMP (またはそれらと等価なもの) への型マッピング。
calendar, calendar_date
java.util.Calendar から SQL 型 の「 TIMESTAMPDATE (またはそれらと等価なもの)への型マッピング。
big_decimal, big_integer
java.math.BigDecimaljava.math.BigInteger から NUMERIC(または Oracle の NUMBER )への型マッピング。
locale, timezone, currency
java.util.Localejava.util.TimeZonejava.util.Currency から VARCHAR (または Oracle の VARCHAR2 )への型マッピング。 LocaleCurrency のインスタンスは、それらの ISO コードにマッピングされます。 TimeZone のインスタンスは、それらの ID にマッピングされます。
class
java.lang.Class から VARCHAR (または Oracle の VARCHAR2 )への型マッピング。 Class はその完全修飾された名前にマッピングされます。
binary
バイト配列は、適切な SQL のバイナリ型にマッピングされます。
text
長い Java 文字列は、 SQL の CLOB または TEXT 型にマッピングされます。
serializable
シリアライズ可能な Java 型は、適切な SQL のバイナリ型にマッピングされます。デフォルトで基本型ではないシリアライズ可能な Java クラスやインターフェースの名前を指定することで、Hibernate の型を serializable とすることもできます。
clob, blob
JDBC クラス java.sql.Clobjava.sql.Blob に対する型マッピング。blob や clob オブジェクトはトランザクションの外では再利用できないため、アプリケーションによってはこれらの型は不便かもしれません。さらにはドライバサポートが不完全で一貫していません。
imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, imm_serializable, imm_binary
可変と考えられるJava の型に対する型マッピング。Hibernate は不変な Java の型に対しては最適化を行い、アプリケーションはそれを不変オブジェクトとして扱います。例えば imm_timestamp としてマップしたインスタンスに対して、Date.setTime() を呼び出してはなりません。プロパティの値を変更しその変更を永続化するためには、アプリケーションはプロパティに対して、同一でない新規 オブジェクトを割り当てなければなりません。
エンティティとコレクションのユニークな識別子は、binaryblobclob を除く、どんな基本型でも構いません。また、複合識別子でも構いません。詳細は以下を参照してください。
基本的な値型には、 org.hibernate.Hibernate で定義された Type 定数がそれぞれあります。例えば、 Hibernate.STRINGstring 型を表現しています。

5.2.3. カスタム型

開発者が独自の値型を作成することは、比較的簡単です。例えば、java.lang.BigInteger 型のプロパティを VARCHAR カラムに永続化したいとします。Hibernate はこのための組み込み型を用意していません。しかしカスタム型は、プロパティ、またはコレクションの要素を1つのテーブルカラムにマッピングするのに制限はありません。そのため例えば、 FIRST_NAMEINITIALSURNAME カラムに永続化される、java.lang.String 型の getName() / setName() Java プロパティを持つ場合があります。
カスタム型を実装するには、org.hibernate.UserType または org.hibernate.CompositeUserType を実装し、その型の完全修飾された名前を使ってプロパティを宣言します。どのような種類のものが可能かを調べるには、org.hibernate.test.DoubleStringType を確認してください。
<property name="twoStrings" type="org.hibernate.test.DoubleStringType">
    <column name="first_string"/>
    <column name="second_string"/>
</property>
<column> タグで、プロパティを複数のカラムへマッピングできることに注目してください。
CompositeUserTypeEnhancedUserTypeUserCollectionTypeUserVersionType インターフェースは、より特殊な使用法に対してのサポートを提供します。
マッピングファイル内で UserType へもパラメータを提供できます。このためには、UserTypeorg.hibernate.usertype.ParameterizedType インターフェースを実装しなくてはなりません。 カスタム型パラメータを提供するために、マッピングファイル内で <type> 要素を使用できます。
<property name="priority">
    <type name="com.mycompany.usertypes.DefaultValueIntegerType">
        <param name="default">0</param>
    </type>
</property>
UserType は、引数として渡された Properties オブジェクトから、 default で指定したパラメータに対する値を検索することができます。
特定の UserType を定期的に使用する場合、短い名前を定義すると便利です。<typedef> 要素を使ってこのようなことが行えます。Typedefs はカスタム型に名前を割り当てます。そして、その型がパラメータを持つならば、パラメータのデフォルト値のリストを含むこともできます。
<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero">
    <param name="default">0</param>
</typedef>
<property name="priority" type="default_zero"/>
プロパティのマッピングで型パラメータを使うことで、 typedef で提供されたパラメータをその都度オーバーライドすることが可能です。
Hibernate の幅広い組み込み型とコンポーネントに対するサポートは、カスタム型をめったに 使わない ということを意味します。それでもなお、アプリケーションで頻出するエンティティ以外のクラスに対するカスタム型の使用は、よいやり方であるとみなされます。例えば MonetaryAmount クラスはコンポーネントとして簡単にマッピングできますが、 CompositeUserType の良い候補です。カスタム型を使用する理由の1つは抽象化です。カスタム型を使うことで、マッピングドキュメントは、通過値の表現方法 に変更があっても保護されます。

5.3. 1つのクラスに1つ以上のマッピング

ある永続クラスに、一つ以上のマッピングを提供することが出来ます。この場合、マッピングする2つのエンティティのインスタンスを明確にするために、 エンティティ名 を指定しなければなりません。デフォルトではエンティティ名はクラス名と同じです。Hibernate では、永続オブジェクトを扱うとき、クエリを書き込むとき、もしくは指定されたエンティティへの関連をマッピングするときに、エンティティ名を指定しなければなりません。
<class name="Contract" table="Contracts"
        entity-name="CurrentContract">
    ...
    <set name="history" inverse="true"
            order-by="effectiveEndDate desc">
        <key column="currentContractId"/>
        <one-to-many entity-name="HistoricalContract"/>
    </set>
</class>

<class name="Contract" table="ContractHistory"
        entity-name="HistoricalContract">
    ...
    <many-to-one name="currentContract"
            column="currentContractId"
            entity-name="CurrentContract"/>
</class>
class の代わりに entity-name を使って関連が指定されました。

5.4. バッククォートで囲んだ SQL 識別子

マッピングドキュメントでテーブルやカラムの名前をバッククォートで囲むことで、 Hibernate で生成された SQL 中の識別子を引用させることができます。Hibernate は SQL の Dialect に対応する、正しい引用スタイルを使います。通常はダブルクォートですが、 SQL Server では括弧、MySQL ではバッククォートを用います。
<class name="LineItem" table="`Line Item`">
    <id name="id" column="`Item Id`"/><generator class="assigned"/></id>
    <property name="itemNumber" column="`Item #`"/>
    ...
</class>

5.5. メタデータの代替手段

XMLはすべてのユーザーに向いているとは限らないため、 Hibernate では O/R マッピングのメタデータを定義する代替方法がいくつかあります。

5.5.1. XDoclet マークアップの使用

XDoclet の @hibernate.tags を使って、ソースコード内に直接マッピング情報を埋め込むことを好むユーザーが多数います。これは厳密に言えば XDoclet の分野なので、本ドキュメントではこの方法は取り上げません。 しかし XDoclet マッピングを使った以下の Cat クラスの例を示します。
package eg;
import java.util.Set;
import java.util.Date;

/**
 * @hibernate.class
 *  table="CATS"
 */
public class Cat {
    private Long id; // identifier
    private Date birthdate;
    private Cat mother;
    private Set kittens;
    private Color color;
    private char sex;
    private float weight;

    /*
     * @hibernate.id
     *  generator-class="native"
     *  column="CAT_ID"
     */
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id=id;
    }

    /**
     * @hibernate.many-to-one
     *  column="PARENT_ID"
     */
    public Cat getMother() {
        return mother;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }

    /**
     * @hibernate.property
     *  column="BIRTH_DATE"
     */
    public Date getBirthdate() {
        return birthdate;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    /**
     * @hibernate.property
     *  column="WEIGHT"
     */
    public float getWeight() {
        return weight;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }

    /**
     * @hibernate.property
     *  column="COLOR"
     *  not-null="true"
     */
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    /**
     * @hibernate.set
     *  inverse="true"
     *  order-by="BIRTH_DATE"
     * @hibernate.collection-key
     *  column="PARENT_ID"
     * @hibernate.collection-one-to-many
     */
    public Set getKittens() {
        return kittens;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kittens.add(kitten);
    }

    /**
     * @hibernate.property
     *  column="SEX"
     *  not-null="true"
     *  update="false"
     */
    public char getSex() {
        return sex;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
}
Hibernate のウェブサイトには、XDoclet と Hibernate に関するサンプルがほかにも多数あります。

5.5.2. JDK 5.0 アノテーションの使用

JDK5.0 ではタイプセーフかつコンパイル時にチェックできる、言語レベルの XDoclet スタイルのアノテーションを導入しました。このメカニズムは XDoclet のアノテーションよりも強力で、ツールや IDE も多くがサポートしています。例えば IntelliJ IDEA は、JDK5.0 にアノテーションの自動補完と構文の強調表示をサポートしています。EJB 仕様 (JSR-220) の新しいバージョンでは、エンティティ Bean に対する主要なメタデータメカニズムとして JDK5.0 のアノテーションを使用しています。Hibernate3 では JSR-220 (永続化 API) の EntityManager を実装し、メタデータマッピングに対するサポートは、 Hibernate Annotations パッケージを別途ダウンロードすることで 利用可能です。これは EJB3 (JSR-220) と Hibernate3 のメタデータをどちらもサポートしています。
以下は EJB のエンティティ Bean として注釈された POJO クラスの例です:
@Entity
public class Customer implements Serializable {

    @Id
    Long id;

    String firstName;
    String lastName;
    Date birthday;

    @Transient
    Integer age;

    @Embedded
    private Address homeAddress;

    @OneToMany(cascade=CascadeType.ALL)
    @JoinColumn(name="CUSTOMER_ID")
    Set<Order> orders;

    // Getter/setter and business methods
}

5.6. 生成プロパティ

生成プロパティとは、データベースによって生成された値を持つプロパティです。通常、 Hibernate アプリケーションは、データベースが値を生成したプロパティを含むオブジェクトを リフレッシュ する必要がありました。しかし、プロパティの生成をマークすることで、アプリケーションはリフレッシュの責任を Hibernate に委譲します。基本的に、生成プロパティを定義したエンティティに対して Hibernate が INSERT や UPDATE の SQL を発行した後すぐに、生成された値を取得するための SELECT SQL が発行されます。
生成とマークされたプロパティは他に、挿入不可能かつ更新不可能でなければなりません。「Version(オプション)」「Timestamp(オプション)」「Property」生成されたとマークできます。
never (デフォルト) - 与えられたプロパティの値は、データベースから生成されません。
insert:与えられたプロパティの値は挿入時に生成されるが、続いて起こる更新時には生成されません。作成された日付などのプロパティは、このカテゴリに分類されます。「Version(オプション)」「Timestamp(オプション)」のプロパティ は生成されたとマークは可能ですがこのオプションは利用できません。
always:挿入時も更新時もプロパティの値が生成されます。

5.7. 補助的なデータベースオブジェクト

任意のデータベースオブジェクトのCREATEとDROPに対し、補助的なデータベースオブジェクト が可能です。Hibernateのスキーマエボリューションツールと連動することで、 Hibernateマッピングファイル内でユーザースキーマを完全に定義することができます。主にトリガやストアドプロシージャのようなデータベースオブジェクトを生成や削除するように設計されていますが、実際には java.sql.Statement.execute() メソッドによって実行できる任意の SQL コマンド(ALTER、INSERTなど)が実行できます。基本的に、補助的なデータベースオブジェクトを定義するモードは2つ存在します。
1つ目のモードは、CREATE と DROP コマンドをマッピングファイル に明示的にリストすることです:
<hibernate-mapping>
    ...
    <database-object>
        <create>CREATE TRIGGER my_trigger ...</create>
        <drop>DROP TRIGGER my_trigger</drop>
    </database-object>
</hibernate-mapping>
2つ目のモードは、CREATE と DROP コマンドを構築するカスタムクラスを提供することです。このカスタムクラスは org.hibernate.mapping.AuxiliaryDatabaseObject インタフェースを実装しなければなりません。
<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
    </database-object>
</hibernate-mapping>
さらに、あるデータベース方言が使用される時にだけ適用するといったように、オプションでデータベースオブジェクトを使うケースを限定できます。
<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
        <dialect-scope name="org.hibernate.dialect.Oracle9iDialect"/>
        <dialect-scope name="org.hibernate.dialect.Oracle10gDialect"/>
    </database-object>
</hibernate-mapping>

第6章 コレクションのマッピング

6.1. コレクションの永続化

永続的なコレクション型のフィールドがインターフェース型として 宣言される必要があります。例えば、
public class Product {
    private String serialNumber;
    private Set parts = new HashSet();
    
    public Set getParts() { return parts; }
    void setParts(Set parts) { this.parts = parts; }
    public String getSerialNumber() { return serialNumber; }
    void setSerialNumber(String sn) { serialNumber = sn; }
}
実際のインターフェースには java.util.Setjava.util.Collectionjava.util.Listjava.util.Mapjava.util.SortedSetjava.util.SortedMap などがあります。または、任意のインターフェースが使えます。(ただし、「任意のインターフェース」を使用する場合は、 org.hibernate.usertype.UserCollectionType の実装クラスを作成する必要があります。)
HashSet のインスタンスを持つインスタンス変数がどのように初期化されるかに注目してみましょう。これは新たにインスタンス化された(永続化されていない)インスタンスのコレクション型プロパティを初期化する最適な方法です。persist()を呼び出すことで、インスタンスを永続化しようとしたとき、 Hibernate は HashSet を Hibernate 独自の Set の実装インスタンスに置き換えます。このため、次のようなエラーには注意が必要です。
Cat cat = new DomesticCat();
Cat kitten = new DomesticCat();
....
Set kittens = new HashSet();
kittens.add(kitten);
cat.setKittens(kittens);
session.persist(cat);
kittens = cat.getKittens(); // Okay, kittens collection is a Set
(HashSet) cat.getKittens(); // Error!
Hibernate により注入された永続性コレクションは、インターフェース型に応じて、 HashMapHashSetTreeMapTreeSetArrayList のように振舞います。
コレクションインスタンスは、値型として普通に動作します。永続化オブジェクトに参照されたときに自動的に永続化され、参照が外されると自動的に削除されます。ある永続化オブジェクトから別の永続化オブジェクトに渡された場合、その要素は現在のテーブルから別のテーブルに移動するかもしれません。2つのエンティティが同じコレクションインスタンスを共有してはいけません。リレーショナルモデルをベースにしているため、コレクション型のプロパティに null 値のセマンティクス をサポートしていません。つまり Hibernate は参照先のないコレクションと空のコレクションを区別しません。
普段使っている Java のコレクションと同じように、永続化コレクションを使ってください。しかし、 双方向関連の意味を理解するようにしてください(これは後ほど説明します)。

6.2. コレクションのマッピング

注記

多くの一般的なリレーショナルモデルに対応するコレクション向けに生成可能な マッピングにはかなりの幅があります。様々なマッピング宣言がどのようにデータベーステーブルに変換されるかを知るために、スキーマ生成ツールを使ってみると良いでしょう。
コレクションをマッピングする際に利用するHibernateマッピング要素は、インターフェースの型に依存します。例えば、<set> 要素は Set 型のプロパティをマッピングするために使います。
<class name="Product">
    <id name="serialNumber" column="productSerialNumber"/>
    <set name="parts">
        <key column="productSerialNumber" not-null="true"/>
        <one-to-many class="Part"/>
    </set>
</class>
マッピング要素には <set> の他に <list><map><bag><array><primitive-array> があります。代表として、 <map> 要素を下記に示します。
<map
    name="propertyName"                                          1
    table="table_name"                                           2
    schema="schema_name"                                         3
    lazy="true|extra|false"                                      4
    inverse="true|false"                                         5
    cascade="all|none|save-update|delete|all-delete-orphan|delete-orphan"    6
    sort="unsorted|natural|comparatorClass"                      7
    order-by="column_name asc|desc"                              8
    where="arbitrary sql where condition"                        9
    fetch="join|select|subselect"                                10
    batch-size="N"                                               11
    access="field|property|ClassName"                            12
    optimistic-lock="true|false"                                 13
    mutable="true|false"                                         14
    node="element-name|."
    embed-xml="true|false"
>
 
    <key .... />
    <map-key .... />
    <element .... />
</map>

1

name コレクションのプロパティ名

2

table(オプション - デフォルトはプロパティ名)コレクションテーブルの名前。これは一対多関連では使用しません。

3

schema (オプション)テーブルスキーマの名前。ルート要素で宣言されているスキーマより優先されます。

4

lazy(オプション - デフォルトは true)遅延フェッチを無効にし、関連を常に即時にフェッチにするために使用します。または、コレクションを初期化しない多くの操作において、 「extra-lazy」フェッチを有効にするために使用します。これは大きなコレクションに適しています。

5

inverse (オプション - デフォルトは false) このコレクションが双方向関連の「逆」側であるとマークします。

6

cascade (オプション - デフォルトは none):子エンティティへのカスケード操作を有効にします。

7

sort(オプション): naturalな順序でソートされた コレクションもしくは、ある Comparator クラスを指定します。

8

order-by(オプション、 JDK1.4 のみ)MapSet、bag のイテレーション順序を定義するテーブルカラムを指定すると共に、オプションとして ascdesc を指定します。

9

where (オプション)コレクションの検索や削除の際に使う任意の SQL のWHERE 条件を指定します。これは、利用可能なデータの一部分だけをコレクションが含むべきときにこれは有用です。

10

fetch(オプション - デフォルトは select) 外部結合によるフェッチ、順次選択フェッチ (sequential select fetch) 、順次サブセレクトフェッチ (sequential subselect fetch) のいずれかを選択してください。

11

batch-size(オプション - デフォルトは 1)このコレクションのインスタンスを遅延フェッチするために、「バッチサイズ」を指定します。

12

access(オプション - デフォルトは property)Hibernate がコレクションプロパティの値にアクセスするために使用する戦略です。

13

optimistic-lock (オプション - デフォルトは true) コレクションの状態を変えることによって、そのオーナーであるエンティティのバージョンがインクリメントされるかを指定します。一対多関連では無効に設定するのが妥当です。

14

mutable(オプション - デフォルトは truefalse 値は、コレクションの要素が決して変更されないことを表します。一部の場合で若干パフォーマンスを高めることができます。

6.2.1. コレクションの外部キー

コレクションのインスタンスは、データベース内では、そのコレクションを所有するエンティティの外部キーによって識別されます。この外部キーはコレクションテーブルの コレクションキーカラム またはカラムと呼ばれます。コレクションキーカラムは <key> 要素によりマッピングします。
外部キーカラムには null 設定制約があるかもしれません。ほとんどのコレクションに当てはまるでしょう。単方向の一対多関連において、外部キーカラムはデフォルトで null を許容する設定になっています。よって、not-null="true" を指定する必要があるかもしれません。
<key column="productSerialNumber" not-null="true"/>
外部キーの制約が ON DELETE CASCADE を使う場合もあります。
<key column="productSerialNumber" on-delete="cascade"/>
<key> 要素のすべての定義については前の章を参照してください。

6.2.2. コレクションの要素

コレクションは、すべての基本型、カスタム型、コンポーネント、他のエンティティへの参照など、他の Hibernate の型のほとんどを格納することができます。 次の点は重要な違いになります。コレクション内のオブジェクトが「値」セマンティクスとして扱われるのか (ライフサイクルはコレクションのオーナーに完全に依存します)、もしくはそれ自身のライフサイクルを持った別のエンティティへの参照であるかのかという違いです。後者は、2つのオブジェクト間の「リンク」をコレクションに保持していると見なしているだけです。
格納される型は コレクション要素型 と呼ばれます。コレクション要素は、 <element> または <composite-element> によりマッピングされ、エンティティへの参照の場合には <one-to-many> または <many-to-many> によりマッピングされます。最初の二つは値として要素をマッピングし、次の二つはエンティティの関連をマッピングするのに使われます。

6.2.3. インデックス付きのコレクション

set と bag を除く全てのコレクションマッピングには、コレクションテーブルの中に インデックス用のカラム が必要です。そのカラムに、配列や List のインデックス、もしくは Map のキーをマッピングします。 Map のインデックスは、 <map-key> によりマッピングされた基本型か、 <map-key-many-to-many> によりマッピングされたエンティティの関連か、あるいは <composite-map-key> によりマッピングされたコンポジット型になります。配列かリストのインデックスは、常に integer 型で、 <list-index> 要素によりマッピングします。マッピングされたカラムにはシーケンシャルな整数を格納します。デフォルトでは0から番号が付けられます。
<list-index 
        column="column_name"                 1
        base="0|1|..."                       2
/>

1

column_name (必須): コレクションインデックスの値を保持するカラム名。

2

base (オプション - デフォルトでは0): リスト もしくはアレイの最初の要素に対応するインデックス カラムの値
<map-key 
        column="column_name"                 1
        formula="any SQL expression"         2
        type="type_name"                     3
        node="@attribute-name"
        length="N"/>

1

column (オプション): コレクションインデックスの値を保持するカラム名。

2

formula (オプション):マップのキーを評価する際に利用する SQL 式。

3

type (必須): マップキーの型
<map-key-many-to-many
        column="column_name"                 1
        formula="any SQL expression"         2
        class="ClassName"                    3
/>

1

column (オプション): コレクションインデックスの値に対する外部キーカラム名

2

formula (オプション): マップキーの外部キーを評価する際に利用するSQL 式。

3

class (必須): マップキーとして利用するエンティティクラス。
テーブルにインデックスカラムがなくても、プロパティ型として List を使いたい場合、Hibernate の <bag> としてプロパティをマッピングすることが可能です。bag はデータベースから取得される時、順序を保持しませんが、オプションでソートまたは順序付けを行うことできます。

6.2.4. 値のコレクションと多対多関連

値のコレクションや多対多関連は、外部キーカラムと、 コレクション要素のカラム と、場合によってはインデックスカラムを伴う、 専用の コレクションテーブル が必要です。
値のコレクションについては、 <element> タグを使用します。
<element
        column="column_name"                      1
        formula="any SQL expression"              2
        type="typename"                           3
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>

1

column (オプション): コレクション要素の値を保持するカラム名。

2

formula (オプション): 要素を評価する際に利用するSQL 式。

3

type (必須): コレクション要素の型。
多対多関連 は、<many-to-many> 要素を利用して指定します。
<many-to-many
        column="column_name"                                1
        formula="any SQL expression"                        2
        class="ClassName"                                   3
        fetch="select|join"                                 4
        unique="true|false"                                 5
        not-found="ignore|exception"                        6
        entity-name="EntityName"                            7
        property-ref="propertyNameFromAssociatedClass"      8
        node="element-name"
        embed-xml="true|false"
    />

1

column (オプション): 外部キーカラムの要素名。

2

formula (オプション): 外部キー値の要素を評価する際に利用する SQL 式。

3

class(必須): 関連クラスの名前。

4

fetch (オプション - デフォルトでは join): この関連にたいする外部結合もしくは順次選択フェッチを有効にします。 以下は特別なケースです;あるエンティティの単数SELECTにおける完全即時フェッチ、そして他のエンティティとの多対多関係については、 コレクション自体のみにだけでなく、<many-to-many> にネストした要素にある属性についてもjoinフェッチを有効にします。

5

unique (オプション): 外部キーカラムに対し、一意制約のDDL生成を 有効にします。関連の多重度を効果的に一対多に変更します。

6

not-found (オプション - デフォルトは exception): 参照先の行がない外部キーをどのように処理するか指定します:ignore は、行がないことを関連がないものとして扱います。

7

entity-name (オプション):class の代わりとなる、 関連クラスのエンティティ名。

8

property-ref (オプション): 外部キーに結合された、 関連クラスのプロパティ名。指定されていない場合は、関連クラスの主キーを使用します。
以下にいくつかの例を挙げています。
文字列セット:
<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set>
order-by 属性が決定した反復順序となっている整数を含むbag
<bag name="sizes" 
        table="item_sizes" 
        order-by="size asc">
    <key column="item_id"/>
    <element column="size" type="integer"/>
</bag>
エンティティの配列、この場合多対多の関連です。
<array name="addresses" 
        table="PersonAddress" 
        cascade="persist">
    <key column="personId"/>
    <list-index column="sortOrder"/>
    <many-to-many column="addressId" class="Address"/>
</array>
文字列と日付の map
<map name="holidays" 
        table="holidays" 
        schema="dbo" 
        order-by="hol_name asc">
    <key column="id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>
コンポーネントのリスト(次の章で説明します)
<list name="carComponents" 
        table="CarComponents">
    <key column="carId"/>
    <list-index column="sortOrder"/>
    <composite-element class="CarComponent">
        <property name="price"/>
        <property name="type"/>
        <property name="serialNumber" column="serialNum"/>
    </composite-element>
</list>

6.2.5. 一対多関連

一対多関連 は、コレクションテーブルを介さず、外部キーにより2つのクラスのテーブルを関連付けます。このマッピングは標準的な Java のコレクションにある特定のセマンティクスを失います:
  • 包含されたエンティティクラスのインスタンスは、2つ以上のコレクションのインスタンスに属してはいけません。
  • コレクションに含まれるエンティティクラスのインスタンスは、コレクションインデックスの値として2度以上現れてはいけません。
Product から Part への関連は、 Part テーブルへの外部キーカラムと、場合によってはインデックスカラムが存在していなければなりません。 <one-to-many> タグは、これが一対多関連であることを表しています。
<one-to-many 
        class="ClassName"                                   1
        not-found="ignore|exception"                        2
        entity-name="EntityName"                            3
        node="element-name"
        embed-xml="true|false"
    />

1

class(必須): 関連クラスの名前。

2

not-found (オプション - デフォルトは exception): 参照先の行がないキャッシュされた識別子をどのように扱うかを指定します: ignore は、行がないことを関連がないものとして扱います。

3

entity-name (オプション):class の代わりとなる、 関連クラスのエンティティ名。
<one-to-many> 要素はいかなるカラムを宣言する必要がないことに注意してください。同様に どこにもテーブル 名を指定する必要もありません。

警告

<one-to-many> 関連の外部キーカラムが NOT NULLと宣言された場合、<key> マッピングに not-null="true" を宣言するか、コレクションマッピングに inverse="true" を付けた上で、 双方向関連を使う 必要があります。双方向関連の詳細情報についてはこの章で後述します。
次の例は、名称(Part の永続的なプロパティである partName) による Part エンティティの マップを表しています。関数ベースのインデックスを使っていることに注意してください。
<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map>

6.3. 高度なコレクションマッピング

6.3.1. ソートされたコレクション

Hibernate は java.util.SortedMapjava.util.SortedSet を実装したコレクションをサポートしています。開発者はマッピング定義ファイルにコンパレータを指定しなければなりません:
<set name="aliases" 
            table="person_aliases" 
            sort="natural">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" sort="my.custom.HolidayComparator">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map>
sort 属性に設定できる値は unsortednatural および、 java.util.Comparator を実装したクラスの名前です。
ソートされたコレクションは実質的には java.util.TreeSetjava.util.TreeMap のように振舞います。
データベース自身にコレクションの要素を並べさせたい場合、setbagmap マッピングの order-by 属性を使います。この解決法は JDK1.4 、もしくはそれ以上のバージョンで利用可能で、LinkedHashSet または LinkedHashMapを使って実装されています。これはメモリ上ではなく、SQL クエリ内で整列の実行されます。
<set name="aliases" table="person_aliases" order-by="lower(name) asc">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" order-by="hol_date, hol_name">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date type="date"/>
</map>

注記

order-by 属性の値は、HQL 命令ではなくSQL 命令となっています。
関連は、コレクションの filter() を使うことで、実行時に任意の criteria によってソートすることも可能です:
sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();

6.3.2. 双方向関連

双方向関連 は関連のどちら「側」からでもナビゲーションできます。2種類の双方向関連がサポートされています:
one-to-many
片側が set か bag の値、もう片方が単一値です。
many-to-many
両側が set か bag です。
2つの多対多関連を同じデータベーステーブルにマッピングし、片方を inverse として宣言することで、双方向の多対多関連を指定することが出来ます。インデックス付きのコレクションは使えません。
以下は双方向の多対多関連の例です。この例では、どのように各カテゴリは多数のアイテムを持つことができ、各アイテムは多くのカテゴリに属することが出来るかを示しています。
<class name="Category">
    <id name="id" column="CATEGORY_ID"/>
    ...
    <bag name="items" table="CATEGORY_ITEM">
        <key column="CATEGORY_ID"/>
        <many-to-many class="Item" column="ITEM_ID"/>
    </bag>
</class>

<class name="Item">
    <id name="id" column="ITEM_ID"/>
    ...

    <!-- inverse end -->
    <bag name="categories" table="CATEGORY_ITEM" inverse="true">
        <key column="ITEM_ID"/>
        <many-to-many class="Category" column="CATEGORY_ID"/>
    </bag>
</class>
関連の inverse 側にのみ行われた変更は永続化されません。これは、Hibernate は全ての双方向関連について、メモリ上に2つの表現を持っているという意味です。つまり一つは A から B へのリンクで、もう一つは B から A へのリンクです。Java のオブジェクトモデルで Java 言語で双方向関係をどのように作るかを考えれば、これは理解しやすいです。
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
関連の inverse ではない側は、メモリ上の表現をデータベースに保存するのに使われます。
双方向の一対多関連を定義するには、一対多関連を多対一関連と同じテーブルのカラムにマッピングし、多側に inverse="true" と宣言します。
<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <set name="children" inverse="true">
        <key column="parent_id"/>
        <one-to-many class="Child"/>
    </set>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class>
関連の片側に inverse="true" をマッピングしても、これらは直交概念であるため、カスケード操作に影響を与えません。

6.3.3. インデックス付きコレクションと双方向関連

片側が <list><map> で表現される 双方向関連は、特別な考慮が必要です。インデックスカラムにマップされる子クラスのプロパティがある場合は、コレクションのマッピングで inverse="true" を使い続けることができます。
<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children" inverse="true">
        <key column="parent_id"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <property name="name" 
        not-null="true"/>
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class>
しかし、子クラスにそのようなプロパティがない場合は、関連を真に双方向であるとすることができません。つまり、関連の片側に利用できる情報がありますが、もう一方にはありません。この場合は、コレクションに inverse="true" をマッピングできません。代わりに、次のようなマッピングが使えます:
<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children">
        <key column="parent_id"
            not-null="true"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        insert="false"
        update="false"
        not-null="true"/>
</class>
注意:このマッピングでは、関連のコレクション値の側は、外部キーのアップデートを担当しています。

6.3.4. 3項関連

3項関連のマッピングには3つのアプローチがあります。1 つ目は関連をそのインデックスとして Map を使用するアプローチです:
<map name="contracts">
    <key column="employer_id" not-null="true"/>
    <map-key-many-to-many column="employee_id" class="Employee"/>
    <one-to-many class="Contract"/>
</map>
<map name="connections">
    <key column="incoming_node_id"/>
    <map-key-many-to-many column="outgoing_node_id" class="Node"/>
    <many-to-many column="connection_id" class="Connection"/>
</map>
2つ目は単純に関連をエンティティクラスとしてモデルを作り直すアプローチで、 最も一般的です。
最後は composite 要素を使うアプローチです。これに関する議論は後ほど行います。

6.3.5. <idbag>の使用

エンティティは合成識別子(代理キー)を持つべきだと提唱されていましたが、 以前に示した多対多関連と値のコレクションの多くはすべて、複合キーでテーブルに マッピングされています。合成値のコレクションには利点がある かも しれませんが純粋な関連テーブルは代理キーを使っても特に利点があるとは思えません。 このような理由で、Hibernate は代理キーを持つテーブルへ多対多関連と値のコレクションをマッピングできる機能も備えています。
<idbag> 要素では、bag のセマンティックスを持つList(または Collection)をマッピングできます。例えば、
<idbag name="lovers" table="LOVERS">
    <collection-id column="ID" type="long">
        <generator class="sequence"/>
    </collection-id>
    <key column="PERSON1"/>
    <many-to-many column="PERSON2" class="Person" fetch="join"/>
</idbag>
<idbag> はエンティティクラスのように人工的な id ジェネレータを持っており、異なる代理キーをそれぞれのコレクションの列に割り当てます。しかし、Hibernate はある行の代理キーの値を見つけ出すメカニズムを持っていません。
<idbag> 更新のパフォーマンスは通常の <bag> よりも勝ります。Hibernate は個々の行を効率的に見つけることができ、 list や map 、set のように個別にその行を更新、削除できます。
現在の実装では、 native という id 生成戦略を <idbag> コレクションの識別子に対して使えません。

6.4. コレクションの例

この項ではコレクションの例を見ていきます。
以下のクラスには、 Child インスタンスのコレクションが含まれます。
package eg;
import java.util.Set;

public class Parent {
    private long id;
    private Set children;

    public long getId() { return id; }
    private void setId(long id) { this.id=id; }

    private Set getChildren() { return children; }
    private void setChildren(Set children) { this.children=children; }

    ....
    ....
}
それぞれの子が多くても一つの親を持っている場合、最も自然なマッピングは一対多関連です。
<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping>
これは以下のテーブル定義にマッピングします。
create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255), parent_id bigint )
alter table child add constraint childfk0 (parent_id) references parent
親を必要とする場合、双方向の一対多関連を使用してください:
<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" inverse="true">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
        <many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/>
    </class>

</hibernate-mapping>
NOT NULL 制約に注意してください。
create table parent ( id bigint not null primary key )
create table child ( id bigint not null
                     primary key,
                     name varchar(255),
                     parent_id bigint not null )
alter table child add constraint childfk0 (parent_id) references parent
あるいは、この関連が単方向でなければならない場合、 <key> マッピングに NOT NULL 制約を宣言できます:
<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id" not-null="true"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping>
一方で、子が複数の親を持てるならば、多対多関連が妥当です:
<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" table="childset">
            <key column="parent_id"/>
            <many-to-many class="Child" column="child_id"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping>
テーブル定義は以下のようになります:
create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255) )
create table childset ( parent_id bigint not null,
                        child_id bigint not null,
                        primary key ( parent_id, child_id ) )
alter table childset add constraint childsetfk0 (parent_id) references parent
alter table childset add constraint childsetfk1 (child_id) references child
親子関係のマッピングについてのより多くの例や完全な説明が必要な場合は、 21章例: 親/子 をご覧ください。
また、さらに複雑な関連マッピングについては次の章で説明します。

第7章 関連マッピング

7.1. 概要

関連マッピングは多くの場合、正しく実装するのは最も難しいとされています。この章では、基本的なケースを1つずつ検証します。単方向のマッピングから始め、それから双方向のケースに移っていきます。例ではすべてPersonAddress を用います。
関連は、介在している結合テーブルにマッピングするかどうかと、多重度によって分類することにします。
null 可能な外部キーは従来型データモデリングの中では良い慣習と見なされていないため、null可能な外部キーを使用している例はありません。これは Hibernate の要件ではなく、null の代入が可能かの制約を外したとしても、マッピングは問題なく動作します。

7.2. 単方向関連

7.2.1. Many-to-one

単方向多対一関連 は単方向関連の中で最も一般的なものです。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )

7.2.2. One-to-one

外部キーの単方向一対一関連 はほとんど同じものです。唯一違うのは、カラムのユニークな制約です。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId" 
        unique="true"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
主キーの単方向一対一関連 は通常、特別な ID ジェネレータを使います。しかしこの例では関連の方向が逆になっていることに注意してください。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
</class>

<class name="Address">
    <id name="id" column="personId">
        <generator class="foreign">
            <param name="property">person</param>
        </generator>
    </id>
    <one-to-one name="person" constrained="true"/>
</class>
create table Person ( personId bigint not null primary key )
create table Address ( personId bigint not null primary key )

7.2.3. 一対多(One-to-many)

外部キーの単方向一対多関連 はとても特殊なケースで、推奨されていません。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses">
        <key column="personId" 
            not-null="true"/>
        <one-to-many class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key )
create table Address ( addressId bigint not null primary key, personId bigint not null )
代わりに、このような関連のために結合テーブルを使うべきです。

7.3. 結合テーブルを使った単方向関連

7.3.1. 一対多(One-to-many)

結合テーブルを使った単方向一対多関連 では こちらのオプションが推奨されています。unique="true" を指定すると、多重度が多対多から一対多に変わります。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            unique="true"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId not null, addressId bigint not null primary key )
create table Address ( addressId bigint not null primary key )

7.3.2. Many-to-one

関連が任意の場合、通常結合テーブルの単方向多対一関連 と なっています。例えば、
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )

7.3.3. One-to-one

結合テーブルの単方向一対一関連 は、非常に特殊ですが不可能ではありません。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" 
            unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"
            unique="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )

7.3.4. 多対多(Many-to-many)

最後に、ここで単方向多対多関連 を示します。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
create table Address ( addressId bigint not null primary key )

7.4. 双方向関連

7.4.1. 一対多(One to many)/多対一(many to one)

双方向多対一関連 は最も一般的な関連です。以下の例で標準的な親子関係を示しています。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true">
        <key column="addressId"/>
        <one-to-many class="Person"/>
    </set>
</class>
create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
List (または他のインデックス付きのコレクション)を使う場合、 外部キーの key カラムを not null に設定します。Hibernateは、コレクション側からの関連を管理し、各要素のインデックスをメンテナンスします。 結果、update="false" かつ insert="false" と設定することで、仮想的に反対側をinverseにします。
<class name="Person">
   <id name="id"/>
   ...
   <many-to-one name="address"
      column="addressId"
      not-null="true"
      insert="false"
      update="false"/>
</class>

<class name="Address">
   <id name="id"/>
   ...
   <list name="people">
      <key column="addressId" not-null="true"/>
      <list-index column="peopleIdx"/>
      <one-to-many class="Person"/>
   </list>
</class>
外部キーカラムが NOT NULL であるならば、コレクションマッピングの <key> 要素を not-null="true" と定義することは重要です。入れ子になった <column> 要素だけではなく、 <key> 要素も not-null="true" と宣言しないようにしてください。

7.4.2. One-to-one

外部キーの双方向一対一関連 は一般的です。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId" 
        unique="true"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
   <one-to-one name="person" 
        property-ref="address"/>
</class>
create table Person ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )
主キーの双方向一対一関連 は特殊な ID ジェネレータを使います。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <one-to-one name="address"/>
</class>

<class name="Address">
    <id name="id" column="personId">
        <generator class="foreign">
            <param name="property">person</param>
        </generator>
    </id>
    <one-to-one name="person" 
        constrained="true"/>
</class>
create table Person ( personId bigint not null primary key )
create table Address ( personId bigint not null primary key )

7.5. 結合テーブルを使った双方向関連

7.5.1. 一対多(One to many)/多対一(many to one)

以下は結合テーブルの双方向一対多関連 の例となっています。inverse="true" は関連端、コレクション、結合のいずれかに設定できるようになっています。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" 
        table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            unique="true"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        inverse="true" 
        optional="true">
        <key column="addressId"/>
        <many-to-one name="person"
            column="personId"
            not-null="true"/>
    </join>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null primary key )
create table Address ( addressId bigint not null primary key )

7.5.2. 一対一(One to one)

結合テーブルの双方向一対一関連 は非常に特殊ですが、可能です。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true">
        <key column="personId" 
            unique="true"/>
        <many-to-one name="address"
            column="addressId" 
            not-null="true"
            unique="true"/>
    </join>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <join table="PersonAddress" 
        optional="true"
        inverse="true">
        <key column="addressId" 
            unique="true"/>
        <many-to-one name="person"
            column="personId" 
            not-null="true"
            unique="true"/>
    </join>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null primary key, addressId bigint not null unique )
create table Address ( addressId bigint not null primary key )

7.5.3. 多対多(Many-to-many)

ここで、双方向多対多関連 の例を示します。
<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <set name="addresses" table="PersonAddress">
        <key column="personId"/>
        <many-to-many column="addressId"
            class="Address"/>
    </set>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true" table="PersonAddress">
        <key column="addressId"/>
        <many-to-many column="personId"
            class="Person"/>
    </set>
</class>
create table Person ( personId bigint not null primary key )
create table PersonAddress ( personId bigint not null, addressId bigint not null, primary key (personId, addressId) )
create table Address ( addressId bigint not null primary key )

7.6. より複雑な関連マッピング

より複雑な関連結合は 極めて 稀です。Hibernate は、マッピングドキュメントに埋め込まれたSQL フラグメントを使用することで、さらに複雑な状況を扱うことができます。例えば、 accountNumbereffectiveEndDateeffectiveStartDate カラムを持つ account (口座)情報の履歴を扱うテーブルは、以下のようにマッピングします。
<properties name="currentAccountKey">
    <property name="accountNumber" type="string" not-null="true"/>
    <property name="currentAccount" type="boolean">
        <formula>case when effectiveEndDate is null then 1 else 0 end</formula>
    </property>
</properties>
<property name="effectiveEndDate" type="date"/>
<property name="effectiveStateDate" type="date" not-null="true"/>
そして、関連を 現時点の インスタンス (effectiveEndDate が null であるもの)にマッピングします。以下のようになります:
<many-to-one name="currentAccountInfo" 
        property-ref="currentAccountKey"
        class="AccountInfo">
    <column name="accountNumber"/>
    <formula>'1'</formula>
</many-to-one>
さらに複雑な例では、Employee(従業員)Organization(組織) 間の関連が Employment(雇用) テーブルで保持される場合を想像してください。このテーブルには雇用データの履歴がすべて含まれます。すると従業員の 最も最近の 雇用者を表す関連 (最も最近の startDate を持つもの)は、このようにマッピングできます:
<join>
    <key column="employeeId"/>
    <subselect>
        select employeeId, orgId 
        from Employments 
        group by orgId 
        having startDate = max(startDate)
    </subselect>
    <many-to-one name="mostRecentEmployer" 
            class="Organization" 
            column="orgId"/>
</join>
この機能で創造性、柔軟性の幅が出すことができますが、このような場合、普通は HQL や criteria クエリを使う方がより実践的です。

第8章 コンポーネントのマッピング

コンポーネント の概念は、Hibernate 全体で様々な状況や目的に再利用されます。

8.1. 依存オブジェクト

コンポーネントは、エンティティの参照ではなく値型として永続化された、包含オブジェクトです。「コンポーネント」という言葉については、アーキテクチャレベルのコンポーネントではなく、コンポジションというオブジェクト指向の概念を参照してください。例えば、以下ように Personをモデル化できます。
public class Person {
    private java.util.Date birthday;
    private Name name;
    private String key;
    public String getKey() {
        return key;
    }
    private void setKey(String key) {
        this.key=key;
    }
    public java.util.Date getBirthday() {
        return birthday;
    }
    public void setBirthday(java.util.Date birthday) {
        this.birthday = birthday;
    }
    public Name getName() {
        return name;
    }
    public void setName(Name name) {
        this.name = name;
    }
    ......
    ......
}
public class Name {
    char initial;
    String first;
    String last;
    public String getFirst() {
        return first;
    }
    void setFirst(String first) {
        this.first = first;
    }
    public String getLast() {
        return last;
    }
    void setLast(String last) {
        this.last = last;
    }
    public char getInitial() {
        return initial;
    }
    void setInitial(char initial) {
        this.initial = initial;
    }
}
ここで NamePerson のコンポーネントとして永続化することが出来ます。Name は永続化プロパティに対して getter 、setter メソッドを定義しますが、インターフェースや識別子プロパティを宣言する必要はありません。
Hibernateマッピングは以下のようになります。
<class name="eg.Person" table="person">
    <id name="Key" column="pid" type="string">
        <generator class="uuid"/>
    </id>
    <property name="birthday" type="date"/>
    <component name="Name" class="eg.Name"> <!-- class attribute optional -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </component>
</class>
Person テーブルは pidbirthdayinitialfirstlast カラムを持ちます。
値型のように、コンポーネントは参照の共有には対応していません。言い換えると、二人の Person は同じ名前を持つことができますが、二つの Person オブジェクトは値が「同じ」だけで別々の name オブジェクトを含んでいるということです。コンポーネントの null 値のセマンティクスは アドホック です。包含オブジェクトを再読み込みする際、Hibernate はコンポーネントのすべてのカラムが null であるならコンポーネント全体が null であると考えます。これは大抵の場合問題ありません。
コンポーネントのプロパティはどんな Hibernate の型でも構いません(コレクション、 many-to-one 関連、他のコンポーネントなど)。ネストされたコンポーネントは滅多に使わないと考えるべきでは ありません 。Hibernate は きめの細かいオブジェクトモデルをサポートするように意図されています。
<component> 要素は、親エンティティへ戻る参照として、コンポーネントのクラスのプロパティをマッピングする <parent> サブ要素を許可します。
<class name="eg.Person" table="person">
    <id name="Key" column="pid" type="string">
        <generator class="uuid"/>
    </id>
    <property name="birthday" type="date"/>
    <component name="Name" class="eg.Name" unique="true">
        <parent name="namedPerson"/> <!-- reference back to the Person -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </component>
</class>

8.2. 依存オブジェクトのコレクション

Hibernate はコンポーネントのコレクションをサポートしています(例えば Name 型の配列)。<element> タグを <composite-element> タグに置き換えることでコンポーネントコレクションを宣言してください。
<set name="someNames" table="some_names" lazy="true">
    <key column="id"/>
    <composite-element class="eg.Name"> <!-- class attribute required -->
        <property name="initial"/>
        <property name="first"/>
        <property name="last"/>
    </composite-element>
</set>

重要

複合要素の Set を定義する場合、 equals()hashCode() を正しく実装することが重要です。
複合要素はコレクションではなく、コンポーネントを含むこともあります。複合要素自身がコンポーネントを含んでいる場合は <nested-composite-element> タグを使用してください。これは、コンポーネントのコレクション自身がコンポーネントを持つケースです。この段階までに、one-to-many 関連の方がより適切でないかと熟考してください。コンポジットエレメントをエンティティとして再度モデリングしてみてください。しかしこれは Java のモデルとしては同じでもリレーショナルモデルと永続動作はまだ若干異なることに注意してください。
<set> を使用する場合、複合要素のマッピングが null の代入可能なプロパティには対応していません。複合要素テーブルには別の主キーカラムがありません。Hibernate はオブジェクトの削除時、レコードを識別するために各カラムの値を使用する必要があるため、null 値を持つことが出来ません。複合要素に not-null の属性のみを使用するか、または <list><map><bag><idbag> を選択する必要があります。
複合要素の特別なケースとして、ネストされた <many-to-one> 属性を持つ複合要素があります。このマッピングは、複合要素クラスを多対多関連テーブルの余分なカラムへマッピングします。以下は、Order から、Item への多対多関連で、purchaseDatepricequantity が関連のプロパティとなっています。
<class name="eg.Order" .... >
    ....
    <set name="purchasedItems" table="purchase_items" lazy="true">
        <key column="order_id">
        <composite-element class="eg.Purchase">
            <property name="purchaseDate"/>
            <property name="price"/>
            <property name="quantity"/>
            <many-to-one name="item" class="eg.Item"/> <!-- class attribute is optional -->
        </composite-element>
    </set>
</class>
双方向関連のナビゲーションに反対側から purchase への参照を作ることは出来ません。コンポーネントは値型であり、共有参照ができません。一つの Purchase は一つの Order の set に存在できますが、同時にその Item による参照することは出来ません。
3項関連(あるいは4項など)も可能です。
<class name="eg.Order" .... >
    ....
    <set name="purchasedItems" table="purchase_items" lazy="true">
        <key column="order_id">
        <composite-element class="eg.OrderLine">
            <many-to-one name="purchaseDetails class="eg.Purchase"/>
            <many-to-one name="item" class="eg.Item"/>
        </composite-element>
    </set>
</class>
複合要素は他のエンティティへの関連として、同じ構文を用いるクエリ内で出現可能です。

8.3. Map のインデックスとしてのコンポーネント

<composite-map-key> 要素は Map のキーとしてコンポーネントクラスをマッピングします。コンポーネントクラス上で hashCode()equals() を正確にオーバーライドするようにしてください。

8.4. 複合識別子としてのコンポーネント

コンポーネントをエンティティクラスの識別子として使うことができます。コンポーネントクラスは一定の条件を満たす必要があります。
  • java.io.Serializable を実装しなければなりません。
  • データベース上の複合キーの等価性と矛盾のないように、equals()hashCode() を再実装しなければなりません。

注記

Hibernate3 において、2番目の条件は絶対的な条件ではありませんが、推奨はされています。
複合キーを生成するために IdentifierGenerator を使用することはできません。代わりにアプリケーションが独自の識別子を割り当てなくてはなりません。
通常の <id> 宣言の代わりに <composite-id> タグをネストされた <key-property> 属性と共に使います。例えば、OrderLine クラスは Order の(複合)主キーに依存した主キーを持っています。
<class name="OrderLine">
    
    <composite-id name="id" class="OrderLineId">
        <key-property name="lineId"/>
        <key-property name="orderId"/>
        <key-property name="customerId"/>
    </composite-id>
    
    <property name="name"/>
    
    <many-to-one name="order" class="Order"
            insert="false" update="false">
        <column name="orderId"/>
        <column name="customerId"/>
    </many-to-one>
    ....
    
</class>
このとき、OrderLine テーブルへ関連する外部キーもまた複合です。他のクラスのマッピングでこれを宣言しなければなりません。 OrderLine への関連は次のようにマッピングされます。
<many-to-one name="orderLine" class="OrderLine">
<!-- the "class" attribute is optional, as usual -->
    <column name="lineId"/>
    <column name="orderId"/>
    <column name="customerId"/>
</many-to-one>

注記

<column> タグはどこも column 属性の代わりになります。
OrderLine への many-to-many 関連も複合外部キーを使います。
<set name="undeliveredOrderLines">
    <key column name="warehouseId"/>
    <many-to-many class="OrderLine">
        <column name="lineId"/>
        <column name="orderId"/>
        <column name="customerId"/>
    </many-to-many>
</set>
Order にある OrderLine のコレクションは次のものを使用します:
<set name="orderLines" inverse="true">
    <key>
        <column name="orderId"/>
        <column name="customerId"/>
    </key>
    <one-to-many class="OrderLine"/>
</set>
<one-to-many> 属性はカラムを宣言しません。
OrderLine 自身がコレクションを持っている場合、同時に複合外部キーも持っています。
<class name="OrderLine">
    ....
    ....
    <list name="deliveryAttempts">
        <key>   <!-- a collection inherits the composite key type -->
            <column name="lineId"/>
            <column name="orderId"/>
            <column name="customerId"/>
        </key>
        <list-index column="attemptId" base="1"/>
        <composite-element class="DeliveryAttempt">
            ...
        </composite-element>
    </set>
</class>

8.5. 動的コンポーネント

Map 型のプロパティのマッピングも可能です:
<dynamic-component name="userAttributes">
    <property name="foo" column="FOO" type="string"/>
    <property name="bar" column="BAR" type="integer"/>
    <many-to-one name="baz" class="Baz" column="BAZ_ID"/>
</dynamic-component>
<dynamic-component> マッピングのセマンティクスは <component> と全く同一のものです。この種のマッピングの利点は、マッピングドキュメントの編集により、配置時に Bean の属性を決定できる点です。また、 DOM パーサを利用して、マッピングドキュメントのランタイム操作が可能です。さらに、 Configuration オブジェクト経由で Hibernate のコンフィグレーション時のメタモデルにアクセス、または変更が可能です。

第9章 継承マッピング 

9.1. 3つの戦略 

Hibernate は3つの基本的な継承のマッピング戦略をサポートします。
  • クラス階層ごとのテーブル (table-per-class-hierarchy)
  • サブクラスごとのテーブル(table-per-subclass)
  • 具象クラスごとのテーブル (table-per-concrete-class)
加えて4つ目に、 Hibernate はわずかに異なる性質を持ったポリモーフィズムをサポートします。
  • 暗黙的ポリモーフィズム
同一の継承階層の異なるブランチに対して異なるマッピング戦略を使うことができます。その場合には全体の階層にわたるポリモーフィズムを実現するために暗黙的ポリモーフィズムを使用します。しかし、Hibernate は同じルート <class> 要素で <subclass> マッピング、 <joined-subclass> マッピング、 <union-subclass> マッピングの同時使用をサポートしていません。<subclass> 要素と <join> 要素を組み合わせることで、同一 <class> 要素内での table-per-hierarchy 戦略と table-per-subclass 戦略の同時使用は可能です(次の例を見てください)。
subclassunion-subclassjoined-subclass マッピングを別のマッピングドキュメントに直接定義することが出来、 hibernate-mapping の直下に配置します。これは新しいマッピングファイルを追加するだけで、クラス階層を拡張できるということです。あらかじめマップしたスーパークラスを指定して、サブクラスマッピングに extends 属性を記述しなければなりません。この特徴により、以前はマッピングドキュメントの順番が重要でした。 Hibernate3 からは、 extends キーワードを使う場合、マッピングドキュメントの順番は問題になりません。1つのマッピングファイル内で順番付けを行うときは、依然として、サブクラスを定義する前にスーパークラスを定義する必要があります。
 <hibernate-mapping>
     <subclass name="DomesticCat" extends="Cat" discriminator-value="D">
          <property name="name" type="string"/>
     </subclass>
 </hibernate-mapping>

9.1.1. クラス階層ごとのテーブル(table-per-class-hierarchy)

例えば、インターフェース Payment と、それを実装した CreditCardPaymentCashPaymentChequePayment があるとします。階層ごとのテーブルマッピングは以下のように表示されます:
<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>
ちょうど一つのテーブルが必要です。このマッピング戦略には制限が1つあります。CCTYPE のような、サブクラスで宣言されたカラムは NOT NULL 制約を持つことができません。

9.1.2. サブクラスごとのテーブル (table-per-subclass)

table-per-subclass マッピングは以下のようになります:
<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <joined-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </joined-subclass>
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        ...
    </joined-subclass>
</class>
4つのテーブルが必要です。3つのサブクラステーブルはスーパークラステーブルとの関連を示す主キーを持っており、実際、関係モデル上は一対一関連です。

9.1.3. 弁別子 を用いた table-per-subclass

Hibernate の table-per-subclass 実装は、 discriminator カラムを必要としないことを覚えておいてください。 Hibernate 以外の O/R マッパーは、 table-per-subclass に異なる実装を用います。それは、スーパークラスのテーブルにタイプ discriminator カラムを必要とします。このアプローチは実装が困難になりますが、関係の視点から見ると、より正確なものです。table-per-subclass 戦略で discriminator カラムを使いたければ、<subclass><join> を以下のように組み合わせて使ってください。
<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <key column="PAYMENT_ID"/>
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        <join table="CASH_PAYMENT">
            <key column="PAYMENT_ID"/>
            ...
        </join>
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        <join table="CHEQUE_PAYMENT" fetch="select">
            <key column="PAYMENT_ID"/>
            ...
        </join>
    </subclass>
</class>
オプションの fetch="select" 宣言は、スーパークラスのクエリ実行時に外部結合を使って、サブクラスの ChequePayment データを取得しないように指定するためのものです。

9.1.4. table-per-subclass と table-per-class-hierarchy の混合

このアプローチを使用すると、table-per-hierarchy と table-per-subclass 戦略を組み合わせる事も可能です。
<class name="Payment" table="PAYMENT">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="PAYMENT_TYPE" type="string"/>
    <property name="amount" column="AMOUNT"/>
    ...
    <subclass name="CreditCardPayment" discriminator-value="CREDIT">
        <join table="CREDIT_PAYMENT">
            <property name="creditCardType" column="CCTYPE"/>
            ...
        </join>
    </subclass>
    <subclass name="CashPayment" discriminator-value="CASH">
        ...
    </subclass>
    <subclass name="ChequePayment" discriminator-value="CHEQUE">
        ...
    </subclass>
</class>
いずれのマッピング戦略であっても、ルートである Payment クラスへのポリモーフィックな関連は <many-to-one> を使ってマッピングします。
<many-to-one name="payment" column="PAYMENT_ID" class="Payment"/>

9.1.5. 具象クラスごとのテーブル(table-per-concrete-class)

table-per-concrete-class 戦略のマッピングに対するアプローチは2つあります。1つ目は <union-subclass> を利用する方法です。
<class name="Payment">
    <id name="id" type="long" column="PAYMENT_ID">
        <generator class="sequence"/>
    </id>
    <property name="amount" column="AMOUNT"/>
    ...
    <union-subclass name="CreditCardPayment" table="CREDIT_PAYMENT">
        <property name="creditCardType" column="CCTYPE"/>
        ...
    </union-subclass>
    <union-subclass name="CashPayment" table="CASH_PAYMENT">
        ...
    </union-subclass>
    <union-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        ...
    </union-subclass>
</class>
サブクラスごとに3つのテーブルが必要です。それぞれのテーブルは、継承プロパティを含んだ、クラスの全てのプロパティに対するカラムを定義します。
このアプローチにおける制限は、プロパティがスーパークラスにマッピングされていた場合、全てのサブクラスにおいてカラム名が同じでなければならないというものです。union subclass 継承では識別子生成戦略を使用できません。主キーを生成するためのシードは、全ての union subclass の階層内で共有する必要があるからです。
スーパークラスが抽象的であれば、abstract="true" とマッピングします。もちろん、スーパークラスが抽象的でないなら、スーパークラスのインスタンスを保持するために、テーブルの追加が必要となります (上の例でのデフォルトは PAYMENT )。

9.1.6. 暗黙的ポリモーフィズムを用いた table-per-concrete-class

もう一つのアプローチは暗黙的ポリモーフィズムの使用です:
<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
</class>

<class name="CashPayment" table="CASH_PAYMENT">
    <id name="id" type="long" column="CASH_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CASH_AMOUNT"/>
    ...
</class>

<class name="ChequePayment" table="CHEQUE_PAYMENT">
    <id name="id" type="long" column="CHEQUE_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <property name="amount" column="CHEQUE_AMOUNT"/>
    ...
</class>
Payment インターフェースが明示的に記載されていないこと、そしてPayment プロパティが各サブクラスにマッピングされていることに注意してください。重複を避けたい場合、XML エンティティの利用も検討してください。(例:DOCTYPE 宣言における [ <!ENTITY allproperties SYSTEM "allproperties.xml"> ] と、マッピングにおける &allproperties;
このアプローチの欠点は、Hibernate がポリモーフィックなクエリの実行時に SQL UNION を生成しない点です。
このマッピング戦略に対しては、 Payment へのポリモーフィックな関連は常に、 <any> を使ってマッピングされます。
<any name="payment" meta-type="string" id-type="long">
    <meta-value value="CREDIT" class="CreditCardPayment"/>
    <meta-value value="CASH" class="CashPayment"/>
    <meta-value value="CHEQUE" class="ChequePayment"/>
    <column name="PAYMENT_CLASS"/>
    <column name="PAYMENT_ID"/>
</any>

9.1.7. 他の継承マッピングと暗黙的ポリモーフィズムの組み合わせ

サブクラスが自身の<class> 要素にマッピングされており、(なおかつ Payment は単なるインターフェースであるため)、各サブクラスは簡単に他の継承階層の一部となりえます。しかも、Payment インターフェースに対するポリモーフィックなクエリを使用することもできます。
<class name="CreditCardPayment" table="CREDIT_PAYMENT">
    <id name="id" type="long" column="CREDIT_PAYMENT_ID">
        <generator class="native"/>
    </id>
    <discriminator column="CREDIT_CARD" type="string"/>
    <property name="amount" column="CREDIT_AMOUNT"/>
    ...
    <subclass name="MasterCardPayment" discriminator-value="MDC"/>
    <subclass name="VisaPayment" discriminator-value="VISA"/>
</class>

<class name="NonelectronicTransaction" table="NONELECTRONIC_TXN">
    <id name="id" type="long" column="TXN_ID">
        <generator class="native"/>
    </id>
    ...
    <joined-subclass name="CashPayment" table="CASH_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CASH_AMOUNT"/>
        ...
    </joined-subclass>
    <joined-subclass name="ChequePayment" table="CHEQUE_PAYMENT">
        <key column="PAYMENT_ID"/>
        <property name="amount" column="CHEQUE_AMOUNT"/>
        ...
    </joined-subclass>
</class>
もう一度述べますが、Payment は明示的に記載されません。Payment インターフェースに対してクエリを実行する場合、 例えば from Payment などから、 Hibernate は自動的に CreditCardPayment (と Payment の実装であるためCreditCardPayment のサブクラス)、および、CashPaymentChequePayment のインスタンスを返します。しかし、NonelectronicTransaction インスタンスは返しません。

9.2. 制限

table-per-concrete-class マッピング戦略への「暗黙的ポリモーフィズム」アプローチにはいくつかの制限があります。<union-subclass> マッピングに対しても若干弱めの制限があります。
次のリストで、Hibernate における table-per-concrete-class マッピングの制限や暗黙的ポリモーフィズムの制限を示します。
table per class-hierarchy , サブクラスごとのテーブル(table-per-subclass)
  • ポリモーフィックな多対一: <many-to-one>
  • ポリモーフィックな一対一: <one-to-one>
  • ポリモーフィックな一対多: <one-to-many>
  • ポリモーフィックな多対多 : <many-to-many>
  • ポリモーフィックなload() あるいは get(): s.get(Payment.class, id)
  • ポリモーフィックなクエリ: from Payment p
  • ポリモーフィックな結合: from Order o join o.payment p
外部結合によるフェッチに対応しています。
table per concrete-class (union-subclass)
  • ポリモーフィックな多対一: <many-to-one>
  • ポリモーフィックな一対一: <one-to-one>
  • ポリモーフィックな一対多: <one-to-many> ( inverse="true" のみ)
  • ポリモーフィックな多対多 : <many-to-many>
  • ポリモーフィックなload() あるいは get(): s.get(Payment.class, id)
  • ポリモーフィックなクエリ: from Payment p
  • ポリモーフィックな結合: from Order o join o.payment p
外部結合によるフェッチに対応しています。
table per concrete class (暗黙的ポリモーフィズム)
  • ポリモーフィックな多対一: <any>
  • ポリモーフィックな多対多 : <many-to-many>
  • ポリモーフィックなload() または get(): s.createCriteria(Payment.class).add( Restrictions.idEq(id) ).uniqueResult()
  • ポリモーフィックなクエリ: from Payment p
ポリモーフィックな一対一、ポリモーフィックな一対多、ポリモーフィックな結合、外部結合フェッチには対応していません。

第10章 オブジェクトを扱う

Hibernate は完全なオブジェクト/リレーショナルマッピングソリューションであり、データベース管理システムの詳細を開発者から見えなくするだけでなく、オブジェクトの 状態管理 も行います。これは、JDBC/SQL 永続層と同じような SQL statements の管理とは異なり、 Java アプリケーションの永続化に対する、自然なオブジェクト指向の考え方を提供します。
言いかえれば、 Hibernate を用いるアプリケーション開発者は、オブジェクトの 状態 については常に意識すべきであり、 SQL 文の実行については必ずしもそうではありません。この部分は、通常、 Hibernate が処理し、システムのパフォーマンスを調整するときにだけ、問題になってきます。

10.1. Hibernate におけるオブジェクトの状態

Hibernate は次のようなオブジェクトの状態を定義し、サポートしています:
  • 一時的(Transient) - new 演算子を使ってインスタンス化されただけで、Hibernate の Session に関連付けられていない場合、オブジェクトは一時的(Transient)なものとなります。それは、データベースに永続的な表現を持たず、識別子となる値は割り当てられていません。Transient インスタンスは、アプリケーションがその参照をどこにも保持しない場合に、ガベージコレクタによって破棄されます。オブジェクトを永続的 (persistent) な状態にするためには、 Hibernate の Session を使いましょう(Hibernate がこの遷移を実行する際に必要となるSQL 文を処理させることになります)。
  • 永続的 (Persistent) - 永続的なインスタンスは識別子値やデータベースに表現を持ちます。それは、保存やロードされている場合もあるかもしれませんが、定義上は、 Session のスコープの中に存在しています。Hibernate は、作業単位(Unit of Work)が完了したときに、永続状態のオブジェクトに加えられた変更を検出し、オブジェクトの状態とデータベースを同期します。オブジェクトを transient にするときは、開発者は、手作業で UPDATE 文や DELETE 文を実行しません。
  • 分離(Detached) - 分離(detached)インスタンスとは、永続化されているが、それと関連付いていた Session がクローズされているオブジェクトのことです。そのオブジェクトへの参照は、依然として有効です。そして、もちろん、detached インスタンスはこの状態に修正することさえできます。 detached インスタンスは、後にもう一度永続化したい(そして、すべての変更を永続化したい)ときに、新しい Session に再追加できます。この機能は、ユーザーが考える時間を必要とするような、長期間に及ぶ作業単位に対するプログラミングモデルを可能にします。これを アプリケーションのトランザクション(application transaction) と呼んでいます。すなわち、ユーザーから見た作業単位です。
これから、状態と状態遷移(そして、遷移のトリガとなる Hibernate のメソッド)について、詳細に述べます。

10.2. オブジェクトを永続状態にする

新しくインスタンス化された永続クラスのインスタンスは、 Hibernate では 一時的(transient) と見なされます。以下のように、セッションと関連づけることで、 transient インスタンスを 永続状態 (persistent) にできます。
DomesticCat fritz = new DomesticCat();
fritz.setColor(Color.GINGER);
fritz.setSex('M');
fritz.setName("Fritz");
Long generatedId = (Long) sess.save(fritz);
Cat クラスの識別子が自動生成されるのであれば、save() が呼ばれるときに、識別子が生成され、cat インスタンスに割り当てられます。Cat の識別子が assigned 識別子か複合キーを持つ場合、save() を呼び出す前に、識別子を cat インスタンスに割り当てなければなりません。save() の代わりに、EJB3 の初期ドラフトで定義された persist() を使うことも可能です。
  • persist() は、一時的なインスタンスを永続化します。しかし、識別子が即座に永続インスタンスに割り当てられる保証はなく、割り当てはフラッシュ時に起こることもあります。また、persist() は、トランザクション境界外で呼び出された場合、INSERT 文を実行しないようにします。これは拡張されたSession / 永続コンテキストにおける長期に亘る会話では有用です。
  • save() では、識別子を返すかの保証はありません。識別子の取得にINSERT を実行する必要がある場合(例「シーケンス」ではなく「アイデンティティ(ID)」ジェネレータ)、トランザクションの内外、どちらにいようとも、この INSERT は即座に起こります。拡張されたSession / 永続コンテキストを伴う長い会話については問題です。
代わりに、多重定義された save() を使って、識別子を割り当てることもできます。
DomesticCat pk = new DomesticCat();
pk.setColor(Color.TABBY);
pk.setSex('F');
pk.setName("PK");
pk.setKittens( new HashSet() );
pk.addKitten(fritz);
永続化するオブジェクトが関連オブジェクトを持っている場合 (例えば、前例の kittens コレクションのように)、外部キーカラムに、 NOT NULL 制約をつけない限りは、これらの一連のオブジェクトをどんな順番で永続化してもかまいません。外部キー制約を違反する恐れはありません。しかし、 NOT NULL 制約がある場合、間違った順番でオブジェクトを save() してしまうと、制約に違反するかもしれません。
通常、Hibernate の 遷移的な永続化 (transitive persistence) 機能を使って関連するオブジェクトを自動保存するため、このような詳細を気にする必要はありません。そして、NOT NULL 制約の違反すら起こりません。Hibernate がすべて処理します。遷移的な永続化は、この章の後半に書かれています。

10.3. オブジェクトのロード

永続化されたインスタンスの識別子があらかじめ分かっているなら、 Sessionload() メソッドを使って取得する手段があります。load() は、Class オブジェクトをとり、永続状態にあるそのクラスのインスタンスを新たに生成し、状態をロードします。
Cat fritz = (Cat) sess.load(Cat.class, generatedId);Id);Id);
// you need to wrap primitive identifiers
long id = 1234;
DomesticCat pk = (DomesticCat) sess.load( DomesticCat.class, new Long(id) );
あるいは、以下のように、既存のインスタンスに状態をロードすることもできます:
Cat cat = new DomesticCat();
// load pk's state into cat
sess.load( cat, new Long(pkId) );
Set kittens = cat.getKittens();
DB に該当する行が無い場合、load() は回復不可能な例外を投げることに注意しましょう。そのクラスがプロキシを使ってマッピングされている場合、 load() は初期化されていないプロキシを返し、プロキシのメソッドが呼ばれるまで実際にはデータベースにアクセスしません。実際にデータベースからロードせずに、オブジェクトに対する関連を作りたい場合、この振る舞いはとても役立ちます。batch-size がクラスマッピングに定義されている場合、複数のインスタンスを一括でロードすることが可能です。
該当する行が存在することを確信できない場合は、データベースにすぐにアクセスし該当する行が無いと null を返すget() メソッドを使うべきです。
Cat cat = (Cat) sess.get(Cat.class, id);
if (cat==null) {
    cat = new Cat();
}
return cat;
LockMode を使えば、SELECT ... FOR UPDATE という SQL を使ってオブジェクトをロードすることができます。詳細な情報は、API ドキュメントを参照してください。
Cat cat = (Cat) sess.get(Cat.class, id, LockMode.UPGRADE);
関連に対するカスケードスタイルとして lockall を指定しない限り、関連するインスタンスや包含するコレクションは FOR UPDATE で選択されません
refresh() メソッドを使うことで、どんなときでも、オブジェクトやそのコレクションをリロードすることができます。データベースのトリガがテーブルを更新した際に、そのテーブルに対応するオブジェクトのプロパティを同期する場合、このメソッドが役に立ちます。
sess.save(cat);
sess.flush(); //force the SQL INSERT
sess.refresh(cat); //re-read the state (after the trigger executes)
Hibernate がデータベースから、どのくらいの量をロードするのでしょうか?またどのくらいの数の SQL の SELECT 文が使われるのでしょうか?これは、フェッチの戦略 によります。これについては、「フェッチ戦略」で説明しています。

10.4. クエリ

探しているオブジェクトの識別子が分からない場合は、クエリが必要になります。Hibernate は使いやすくて強力なオブジェクト指向のクエリ言語 (HQL) をサポートしています。プログラムでクエリが作成できるように、Hibernate は洗練された Criteria と Example クエリ機能 (QBC と QBE) をサポートしています。また、リザルトセットをオブジェクトに変換する Hibernate のオプション機能を使うことで、データベースのネイティブ SQL でクエリを表現することもできます。

10.4.1. クエリの実行

HQL やネイティブな SQL クエリは、 org.hibernate.Query のインスタンスとして表現されます。このインタフェースは、パラメータバインディングや ResultSet のハンドリングやクエリの実行を行うメソッドを用意しています。通常、 Query は、以下に示すように、その時点の Session を使って取得します。
List cats = session.createQuery(
    "from Cat as cat where cat.birthdate < ?")
    .setDate(0, date)
    .list();

List mothers = session.createQuery(
    "select mother from Cat as cat join cat.mother as mother where cat.name = ?")
    .setString(0, name)
    .list();

List kittens = session.createQuery(
    "from Cat as cat where cat.mother = ?")
    .setEntity(0, pk)
    .list();

Cat mother = (Cat) session.createQuery(
    "select cat.mother from Cat as cat where cat = ?")
    .setEntity(0, izi)
    .uniqueResult();

Query mothersWithKittens = session.createQuery(
    "select mother from Cat as mother left join fetch mother.kittens");
Set uniqueMothers = new HashSet(mothersWithKittens.list());
クエリは、普通、list() を呼び出すことによって実行されます。クエリの結果は、メモリ上にあるコレクションにすべてロードされます。クエリによって取得されたエンティティのインスタンスは、永続状態です。クエリがたった1つのインスタンスを返すと分かっている場合、uniqueResult() メソッドが簡単な方法です。通常、即時フェッチを利用したクエリの場合、得られたコレクションには、ルートのオブジェクトが重複して含まれていますが、初期化されたコレクションでは、この重複をSet でフィルタリングすることができます。

10.4.1.1. 結果をイテレートする

時にiterate() メソッドを使ってクエリを実行することで、より良いパフォーマンスを得ることができます。これは、通常、クエリによって得られた実際のエンティティのインスタンスが、すでにセッションまたは二次キャッシュに存在することが期待できる場合だけです。それらが、まだキャッシュされていないなら、 iterate() は、 list() よりも遅く、簡単なクエリに対しても多くのデータベースアクセスを必要とします。そのアクセスとは、識別子だけを取得するための最初の select 1回 と、実際のインスタンスを初期化するために後から行う n回 の select のことです。
// fetch ids
Iterator iter = sess.createQuery("from eg.Qux q order by q.likeliness").iterate();
while ( iter.hasNext() ) {
    Qux qux = (Qux) iter.next();  // fetch the object
    // something we couldn't express in the query
    if ( qux.calculateComplicatedAlgorithm() ) {
        // delete the current instance
        iter.remove();
        // don't need to process the rest
        break;
    }
}

10.4.1.2. オブジェクトの組(tuple)を返すクエリ

Hibernate のクエリでは、オブジェクトのタプル(組)を返すことがあります。各タプルは配列として返されます:
Iterator kittensAndMothers = sess.createQuery(
            "select kitten, mother from Cat kitten join kitten.mother mother")
            .list()
            .iterator();

while ( kittensAndMothers.hasNext() ) {
    Object[] tuple = (Object[]) kittensAndMothers.next();
    Cat kitten = (Cat) tuple[0];
    Cat mother = (Cat) tuple[1];
    ....
}

10.4.1.3. スカラーの結果

クエリでは、select 節でクラスのプロパティを指定できます。SQL の集合関数を呼ぶこともできます。プロパティや集合関数は、永続状態のエンティティではなく、「スカラー値」であると見なされます。
Iterator results = sess.createQuery(
        "select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
        "group by cat.color")
        .list()
        .iterator();

while ( results.hasNext() ) {
    Object[] row = (Object[]) results.next();
    Color type = (Color) row[0];
    Date oldest = (Date) row[1];
    Integer count = (Integer) row[2];
    .....
}

10.4.1.4. パラメータのバインド

Query は、名前付きのパラメータや JDBC スタイルの ? パラメータに値をバインドするためのメソッドを持っています。JDBC とは違い、Hibernate はパラメータにゼロから番号を振っていきます。名前付きのパラメータとは、クエリ文字列のなかにある :name 形式の識別子です。名前付きパラメータの利点は次の通りです:です:
  • 名前付きパラメータは、クエリ文字列に登場する順番と無関係です
  • 同じクエリ内に複数回登場することができます。
  • 自分自身を説明します
//named parameter (preferred)
Query q = sess.createQuery("from DomesticCat cat where cat.name = :name");
q.setString("name", "Fritz");
Iterator cats = q.iterate();
//positional parameter
Query q = sess.createQuery("from DomesticCat cat where cat.name = ?");
q.setString(0, "Izi");
Iterator cats = q.iterate();
//named parameter list
List names = new ArrayList();
names.add("Izi");
names.add("Fritz");
Query q = sess.createQuery("from DomesticCat cat where cat.name in (:namesList)");
q.setParameterList("namesList", names);
List cats = q.list();

10.4.1.5. ページ分け

リザルトセットに制限(取得したい最大行数や取得したい最初の行)を加える必要があれば、Query インターフェースのメソッドを使うことができます:
Query q = sess.createQuery("from DomesticCat cat");
q.setFirstResult(20);
q.setMaxResults(10);
List cats = q.list();
制限付きのクエリを DBMS のネイティブな SQL に変換する方法を、 Hibernate は知っています。

10.4.1.6. スクロール可能なイテレーション

JDBC ドライバがスクロール可能な ResultSet をサポートしていれば、Query インターフェースを使って、ScrollableResults オブジェクトを取得できます。それを使うと、クエリの結果に対して柔軟にナビゲーションできます。
Query q = sess.createQuery("select cat.name, cat from DomesticCat cat " +
                            "order by cat.name");
ScrollableResults cats = q.scroll();
if ( cats.first() ) {

    // find the first name on each page of an alphabetical list of cats by name
    firstNamesOfPages = new ArrayList();
    do {
        String name = cats.getString(0);
        firstNamesOfPages.add(name);
    }
    while ( cats.scroll(PAGE_SIZE) );

    // Now get the first page of cats
    pageOfCats = new ArrayList();
    cats.beforeFirst();
    int i=0;
    while( ( PAGE_SIZE > i++ ) && cats.next() ) pageOfCats.add( cats.get(1) );

}
cats.close();
この機能にはオープン状態のデータベースコネクションが必要であることに注意してください。オフラインのページ分け機能が必要であれば、 setMaxResult() / setFirstResult() を使いましょう。

10.4.1.7. 名前付きクエリの外出し

マッピングドキュメントに名前付きのクエリを定義することができます。マークアップと解釈される文字がクエリに含まれるなら、CDATA セクションを使うことを忘れないようにしましょう。
<query name="ByNameAndMaximumWeight"><![CDATA[
    from eg.DomesticCat as cat
        where cat.name = ?
        and cat.weight > ?
] ]></query>
パラメータのバインディングと実行は、以下のようなプログラムで行われます:
Query q = sess.getNamedQuery("ByNameAndMaximumWeight");
q.setString(0, name);
q.setInteger(1, minWeight);
List cats = q.list();
実際のプログラムコードは、使われるクエリ言語に依存していません。メタデータには、ネイティブ SQL クエリを定義することもできますし、既存のクエリをマッピングファイルに移すことで、 Hibernate に移行することもできます。
<hibernate-mapping> 要素の中のクエリ宣言は、クエリに対するグローバルに一意な名前が必要なことにも注意してください。それに対して、 <class> 要素の中のクエリ宣言は、クラスの完全修飾名が前に付けられるので、自動的に一意になります。例: eg.Cat.ByNameAndMaximumWeight

10.4.2. フィルタリングコレクション

コレクション フィルタ は、永続化されているコレクションや配列に適用される特殊なタイプのクエリです。そのクエリ文字列では、コレクションのその時点での要素を意味する this を参照可能です。
Collection blackKittens = session.createFilter(
    pk.getKittens(), 
    "where this.color = ?")
    .setParameter( Color.BLACK, Hibernate.custom(ColorUserType.class) )
    .list()
返されるコレクションは Bag とみなされます。そして、それはもとのコレクションのコピーになります。元のコレクションは修正されません。これは、「filter」という名前の意味とは反対ですが、期待される動きとは一致しています。
必要なら、持つことも可能ですが、フィルタには from 節が不要である点に注目してください。フィルタは、コレクションの要素自体を返して構いません。
Collection blackKittenMates = session.createFilter(
    pk.getKittens(), 
    "select this.mate where this.color = eg.Color.BLACK.intValue")
    .list();
クエリを含まないフィルタも役に立ちます。例えば、大きなコレクションの部分集合をロードするために使えます。
Collection tenKittens = session.createFilter(
    mother.getKittens(), "")
    .setFirstResult(0).setMaxResults(10)
    .list();

10.4.3. クライテリアのクエリ

HQL は非常に強力ですが、クエリ文字列を作るよりも、オブジェクト指向の API を使って動的にクエリを作る方を好む開発者もいます。こういった場合のために、 Hibernate は直感的な Criteria クエリ API を提供しています。
Criteria crit = session.createCriteria(Cat.class);
crit.add( Restrictions.eq( "color", eg.Color.BLACK ) );
crit.setMaxResults(10);
List cats = crit.list();
CriteriaExample API の詳細は、 15章Criteria クエリに述べられています。

10.4.4. ネイティブ SQL のクエリ

createSQLQuery() を使って、 SQL でクエリを表現することもできます。そして、Hibernate に、リザルトセットからオブジェクトへのマッピングを管理します。session.connection() を呼べばどんなときでも、直接、 JDBC Connection を使用できます。Hibernate API を使うのであれば、下記のように SQL の別名を括弧でくくらなければなりません。
List cats = session.createSQLQuery("SELECT {cat.*} FROM CAT {cat} WHERE ROWNUM<10")
    .addEntity("cat", Cat.class)
.list();
List cats = session.createSQLQuery(
    "SELECT {cat}.ID AS {cat.id}, {cat}.SEX AS {cat.sex}, " +
           "{cat}.MATE AS {cat.mate}, {cat}.SUBCLASS AS {cat.class}, ... " +
    "FROM CAT {cat} WHERE ROWNUM<10")
    .addEntity("cat", Cat.class)
.list();
SQL クエリは、Hibernate クエリと同じように、名前付きのパラメータと位置パラメータを持つことができます。 Hibernate におけるネイティブな SQL クエリの詳細については、16章ネイティブ SQLを参照してください。

10.5. 永続オブジェクトの修正

処理中の永続インスタンス(例:Session によって、ロード、保存、作成、クエリされたオブジェクト)は、アプリケーションが操作します。その際に変更された永続状態は、Sessionフラッシュ されるときに、永続化されます。これは、この章で後述しています。変更を永続化するために、特殊なメソッド(update() のようなもの。これは、別の目的で使用します)を呼ぶ必要はありません。オブジェクトの状態を更新する一番簡単な方法は、オブジェクトを load() し、Session をオープンにしている間に、直接操作することです。
DomesticCat cat = (DomesticCat) sess.load( Cat.class, new Long(69) );
cat.setName("PK");
sess.flush();  // changes to cat are automatically detected and persisted
オブジェクトをロードするには SQL の SELECTが、更新された状態を永続化するには SQL の UPDATE が同じセッションで必要となるので、このプログラミングモデルは効率が悪くなります。Hibernate では分離インスタンスを利用することで別の方法を用意しています。

重要

Hibernate は、UPDATE 文や DELETE 文を直接実行する API を用意していません。Hibernate は、状態管理 サービスであり、それを使うのに 命令文 のことを開発者が考える必要はありません。JDBC は SQL 文を実行する完璧な API であり、session.connection() を呼ぶことでいつでも、 JDBC Connection を開発者は取得できます。さらに、大量のデータ操作の考え方は、オンライントランザクション処理向きアプリケーションのオブジェクト/リレーショナルマッピングと衝突します。しかし、Hibernate の今後のバージョンでは、大量データを処理する特別な機能を提供することができます。バッチ操作に利用できるいくつかの工夫については、13章バッチ処理 を参照してください。

10.6. 分離オブジェクトの修正

多くのアプリケーションでは、あるトランザクションでオブジェクトを復元し、操作するためにオブジェクトを UI 層に送り、その後に、新しいトランザクションで変更を保存する必要があります。並行性の高い環境で、このタイプのアプローチを使うアプリケーションでは通常、「期間の長い」作業単位の隔離性を保証するために、バージョンデータが使われます。
Hibernate は、Session.update()Session.merge() メソッドを使って、detached インスタンスを再追加することで、このモデルに対応します。
// in the first session
Cat cat = (Cat) firstSession.load(Cat.class, catId);
Cat potentialMate = new Cat();
firstSession.save(potentialMate);

// in a higher layer of the application
cat.setMate(potentialMate);

// later, in a new session
secondSession.update(cat);  // update cat
secondSession.update(mate); // update mate
識別子 catId を持つ Cat が、既に secondSession でロードされていた場合は、再追加しようとしたときに、例外が投げられます。
同じ識別子を持つ永続インスタンスをセッションが既に保持していないことを確信できる場合は update() を使います。そして、セッションの状態を考えずに、いつでも変更をマージしたい場合は、merge() を使います。すなわち、detached インスタンスの再追加操作が、最初に確実に実行されるようにするには、通常は update() が新しいセッションのなかで最初に呼ばれるメソッドになります。
その状態を更新したい場合に 限り、このdetached インスタンスから到達可能な、detached インスタンスをアプリケーションは個別に update() すべきです。遷移的な永続化 を使えば、もちろん自動化できます。「連鎖的な永続化」を参照してください。
lock() メソッドでもまた、新しいセッションにオブジェクトを再関連付けできます。しかし、detached インスタンスは無修正でなければなりません。
//just reassociate:
sess.lock(fritz, LockMode.NONE);
//do a version check, then reassociate:
sess.lock(izi, LockMode.READ);
//do a version check, using SELECT ... FOR UPDATE, then reassociate:
sess.lock(pk, LockMode.UPGRADE);
lock() は、さまざまな LockMode とともに使うことができる点に注意してください。詳細は、 API ドキュメントとトランザクション処理の章を参照してください。再追加のときにだけ、 lock() が使われるわけではありません。
期間の長い作業単位の、その他のモデルは、「楽観的同時実行制御」 で述べています。

10.7. 自動的な状態検出

Hibernate のユーザーは次の2つのケースのどちらにも使える汎用的なメソッドを要求していました。それは、新しい識別子を生成して transient インスタンスを保存することと、その時点の識別子と関連づいている detached インスタンスを更新/再追加することのできるメソッドです。 saveOrUpdate() はこのような機能を実現したメソッドです。
// in the first session
Cat cat = (Cat) firstSession.load(Cat.class, catID);

// in a higher tier of the application
Cat mate = new Cat();
cat.setMate(mate);

// later, in a new session
secondSession.saveOrUpdate(cat);   // update existing state (cat has a non-null id)
secondSession.saveOrUpdate(mate);  // save the new instance (mate has a null id)
saveOrUpdate() の使用方法と意味は、新しいユーザーにとって混乱を招くかもしれません。まず第一に、あるセッションで使用したインスタンスを別の新しいセッションで使おうとしない限り、 update()saveOrUpdate()merge() を使う必要はありません。アプリケーション全体を通じて、これらのメソッドを全く使わないこともあります。
通常、 update()saveOrUpdate() は次のシナリオで使われます:
  • アプリケーションが最初のセッションでオブジェクトをロードします。
  • オブジェクトが UI 層に送られます。
  • オブジェクトに対して変更が加えられます。
  • オブジェクトがビジネスロジック層に送られます。
  • アプリケーションは、2番目のセッションで update() を呼ぶことで、これらの変更を永続化します。
saveOrUpdate() は以下のことを行います:
  • オブジェクトがこのセッションで、すでに永続化されていれば、何もしません。
  • そのセッションに関連づいている別のオブジェクトが同じ識別子を持っているなら、例外を投げます。
  • オブジェクトの識別子が値を持たないならば、 save() します。
  • オブジェクトの識別子が値を持ち、その値が新たにインスタンス化されたオブジェクトのための値である場合、そのオブジェクトを save() します。
  • オブジェクトが <version><timestamp> でバージョンづけされていて、バージョンのプロパティ値が新しくインスタンス化されたオブジェクトに割り当てた値と同じ場合、そのオブジェクトを save() します。
  • そうでない場合は、そのオブジェクトを update() します。
そして、 merge() は以下のように非常に異なります:
  • 同じ識別子を持つ永続化インスタンスがその時点でセッションと関連付いているならば、引数で受け取ったオブジェクトの状態を永続化インスタンスにコピーします。
  • 永続化インスタンスがその時点でセッションに関連付いていないなら、データベースからそれをロードするか、あるいは、新しい永続化インスタンスを作成します。
  • 永続化インスタンスが返されます。
  • 引数として与えたインスタンスはセッションと関連を持ちません。それは、分離状態のままです。

10.8. 永続オブジェクトの削除

Session.delete() はオブジェクトの状態をデータベースから削除します。しかし、削除したオブジェクトをアプリケーションが保持し続けることも可能です。delete() は永続インスタンスを transient にすると考えるのが一番です。
sess.delete(cat);
外部キー制約に違反するリスクもなく、好きな順番でオブジェクトを削除することができます。ただし、間違った順番でオブジェクトを削除すると、外部キーカラムの NOT NULL 制約に違反する可能性があります。例えば、親オブジェクトを削除したが子オブジェクトを削除し忘れた場合です。

10.9. 異なる二つのデータストア間でのオブジェクトのレプリケーション

永続インスタンスのグラフを別のデータストアに永続化する場合に、識別子の値を再生成せずにすむと便利な場合があります。
//retrieve a cat from one database
Session session1 = factory1.openSession();
Transaction tx1 = session1.beginTransaction();
Cat cat = (Cat) session1.get(Cat.class, catId);
tx1.commit();
session1.close();

//reconcile with a second database
Session session2 = factory2.openSession();
Transaction tx2 = session2.beginTransaction();
session2.replicate(cat, ReplicationMode.LATEST_VERSION);
tx2.commit();
session2.close();
データベースに既存の行がある場合、replicate() が衝突をどのように扱うかを ReplicationMode で指定します。
  • ReplicationMode.IGNORE:同じ識別子を持つ行がデータベースに存在するなら、そのオブジェクトを無視します。
  • ReplicationMode.OVERWRITE:同じ識別子を持つ既存の行をすべて上書きします。
  • ReplicationMode.EXCEPTION:同じ識別子を持つ行がデータベースに存在する場合、例外を投げます。
  • ReplicationMode.LATEST_VERSION:行に保存されているバージョン番号が、引数のオブジェクトのバージョン番号より古い場合、その行を上書きします。
次のようなケースで、この機能を使用します。異なるデータベースインスタンスに入れられたデータの同期、製品更新時におけるシステム設定情報の更新、非 ACID トランザクションのなかで加えられた変更のロールバックなどです。

10.10. セッションのフラッシュ

JDBC コネクションの状態とメモリ上のオブジェクトの状態を同期させるために必要な SQL 文を Session が実行することがときどきあります。flush と言われるこの処理は、デフォルトでは次のときに起こります。
  • クエリを実行する前
  • org.hibernate.Transaction.commit() を実行したとき
  • Session.flush() を実行したとき
SQL 文は以下の順番で発行されます:
  1. Session.save() を使って該当のオブジェクトを保存したときと同じ順番ですべてのエンティティを挿入。
  2. すべてのエンティティの更新
  3. すべてのコレクションの削除
  4. すべてのコレクションの要素に対する削除、更新、挿入
  5. すべてのコレクションの挿入
  6. Session.delete() を使って該当のオブジェクトを削除したときと同じ順番ですべてのエンティティを削除。
例外として、native ID 生成を使ったオブジェクトは、それらが保存されたときに挿入されます。
明示的に flush() するときを除いて、いつ Session が JDBC をコールするかについて絶対的な保証はありません。ただし、それらが実行される 順番 だけは保証されます。しかし Hibernate は、Query.list(..) が古いデータや間違ったデータを返さないことを保証しています。
フラッシュが頻繁に起こらないようにデフォルトの振る舞いを変えることができます。FlushMode クラスは3つの異なるモードを定義します。それは、Hibernate の Transaction API が使われるコミット時にだけフラッシュするモード、説明のあった処理順に基づいて自動でフラッシュするモード、 flush() が明示的に呼ばれない限りフラッシュしないモードの3つです。最後のモードは、作業単位が長期間に及ぶ場合に役に立ちます ( 「拡張セッションと自動バージョニング」 を参照してください)。
sess = sf.openSession();
Transaction tx = sess.beginTransaction();
sess.setFlushMode(FlushMode.COMMIT); // allow queries to return stale state

Cat izi = (Cat) sess.load(Cat.class, id);
izi.setName(iznizi);

// might return stale data
sess.createQuery("from Cat as cat left outer join cat.kittens kitten");

// change to izi is not flushed!
...
tx.commit(); // flush occurs
sess.close();
フラッシュ時に例外が発生するかもしれません(例えば、DML 操作が制約を違反するような場合です)。例外処理を理解するためには、Hibernate のトランザクションの動作を理解する必要があるため、11章トランザクションと並行性で説明します。

10.11. 連鎖的な永続化

個々のオブジェクトを保存、または削除、再追加することはかなり面倒です。特に、関連するオブジェクトを扱うような場合には際立ちます。よくあるのは、親子関係を扱うケースです。以下の例を考えてみましょう:
親子関係の子が値型なら(例えば、住所や文字列のコレクション)、それらのライフサイクルは親に依存しており、便利な状態変化の「カスケード」には追加の作業は必要はありません。親が保存されたとき、値型の子オブジェクトも同じように保存されますし、親が削除されたときは、子も削除されます。その他の操作も同じです。コレクションから1つの子を削除するような操作でもうまくいきます。Hibernate は値型のオブジェクトは共有参照ができないので、この削除操作を検出すると、データベースからその子を削除します。
ここで、親と子が値型でなくエンティティであるとして同じシナリオを考えてみましょう(例えば、カテゴリーと品目の関係や親と子のcatの関係です)。エンティティは、それ自身がライフサイクルを持ち、共有参照に対応しています。そのため、コレクションからエンティティを削除しても、エンティティ自身を削除できるわけではありません。また、エンティティは、デフォルトでは、関連する他のエンティティへ状態をカスケードすることはありません。Hibernate は 到達可能性による永続化 をデフォルトでは実装していません。
Hibernate の Session の基本操作( persist(), merge(), saveOrUpdate(), delete(), lock(), refresh(), evict(), replicate() が含まれます)に対して、それぞれに対応するカスケードスタイルがあります。それぞれのカスケードスタイルには、 create, merge, save-update, delete, lock, refresh, evict, replicate という名前がついています。関連に沿ってカスケードさせたい操作があるなら、マッピングファイルにそう指定しなければなりません。例えば、以下のようにします:
<one-to-one name="person" cascade="persist"/>
カスケードスタイルは、組み合わせることができます:
<one-to-one name="person" cascade="persist,delete,lock"/>
すべての 操作を関連に沿ってカスケードするよう指定するときは、cascade="all" を使います。デフォルトの cascade="none" は、どの操作もカスケードしないことを意味します。
特殊なカスケードスタイル delete-orphan は、一対多関連にだけ適用できます。これは、関連から削除された子のオブジェクトに対して、 delete() 操作が適用されることを意味します。
推奨事項:
  • 通常、<many-to-one><many-to-many> 関連に対しては、カスケードを有効にする意味はありません。 <one-to-one><one-to-many> 関連に対しては、カスケードが役に立つことがあります。
  • 子オブジェクトの寿命が親オブジェクトの寿命に制限を受けるならば、 cascade="all,delete-orphan" を指定し、子オブジェクトを ライフサイクルオブジェクト にします。
  • それ以外の場合は、カスケードはほとんど必要ないでしょう。しかし、同じトランザクションのなかで親と子が一緒に動作することが多いと思い、いくらかのコードを書く手間を省きたいのであれば、 cascade="persist,merge,save-update" を使うことを考えましょう。
cascade="all" でマッピングした関連(単値関連やコレクション)は、 親子 スタイルの関連とマークされます。それは、親の保存/更新/削除が、子の保存/更新/削除を引き起こす関係のことです。
さらに、永続化された親が子を単に参照している場合、その子を保存/更新することになります。しかし、このメタファーは不完全です。親から参照されなくなった子は、cascade="delete-orphan" でマッピングされた <one-to-many> 関連を除き、自動的に削除されません。親子関係のカスケード操作の正確な意味は以下のようになります:
  • 親が persist() に渡されたならば、すべての子は persist() に渡されます。
  • merge() に渡されたならば、すべての子は merge() に渡されます。
  • 親が save()update()saveOrUpdate() に渡されたならば、すべての子は saveOrUpdate() に渡されます。
  • transient または detached の子が、永続化された親に参照されたならば、 saveOrUpdate() に渡されます。
  • 親が削除されたならば、すべての子は、 delete() に渡されます。
  • 子が永続化された親から参照されなくなったときは、 特に何も起こりません 。よって、アプリケーションが必要であれば、明示的に削除する必要があります。ただし、 cascade="delete-orphan" の場合を除きます。この場合、「親のない」子は削除されます。
最後に、操作のカスケードがオブジェクトグラフに適用されるのは、コールした時 あるいは、フラッシュした時 であることに注意してください。有効な場合、この操作が実行されるときに、全操作は到達可能な関連エンティティへカスケード化されます。しかし、 save-upatedelete-orphan は、 Session のフラッシュ時、到達可能な関連エンティティすべてに対しては推移的となります。

10.12. メタデータの使用

Hibernate は、すべてのエンティティと値型のリッチなメタレベルモデルを必要とします。このモデルはアプリケーション自体で役に立つこともあります。例えば、アプリケーションは、Hibernate のメタデータを使って、「スマートな」ディープコピーアルゴリズムを実装できるかもしません。そのアルゴリズムとは、どオブジェクトがコピーされるべきか(例:可変の値型)やどのオブジェクトはコピーすべきでないか(例:不変な値型や可能なら関連するエンティティ)を判断できるものです。
Hibernate は ClassMetadataCollectionMetadata インタフェースと Type 階層を通してメタデータを公開します。メタデータインターフェースのインスタンスは、 SessionFactory から得ることができます。
Cat fritz = ......;
ClassMetadata catMeta = sessionfactory.getClassMetadata(Cat.class);

Object[] propertyValues = catMeta.getPropertyValues(fritz, EntityMode.POJO);
String[] propertyNames = catMeta.getPropertyNames();
Type[] propertyTypes = catMeta.getPropertyTypes();

// get a Map of all properties which are not collections or associations
Map namedValues = new HashMap();
for ( int i=0; i<propertyNames.length; i++ ) {
    if ( !propertyTypes[i].isEntityType() && !propertyTypes[i].isCollectionType() ) {
        namedValues.put( propertyNames[i], propertyValues[i] );
    }
}

第11章 トランザクションと並行性

Hibernate と同時実行制御について最も重要な点は、容易に理解できることです。Hibernate は新たなロックの振る舞いを追加しておらず、直接 JDBC コネクションと JTA リソースを使用します。JDBC 、ANSI 、およびデータベース管理システム(DBMS)のトランザクション分離の仕様について時間を費してみることを推奨します。
Hibernate はメモリ内のオブジェクトをロックしません。アプリケーションは、データベーストランザクションの分離レベルで定義した振る舞いを期待できます。トランザクションスコープのキャッシュでもある Session のお陰で、識別子やクエリにより検索したエンティティは再読み込み可能な読み込み(Repeatable-read)で、スカラー値を返すようなレポートクエリとは違います。
自動的な楽観的同時実行制御のバージョニングに加えて、Hibernate は SELECT FOR UPDATE 文を使用して、行を悲観的ロックするための(マイナーな) API も提供します。楽観的同時実行制御とこの API については、この章で後述します。
Hibernate が行う同時実行制御について、データベーストランザクションや長い会話(conversation、ロングトランザクション)や ConfigurationSessionFactory、および Session という粒度から議論を始めていきます。

11.1. session スコープと transaction スコープ

SessionFactory は生成することが高価で、スレッドセーフなオブジェクトであり、アプリケーションのすべてのスレッドで共有されるよう設計されています。通常、アプリケーションの起動時に、Configuration インスタンスから1度だけ生成します。
Session は高価ではなく、スレッドセーフなオブジェクトでもありません。よって、1つの要求や会話、作業単位(unit of work)に対して1度だけ使い、その後で捨てるべきです。Session は必要になるまで、JDBC Connection(もしくは DataSource)を獲得しません。ゆえに、実際に使用するときまでリソースを消費しません。
この状況を完了させるために、データベーストランザクションをできるだけ短くしなければなりません。長いデータベーストランザクションは、アプリケーションが高度な並列実効性への拡張を阻害します。ユーザーが考えている間は、作業単位が完了するまでデータベーストランザクションを開いたままにするのは推奨できません。
作業単位というスコープとは何でしょうか?1つの Hibernate Session は、いくつかのデータベーストランザクションにわたることができるでしょうか?また、これはスコープと一対一の関係でしょうか?いつ Session を開き、閉じるべきでしょうか?そして、データベーストランザクション境界をどのように分けるのでしょうか?以下の項でこのような疑問に対応しています。

11.1.1. 作業単位(Unit of work)

まず、作業単位を定義しましょう。Martin Fowlerは、作業単位をビジネストランザクションから影響をうけるオブジェクトのリストを[保持し]、変更により発生した記述や並行性の問題解決を調整する[PoEAA]設計パターンと説明しています。言いかえると、データベースに対して実行したい一連の操作で、基本的にこれはトランザクションを指します(作業単位を達成するには複数の物理データベーストランザクションに亘ることがしばしばありますが)( 「長い会話」 を参照してください)。このようにトランザクションについて、より抽象的な概念について説明しています。「ビジネストランザクション」という単語も作業単位の代わりに利用される場合もあります。
session-per-operation アンチパターンを使ってはいけません。すなわち、1つのスレッドの中で、単純なデータベース呼び出しの度に Session を開いて、閉じてはいけません。もちろん、データベーストランザクションについても同様です。アプリケーション中のデータベース呼び出しは、計画されたシーケンス(planned sequence)を使い、アトミックな作業単位に分類されます。また、1つの SQL 文ごとにコミットする自動コミットが、使われないという意味でもあります。自動コミットは、SQL コンソールでアドホックな作業をする際に使うものです。Hibernate は直ちに自動コミットモードを無効にするか、アプリケーションサーバーが無効化するのを待ちます。データベーストランザクションはオプションではありません。データベースとのすべての通信は、データの読み込み、書き込みのいずれでも、トランザクションの中で行わなければなりません。そして、データ読み込みに対して、自動コミットは避けるべきです。なぜなら、多数の小さなトランザクションは、明確に定義された1つの作業単位と比べて、パフォーマンスがよくなることはありません。後者は保守性や拡張性もよりすぐれています。
マルチユーザーのクライアント/サーバーアプリケーションの中で、最もよく使われるパターンは、 session-per-request です。このモデルの中では、クライアントから、Hibernate 永続化層が動作するサーバーへリクエストが送られ、新しい Hibernate Session が開かれます。そして、この作業単位の中ですべてのデータベース処理が実行されます。作業完了時、そして、クライアントへのレスポンスが準備できた時点で、session をフラッシュし、閉じます。クライアントの要求を処理するために、1つのデータベーストランザクションを使用してください。Session を開き、閉じる際に、データベーストランザクションを開始し、コミットします。二つの関係は一対一です。このモデルは多くのアプリケーションに完全に適合します。
しかし、実装自体が困難なのです。Hibernate では予め組み込まれた「現在のセッション」の管理ができるため、このパターンを簡素化します。サーバーリクエストを処理しなければならない場合、トランザクションを開始し、レスポンスをクライアントに送信する前にトランザクションを終了させます。一般的な解決策は ServletFilter やサービスメソッドをポイントカットした AOP インターセプター、proxy/interception コンテナです。EJB コンテナは、EJBセッションbeanにあるトランザクション境界など、クロスカットのアスペクトを実装する標準的な方法(CMTで宣言)となっています。プログラムによるトランザクション境界を使う場合、使い易さやコード移植性の面で、この章で後述する Hibernate Transaction API を利用してください。
アプリケーションのコードは、sessionFactory.getCurrentSession() を呼び出すことで「現在のセッション」にアクセスできます。現在のデータベーストランザクションを対象とするセッション を常に取得します。これは、リソースローカルな環境、もしくは JTA 環境対して、構成しなければなりません。「コンテキストのセッション」 を参照してください。
「ビューをレンダリングする」まで セッション とデータベーストランザクションのスコープを拡張することができます。これは、要求処理後に別のレンダリングフェーズを使用するサーブレットアプリケーションにおいて特に役立ちます。独自のインターセプタを実装することで、ビューをレンダリングするまでデータベーストランザクションを拡張できます。しかし、コンテナ管理トランザクションの EJB に頼る場合は、簡単にはできません。なぜなら、ビューのレンダリングを開始する前に、 EJB のメソッドがリターンした際に、トランザクションが完了するためです。この Open Session in View パターンに関連するヒントと例については、 Hibernate の Web サイトやフォーラムを参照してください。

11.1.2. 長い会話

session-per-request パターンは、作業単位の設計手段だけではありません。多くのビジネスプロセスは、ユーザーとの一連の相互作用全体を要求します。その相互作用には、データベースアクセスが含まれます。Web とエンタープライズアプリケーションでは、データベーストランザクションがユーザーとの相互作用にまで亘ることは許されません。次の例を考えてみてください:
  • ダイアログの最初の画面が開き、ユーザーに見せるデータを、特定の Session とデータベーストランザクションの中にロードします。ユーザーはオブジェクトを自由に修正できます。
  • 5分後にユーザーは 「Save」をクリックし、修正が永続化されるのを待ちます。また、この情報を編集したのは自分1人だけで、修正のコンフリクトは発生しないと期待します。
この作業単位を(ユーザーの視点で)長期の 会話、もしくは、アプリケーショントランザクション と呼びます。アプリケーションにこれを実装する方法はたくさんあります。
最初の単純な実装では、ユーザーが考えている間、Session とデータベーストランザクションを開いたままにしておく可能性があります。同時修正を防ぎ、分離と原子性が保証されるように、データベース内のロックは保持したままにします。しかし、ロックの競合が発生すると、アプリケーションが同時ユーザー数に応じてスケールアップできなくなるため、これはアンチパターンです。
会話を実装するためには、いくつかのデータベーストランザクションを使用するべきです。この場合、ビジネスプロセスの分離を維持することは、アプリケーション層の責務の1つになります。1つの会話は、通常いくつかのデータベーストランザクションにわたります。複数のデータベーストランザクションの1つ(最後の1つ)のみが更新データを保存し、他はデータを読むだけであれば、それはアトミックです(例えば、いくつかの要求/応答を繰り返すウィザード形式のダイアログ)。特にHibernate の機能の一部を使うのであれば、聞くよりも実際の実装は簡単です。
  • 自動バージョニング - Hibernate は自動的に楽観的同時実行制御ができます。ユーザーが考えている間に同時修正がおきた場合、自動的に検出できます。通常、会話の終了時にこれをチェックするだけです。
  • 分離(Detached)オブジェクト - すでに議論した session-per-request パターンを使うと決定した場合、ロードされたすべてのインスタンスは、ユーザーが考えている間は、セッションから分離された状態になります。オブジェクトをセッションに再追加し、修正を永続化できます。これを session-per-request-with-detached-objects パターンと呼びます。自動バージョニングを使うことで、同時修正を分離します。
  • 拡張(もしくは、長い)セッション - Hibernate の Session は、データベーストランザクションをコミットした後、基盤となっている JDBC 接続を切断でき、クライアントからの新しい要求が発生した際に、再接続できます。このパターンは、 session-per-conversation という名で知られており、接続の再設定も必要なくなります。自動バージョニングを使うことで、同時修正を分離でき、Session を自動的にフラッシュさせず、明示的にフラッシュします。
session-per-request-with-detached-objectssession-per-conversation の2つは、利点と欠点を持っています。これについては、この章で、楽観的同時実行制御の文脈の中で後述します。

11.1.3. オブジェクト識別子を考える

アプリケーションは、2つの異なる Session から同じ永続状態に同時にアクセスできます。しかし、2つの Session インスタンスが永続性クラスの1つのインスタンスを共有することはできません。ゆえに、アイデンティティには2つの異なる概念があるということになります:
データベースアイデンティティ
foo.getId().equals( bar.getId() )
JVM アイデンティティ
foo==bar
特定のSession に追加されたオブジェクトにとって (すなわち、1つの Session のスコープの中では)、2つの概念は同じです。データベース同一性と JVM 同一性が一致することを、Hibernate が保証します。しかし、アプリケーションが2つの異なるセッションから「同じ」(永続性アイデンティティの)ビジネスオブジェクトに同時にアクセスする限り、2つのインスタンスは実際に( JVM アイデンティティが)「異なり」ます。楽観的アプローチによって、(自動バージョニングの) フラッシュ/コミット時にコンフリクトが解決されます。
このアプローチでは、Hibernate とデータベースに同時実行についての心配が残ります。一方で、最高のスケーラビリティが提供されます。なぜなら、1スレッドの作業単位の中で一意性が保証されれば、高価なロックや別の同期化の別手段が不要になるためです。 Session ごとに1つのスレッドを保つ限り、アプリケーションはビジネスオブジェクトを synchronize する必要はありません。Session 内では、アプリケーションはオブジェクトを比較するために、== を安全に使用できます。
しかし、Session の外で == を使うアプリケーションは、予期しない結果に遭遇します。これは予期しない場所で起こりえます。例えば、2つの分離インスタンスを同じ Set に入力したときなどです。両方とも同じデータベースアイデンティティを持つ可能性があります(すなわち、同じ行を表します)。しかし、定義的には、分離状態のインスタンスの JVM アイデンティティは保証されません。開発者は、永続性クラスの equals()hashCode() メソッドをオーバーライドし、オブジェクト等価性の概念を実装すべきです。警告が1つあります:等価性の実装にデータベース識別子を使わないでください。ユニークな(普通は不変の)属性の組み合わせであるビジネスキーを使ってください。一時オブジェクトが永続化された場合、データベース識別子が変わります。一時オブジェクトを(通常分離インスタンスと共に)Set に保持する場合、ハッシュコードが変わるということは、 Set の契約を破るということです。ビジネスキーのための属性は、データベースの主キーほど安定すべきではないです。オブジェクトが同じ Set の中にいる間だけ、安定を保証すべきです。この問題のより徹底的な議論は、Hibernate の Web サイトを参照してください。また、これは Hibernate の問題ではなく、単に Java オブジェクトの識別子や等価性をどのように実装すべきかということです。

11.1.4. 一般的な問題

session-per-user-sessionsession-per-application アンチパターンは使ってはいけません(しかし、このルールには、まれに例外があります)。下記の問題のいくつかは、推奨パターンとしても出現する場合があります。そのため、設計を決定する前に、それによる影響も理解するようにしてください。
  • Session はスレッドセーフではありません。HTTP リクエスト、セッション Bean 、Swing ワーカーのように、同時実行が可能なものが Session インスタンスを共有すると、競合状態を引き起こします。(本章で後述する)HttpSession の中で Hibernate Session を保持する場合、 HttpSession へのアクセスを同期化することを考慮すべきです。さもなければ、ユーザーが素早くリロードをクリックすると、同時に走る2つのスレッドの中で、同じ Session が使われてしまうことがあります。
  • Hibernate が例外を投げた場合は、データベーストランザクションをロールバックし、直ちに Session を閉じるべきです (詳細を本章で後に議論します)。Session がアプリケーションに結び付けられているのであれば、アプリケーションを停止すべきです。データベーストランザクションをロールバックしても、ビジネスオブジェクトはトランザクションを開始したときの状態に戻りません。これは、データベースの状態とビジネスオブジェクトは同期していないことを意味します。通常、例外の回復ができないため、これは問題になりません。とにかくロールバックした後にやり直す必要があります。
  • Session は永続 (persistent) 状態のすべてのオブジェクトをキャッシュします(Hibernate は監視し、ダーティ状態かチェックします)。これは、長い間セッションを開いたままにするか、非常に多くのデータをロードし続けるかした場合は、 OutOfMemoryException が発生するまで無限に大きくなることを意味します。解決策の1つは、Session キャッシュを管理するために、 clear()evict() を呼ぶことです。しかし、大きなデータを処理する必要があるなら、たぶんストアドプロシージャを考慮するべきでしょう。いくつかの解決策は、13章バッチ処理 で紹介されています。ユーザーセッションの間、Session を開いたままにするということは、データが無効になっている確率が高くなることを意味します。

11.2. データベーストランザクション境界

データベース もしくはシステム:トランザクションの境界は、常に必要です。データベーストランザクションの外で、データベースとの通信は起きません(これは自動コミットモードに慣れている多くの開発者を混乱させるかもしれません)。読み込むだけの操作にでも、いつも明確なトランザクション境界を使用してください。分離レベルとデータベースの能力次第で、これは必要ないかもしれませんが、常にトランザクション境界を明示的に指定しても、マイナス面は全くありません。確かに、1つのデータベーストランザクションは多数の小さなトランザクションより 、データの読み込みであっても パフォーマンスがすぐれています。
J2EE 環境に管理されていない状態 (すなわち、スタンドアロン、単純な Web や Swing アプリケーション)でも、管理された状態でも、Hibernate アプリケーションを実行できます。管理されていない環境では、 Hiberante がデータベースのコネクションプールを提供します。アプリケーション開発者は、トランザクション境界を手動で設定しなければなりません。言い換えると、データベーストランザクションの開始、コミット、ロールバックを開発者自身が設定する必要があるということです。通常、管理された環境では、コンテナ管理によるトランザクション (CMT) が提供されます。(例えば、セッション Bean のデプロイメントディスクリプタで)宣言的に定義し、トランザクションを組み立てます。プログラムによるトランザクション境界はもう必要ありません。
しかしながら、管理されていないリソースローカルな環境と JTA に依存したシステム (CMT ではなく BMT) の両方に、永続化層を移植可能な状態に保つのは、通常望ましいことです。デプロイ環境のネイティブのトランザクションシステムへ変換するTransaction というラッパー API を Hibernate が提供します。このAPIを使うかは実際任意ではありますが、CMT のセッション Beanでの操作がないのであれば、APIの使用を強く推奨します。
通常、 Session 終了には、4つの異なるフェーズがあります:
  • セッションのフラッシュ
  • トランザクションのコミット
  • セッションのクローズ
  • 例外のハンドリング
セッションのフラッシュについては、前述しましたので、管理された環境と管理されていない環境の両方について、トランザクション境界と例外ハンドリングをもっと詳しく見ていきましょう。

11.2.1. 管理されていない環境

Hibernate の永続化層を管理されていない環境で実装する場合は、通常単純なコネクションプール (すなわち非 DataSource) によって、データベースコネクションを処理します。Hibernate はそのコネクションプールから必要なコネクションを取得します。セッション/トランザクション処理のイディオムは次のようになります:
// Non-managed environment idiom
Session sess = factory.openSession();
Transaction tx = null;
try {
    tx = sess.beginTransaction();

    // do some work
    ...

    tx.commit();
}
catch (RuntimeException e) {
    if (tx != null) tx.rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}
明示的に Sessionflush() を呼び出すべきではなく、そのセッションの 「セッションのフラッシュ」 によっては、commit() を呼び出すことにより、自動的に同期化処理が実行されます。 close() を呼び出すことにより、セッションの終わりを明確にします。 close() が暗黙的に行う主なことは、セッションが JDBC コネクションを開放することです。上記の Java コードはポータブルであり、管理されていない環境と JTA 環境の両方で実行できます。
すでに説明したように、はるかに適応性のある解決策は、Hibernate に予め組み込まれている 「current session」コンテキスト管理です。
// Non-managed environment idiom with getCurrentSession()
try {
    factory.getCurrentSession().beginTransaction();

    // do some work
    ...

    factory.getCurrentSession().getTransaction().commit();
}
catch (RuntimeException e) {
    factory.getCurrentSession().getTransaction().rollback();
    throw e; // or display error message
}
正規のアプリケーションの中では、このようなコードの切れ端を決して見ないでしょう。致命的な (システム) 例外は、常に「最上位」でキャッチすべきです。言い換えれば、永続化層でHibernate 呼び出しを実行するコードと、 RuntimeException を処理する (通常はクリーンアップと終了のみ行うことができる) コードは、別々の層にあります。Hibernate による現在のコンテキスト管理は、SessionFactory にアクセスするだけでこの設計をかなり単純にします。例外処理は、この章の後のほうで議論します。
org.hibernate.transaction.JDBCTransactionFactory (デフォルト)を選択するべきです。第2の用例としては、"thread"hibernate.current_session_context_class を選択するとよいでしょう。

11.2.2. JTA を使用する

永続化層をアプリケーションサーバー (例えば、 EJB セッション Bean の背後) で実行する場合、 Hibernate から取得するすべてのデータソースコネクションは、自動的にグローバル JTA トランザクションの一部になります。EJB を使わずに、スタンドアロンの JTA 実装を導入することもできます。JTA 統合のために、Hibernate は2つの戦略を提供します。
Bean 管理トランザクション(BMT)を使い、Transaction API を使う場合、 Hibernate はアプリケーションサーバーに BMT トランザクションの開始と終わりを告げます。すなわち、トランザクション管理のコードは、管理のない環境と同じになります。
// BMT idiom
Session sess = factory.openSession();
Transaction tx = null;
try {
    tx = sess.beginTransaction();

    // do some work
    ...

    tx.commit();
}
catch (RuntimeException e) {
    if (tx != null) tx.rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}
トランザクション境界として Session を使いたい場合、簡単にコンテキストを伝播する getCurrentSession() 機能があるので、 JTAの UserTransaction API を直接使用すべきでしょう。
// BMT idiom with getCurrentSession()
try {
    UserTransaction tx = (UserTransaction)new InitialContext()
                            .lookup("java:comp/UserTransaction");

    tx.begin();

    // Do some work on Session bound to transaction
    factory.getCurrentSession().load(...);
    factory.getCurrentSession().persist(...);

    tx.commit();
}
catch (RuntimeException e) {
    tx.rollback();
    throw e; // or display error message
}
CMT では、トランザクション境界をセッション Bean のデプロイメントディスクリプタで定義し、プログラムでは行いません。コードは次のように少なくなります:
// CMT idiom
 Session sess = factory.getCurrentSession();

 // do some work
 ...
CMT/EJB の中では、ロールバックが自動的に実施されます。セッション Bean のメソッドにより投げられた処理されていない RuntimeException は、グローバルトランザクションをロールバックするようコンテナに伝えるためです。これは、BMT もしくは CMT と一緒に Hibernate Transaction API を使う必要はまったくなくトランザクションにバインドする「現在の」セッションを自動伝搬できます。
Hibernate のトランザクションファクトリを設定する際に、JTA を直接使う (BMTの) 場合は org.hibernate.transaction.JTATransactionFactory を、 CMT セッション Bean の中では org.hibernate.transaction.CMTTransactionFactory を選択してください。hibernate.transaction.manager_lookup_class をセットすることも忘れないでください。なお、hibernate.current_session_context_class は、セットしないか(後方互換)、"jta" をセットしてください。
getCurrentSession() オペレーションは、JTA 環境で欠点が1つあります。デフォルトで使われる after_statement コネクションリリースモードを使用する上で、警告が1つあります。JTA 仕様の制約のために、scroll() または iterate() が返した、閉じられていない ScrollableResults または Iterator インスタンスを Hibernate が自動的にクリーンアップすることはできません。finally ブロックの中で、 ScrollableResults.close() または Hibernate.close(Iterator) を明示的に呼び出して、基盤のデータベースカーソルを解放 しなければなりません。多くのアプリケーションでは、 JTA か CMT コードから、scroll()iterate() の使用を簡単に避けることができます。

11.2.3. 例外ハンドリング

Session が例外 (SQLExceptionを含む) を投げた場合、直ちに、データベーストランザクションをロールバックし、 Session.close() を呼び、 Session インスタンスを破棄すべきです。Session のいくつかのメソッドは、セッションを一貫した状態には保ちません。Hibernate が投げた例外を、回復できるものとして扱うことはできません。 finally ブロックの中で close() を呼んで、 Session が確実に閉じられるようにしてください。
HibernateException は、Hibernate 永続化層の中で発生する多くのエラーをラップする、検査されない例外です。これは、Hibernate の古いバージョンにはありませんでした。私たちの意見は、アプリケーション開発者に回復不可能な例外を下層でキャッチすることを強要すべきではないということです。多くのシステムでは、検査されない例外と致命的な例外は、コールスタックの最初のフレームの1つ (例えば、上層で) で処理し、エラーメッセージをアプリケーションユーザーに表示するか、もしくは、他の適切な処理を実施します。Hibernate は、HibernateException 以外の検査されない例外も投げることに注意してください。これらもまた、回復不可能であり、適切な処理を実施すべきです。
Hibernate は、データベースとの対話中に投げられた SQLExceptionJDBCException でラップします。実際は、例外をより意味のある JDBCException のサブクラスに変換しようと試みます。元の SQLException は、 JDBCException.getCause() によりいつでも得られます。Hibernate は、 SessionFactory に追加されている SQLExceptionConverter を使い、SQLException を適当な JDBCException サブクラスに変換します。デフォルトでは、SQLExceptionConverter は設定されている SQL 方言により定義されます。一方で、独自の実装に差し替えることもできます。詳細は、 SQLExceptionConverterFactory クラスの Javadoc を参照してください。標準的な JDBCException のサブタイプを下記に示します。
  • JDBCConnectionException :基礎となる JDBC 通信のエラーを表します。
  • SQLGrammarException: 発行する SQL の文法もしくは構文の問題を表します。
  • ConstraintViolationException:何らかの形式の完全性制約違反を表します。
  • LockAcquisitionException:要求された操作を実施するのに必要なロックレベルを得る際のエラーを表します。
  • GenericJDBCException:他のカテゴリに入らなかった一般的な例外です。

11.2.4. トランザクションのタイムアウト

EJB などの管理環境で提供する極めて重要な特徴の1つは、トランザクションのタイムアウトです。これは管理されていないコードには提供できません。トランザクションタイムアウトにより、不正なトランザクションがユーザーにレスポンスを返さないまま、無期限にリソースを使い続けないようにします。管理環境 (JTA) の外では、Hibernate はこの機能をフルに提供できません。しかしながら、 Hibernate は次のようなデータアクセス操作の制御くらいはできます。データベースレベルのデッドロックや大きなリザルトセットを返すクエリを定義されたタイムアウトによって確実に制限します。管理された環境では、 Hibernate はトランザクションタイムアウトを JTA に委譲します。この機能は、Hibernate の Transaction オブジェクトによって抽象化されています。
Session sess = factory.openSession();
try {
    //set transaction timeout to 3 seconds
    sess.getTransaction().setTimeout(3);
    sess.getTransaction().begin();

    // do some work
    ...

    sess.getTransaction().commit();
}
catch (RuntimeException e) {
    sess.getTransaction().rollback();
    throw e; // or display error message
}
finally {
    sess.close();
}
CMT Bean の中では setTimeout() を呼び出せないことに注意してください。トランザクションタイムアウトは宣言的に定義しなければなりません。

11.3. 楽観的同時実行制御

高い並列性と高いスケーラビリティの両方を実現するアプローチは、バージョニングを使った楽観的同時実行制御のみです。更新の衝突を見つけ、更新が失われるのを防ぐために、バージョン番号もしくはタイムスタンプを使って、バージョンをチェックします。Hibernate は、楽観的同時実行を行うアプリケーションコードを書くためのアプローチを3つ提供します。ここでお話するユースケースは、長い会話といったコンテキストですが、バージョンチェックは1つのデータベーストランザクションの中で更新を失うことを防ぐ利点も持っています。

11.3.1. アプリケーションによるバージョンチェック

Hibernate の支援がほぼない状態で実装するケースにおいて、データベースとのやり取りは、それぞれ新しい Session の中で起こります。開発者は、すべての永続性インスタンスを操作する前に、データベースから再読み込みする責務があります。会話トランザクションの分離を確保するために、アプリケーション自身がバージョンチェックを行う必要があります。このアプローチは、データベースアクセスの中では、最も非効率で、エンティティ EJB と最も似ているアプローチです。
// foo is an instance loaded by a previous Session
session = factory.openSession();
Transaction t = session.beginTransaction();

int oldVersion = foo.getVersion();
session.load( foo, foo.getKey() ); // load the current state
if ( oldVersion != foo.getVersion() ) throw new StaleObjectStateException("Message", foo.getId()); 
foo.setProperty("bar");

t.commit();
session.close();
<version> を使って、 version プロパティをマッピングします。 Hibernate は、エンティティがダーティである場合、フラッシュし、その間に version プロパティを自動的にインクリメントします。
データの並列性が低い環境で運用しており、バージョンチェックが不要なら、このアプローチを使い、バージョンチェックをスキップすることができます。この場合は、長い会話には、最後にコミットしたものが勝つ がデフォルトの戦略でしょう。このアプローチは、アプリケーションのユーザーを混乱させるかもしれないことを心に留めて置いてください。それは、エラーメッセージや競合した変更をマージする機会がないまま、更新を失う可能性があるからです。
マニュアルによるバージョンチェックは、普通の状況であれば実行できますが、多くのアプリケーションにとって実用的ではありません。1つのインスタンスだけでなく、修正されたオブジェクトの完全なグラフをチェックしなければなりません。Hibernate は、設計パラダイムとして、拡張 Session か分離されたインスタンスを自動的にバージョンチェックします。

11.3.2. 拡張セッションと自動バージョニング

1つの Session インスタンスとその永続性インスタンスは、 session-per-conversation として知られる、会話全体で使われます。Hibernate はフラッシュする際に、インスタンスのバージョンをチェックします。同時修正を検出すると、例外を投げます。この例外をキャッチして処理するかは開発者次第です。一般的な選択肢は、変更をマージするか無効でないデータでビジネス会話を再スタートする機会をユーザーに提供することです。
ユーザーの対話を待っているときは、Session を基礎となる JDBC コネクションから切断します。このアプローチは、データベースアクセスの中では、最も効率的です。アプリケーションは、バージョンチェックや分離されたインスタンスの再接続、あらゆるデータベーストランザクションの中でインスタンスを再読み込みを行う必要はありません。
// foo is an instance loaded earlier by the old session
Transaction t = session.beginTransaction(); // Obtain a new JDBC connection, start transaction

foo.setProperty("bar");

session.flush();    // Only for last transaction in conversation
t.commit();         // Also return JDBC connection
session.close();    // Only for last transaction in conversation
foo オブジェクトは、自分をロードした Session を把握しいます。古いセッション上で新しいデータベーストランザクションを開始することで、新しいコネクションを取得し、そのセッションが再開されます。データベーストランザクションをコミットすることで、セッションから JDBC コネクションを切断し、コネクションをプールに返します。再接続した後、更新していないデータのバージョンチェックを強制するために、他のトランザクションにより更新されているかもしれないオブジェクトに関して、 LockMode.READ をつけて Session.lock() を呼び出すことができます。更新して いる データをロックする必要はありません。通常、拡張 SessionFlushMode.NEVER をセットします。最後のデータベーストランザクションの周期でのみ、会話の中で変更されたすべてを実際に永続化させることができます。ゆえに、この最後のデータベーストランザクションのみが flush() オペレーションを含みます。そして、会話を終わらせるために、セッションも close() します。
ユーザーが考慮中に、格納することができないくらい Session が大きいのであれば、このパターンは問題があります(例えば、 HttpSession は可能な限り小さく保つべきです)。 Session は (強制的に) 1次キャッシュでもあり、ロードしたオブジェクトをすべて保持しするため、おそらく、リクエスト/レスポンスのサイクルが2〜3回のみであれば、この戦略が使えます。データの期限がすぐに切れるため、1つの会話のためだけに Session を使いましょう。

注記

Hibernate の以前のバージョンは、明示的な Session の切断と再接続が必要でした。トランザクションの開始と終了は同じ効果があるため、これらのメソッドは推奨されません。
切断した Session を永続化層の近くで保持すべきであることに注意してください。また、EJB ステートフルセッション Bean を使い、3層環境の中で Session を保持してください。HttpSession に格納するために、 Web 層への転送、別の層へのシリアライズは行わないでください。
拡張セッションパターン、もしくは、session-per-conversation は、自動的なカレントセッションコンテキスト管理を実施するより難しく、これについては、自身でCurrentSessionContext の実装を供給する必要があります。Hibernate Wiki にある例を参照してください。

11.3.3. 分離オブジェクトと自動バージョニング

新しい Session により、永続化ストア (訳注:DB) との対話が発生します。また一方、同じ永続性インスタンスが、データベースとの対話ごとに再利用されます。アプリケーションは、元々は他の Session でロードされ、分離インスタンスの状態を操作します。そして、Session.update() もしくは、 Session.saveOrUpdate()Session.merge() を使って、それらのインスタンスを再追加します。
// foo is an instance loaded by a previous Session
foo.setProperty("bar");
session = factory.openSession();
Transaction t = session.beginTransaction();
session.saveOrUpdate(foo); // Use merge() if "foo" might have been loaded already
t.commit();
session.close();
この場合もやはり、Hibernate はフラッシュする際に、インスタンスのバージョンをチェックします。更新の競合が発生した場合には、例外を投げます。
オブジェクトが修正されていないと確信している場合は、update() の代わりに、 LockMode.READ を使って、 lock() を呼び出すこともできます (すべてのキャッシュを迂回し、バージョンチェックを実施します)。

11.3.4. 自動バージョニングのカスタマイズ

マッピングの optimistic-lock 属性に false を設定することにより、特定のプロパティやコレクションのために自動バージョンインクリメントを無効にできます。プロパティがダーティであっても、バージョンをインクリメントしません。
レガシーのデータベーススキーマは通常、静的であり、変更できません。または、他のアプリケーションが同じデータベースにアクセスしなければならず、そのアプリケーションはバージョン番号やタイムスタンプさえ処理する方法を知りません。どちらの場合も、テーブルの特定のカラムを当てにして、バージョニングを行えません。バージョンやタイムスタンプのプロパティをマッピングせずに、バージョンチェックさせるために、 <class> マッピングに optimistic-lock="all" を指定してください。行のすべてのフィールドの状態を比較するようになります。これは、Hibernate が古い状態と新しい状態を比較できる場合にのみ、理論上では動作します。(すなわち、 session-per-request-with-detached-objects ではなく、1つの長い Session を使う場合です)。
行われた変更が重ならないインスタンスに限り、同時に行われた変更を受け入れることができます。<class> のマッピング時に optimistic-lock="dirty" を設定した場合、Hibernate はフラッシュ時にダーティフィールドのみを比較します。
専用のバージョン/タイムスタンプのカラムを使う場合、もしくはすべて/ダーティのフィールドを比較する場合どちらであっても、Hibernate はエンティティごとに1つの UPDATE 文を 適切な WHERE 節と共に使い、バージョンチェックと情報の更新を行います。関連するエンティティの再追加をカスケードするために、連鎖的な永続化を使用した場合、不必要な更新を実行するかもしれません。これは通常問題になりませんが、分離したインスタンスを変更していなくとも、データベースの on update トリガーが実行されるかもしれません。<class> マッピングに select-before-update="true" を設定することによって、この振る舞いをカスタマイズできます。こうすることでHibernateが行の必ずインスタンスを SELECT し、更新前に確実に変更されるようにします。

11.4. 悲観的ロック

悲観的ロックは、ユーザーがロック戦略に悩むのに多くの時間を費やすためのものではありません。通常は、JDBC コネクションに分離レベルを指定し、単にデータベースにすべての処理をさせれば十分です。しかしながら、高度なユーザーは、排他的な悲観的ロックの獲得や、新しいトランザクションが開始される際のロックの再獲得をしたいと考えるかもしれません。
Hibernate はいつもデータベースのロックの仕組みを使います。メモリ内のオブジェクトを決してロックしません。
LockMode クラスは、Hibernate が獲得できる異なるロックレベルを定義します。以下の仕組みにより、ロックを獲得します。
  • LockMode.WRITE は、 Hibernate が行を更新もしくは挿入する際に自動的に得られます。
  • LockMode.UPGRADE は、データベースでサポートされている文法 SELECT ... FOR UPDATE を使いユーザーが明示的に要求することで得ることができます。
  • LockMode.UPGRADE_NOWAIT は、 Oracle で SELECT ... FOR UPDATE NOWAIT を使いユーザーが明示的に要求することで得ることができます。
  • LockMode.READ は、 Repeatable Read もしくは Serializable の分離レベルで、データを読んだ際に自動的に得られます。明示的なユーザー要求により、再取得されます。
  • LockMode.NONE は、ロックしないことを表します。 Transaction の終わりに、すべてのオブジェクトはこのロックモードに切り替わります。 update()saveOrUpdate() を呼び出すことによって、セッションに関連付けられたオブジェクトも、このロックモードで出発します。
「明示的なユーザー要求」とは、下記の方法の1つで言い表せます。
  • LockMode を指定した Session.load() の呼び出し。
  • Session.lock() の呼び出し。
  • Query.setLockMode() の呼び出し。
UPGRADE もしくは UPGRADE_NOWAIT が指定された Session.load() が呼び出され、かつ要求されたオブジェクトがセッションによってまだロードされていなかった場合は、 SELECT ... FOR UPDATE を使って、オブジェクトがロードされます。 load() で呼び出されたオブジェクトが、要求されているより制限が少ないロックですでにロードされていた場合は、 Hibernate はそのオブジェクトのために、 lock() を呼び出します。
指定されたロックモードが READ もしくは、 UPGRADEUPGRADE_NOWAIT だった場合、 Session.lock() は、バージョン番号のチェックを実施します。 UPGRADE もしくは UPGRADE_NOWAIT の場合、 SELECT ... FOR UPDATE が使われます。
データベースが要求されたロックモードをサポートしていない場合、Hibernate は例外を投げる代わりに、適切な代わりのモードを使います。これは、アプリケーションがポータブルであることを保証します。

11.5. コネクション開放モード 

Hibernate のレガシー(2.x)の JDBC コネクション管理に関する振る舞いは、最初に必要とした際に Session がコネクションを得て、セッションが閉じられるまで、そのコネクションを保持しました。 Hibernate 3.x は、セッションに JDBC コネクションをどのように制御するかを伝えるコネクション開放モードという概念を導入しました。以降の議論は、構成された ConnectionProvider を通して提供されるコネクションに適切であることに注意してください。異なる開放モードは、org.hibernate.ConnectionReleaseMode に列挙された値により特定されます。
  • ON_CLOSE:本質的に上記で述べたレガシーの振る舞いです。 Hibernate セッションは最初に JDBC アクセスを実行する必要がある際にコネクションを得ます。そして、セッションが閉じられるまで、コネクションを保持します。
  • AFTER_TRANSACTIONorg.hibernate.Transaction が完了した後、コネクションを開放します。
  • AFTER_STATEMENT (積極的な開放とも呼ばれる):すべてのステートメントが実行された後、コネクションが開放されます。ステートメントがセッションに関連するリソースを開いたままにする場合は、この積極的な開放はスキップされます。今のところ、これが起こるのは org.hibernate.ScrollableResults が使われる場合のみです。
コンフィギュレーションパラメータの hibernate.connection.release_mode は、使用する開放モードを指定するために使います。指定できる値は次の通りです:
  • auto (デフォルト):これを選択すると org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode() メソッドによって返される開放モードに委譲されます。このメソッドは、 JTATransactionFactory には ConnectionReleaseMode.AFTER_STATEMENT を返し、 JDBCTransactionFactory には ConnectionReleaseMode.AFTER_TRANSACTION を返します。このデフォルトの動作を変更しないでください。というのは、この設定値が原因で起こる障害は、ユーザーコードの中でバグや間違った条件になりやすいからです。
  • on_close - ConnectionReleaseMode.ON_CLOSE を使います。この設定は後方互換のために残されていますが、当設定の使用はお薦めできません。
  • after_transaction:ConnectionReleaseMode.AFTER_TRANSACTION を使います。この設定は JTA 環境の中では使うべきではありません。また、ConnectionReleaseMode.AFTER_TRANSACTION を指定し、自動コミットモードの中では、開放モードが AFTER_STATEMENT であるかのように、コネクションは開放されることに注意してください。
  • after_statement:ConnectionReleaseMode.AFTER_STATEMENT を使います。さらに、設定された ConnectionProvider は、この設定 (supportsAggressiveRelease()) をサポートするかどうかを調べるために使用します。そうでない場合、開放モードは ConnectionReleaseMode.AFTER_TRANSACTION にリセットされます。この設定は次の環境でのみ安全です。それは、 ConnectionProvider.getConnection() を呼び出すたびに基盤となる JDBC コネクションが同じものを取得できるか、同じコネクションが得られることが問題とならない自動コミット環境の中です。

第12章 インターセプタとイベント

アプリケーションが Hibernate の内部で発生するイベントに対応できると役に立つことがあります。ある種の一般的な機能を実装し、また Hibernate の機能を拡張することもできるようになります。

12.1. インターセプタ

Interceptor インターフェースを使って、セッションからアプリケーションへコールバックをすることができます。これにより永続オブジェクトの保存、更新、削除、読み込みの前に、アプリケーションがプロパティを検査したり操作したりできるようになります。これは監査情報の追跡に利用できます。下の例で InterceptorAuditable が作成されると自動的に createTimestamp を設定し、Auditable が更新されると自動的に lastUpdateTimestamp プロパティを更新します。
Interceptor を直接実装したり、EmptyInterceptor を拡張したりできます。
package org.hibernate.test;

import java.io.Serializable;
import java.util.Date;
import java.util.Iterator;

import org.hibernate.EmptyInterceptor;
import org.hibernate.Transaction;
import org.hibernate.type.Type;

public class AuditInterceptor extends EmptyInterceptor {

    private int updates;
    private int creates;
    private int loads;

    public void onDelete(Object entity,
                         Serializable id,
                         Object[] state,
                         String[] propertyNames,
                         Type[] types) {
        // do nothing
    }

    public boolean onFlushDirty(Object entity,
                                Serializable id,
                                Object[] currentState,
                                Object[] previousState,
                                String[] propertyNames,
                                Type[] types) {

        if ( entity instanceof Auditable ) {
            updates++;
            for ( int i=0; i < propertyNames.length; i++ ) {
                if ( "lastUpdateTimestamp".equals( propertyNames[i] ) ) {
                    currentState[i] = new Date();
                    return true;
                }
            }
        }
        return false;
    }

    public boolean onLoad(Object entity,
                          Serializable id,
                          Object[] state,
                          String[] propertyNames,
                          Type[] types) {
        if ( entity instanceof Auditable ) {
            loads++;
        }
        return false;
    }

    public boolean onSave(Object entity,
                          Serializable id,
                          Object[] state,
                          String[] propertyNames,
                          Type[] types) {

        if ( entity instanceof Auditable ) {
            creates++;
            for ( int i=0; i<propertyNames.length; i++ ) {
                if ( "createTimestamp".equals( propertyNames[i] ) ) {
                    state[i] = new Date();
                    return true;
                }
            }
        }
        return false;
    }

    public void afterTransactionCompletion(Transaction tx) {
        if ( tx.wasCommitted() ) {
            System.out.println("Creations: " + creates + ", Updates: " + updates + "Loads: " + loads);
        }
        updates=0;
        creates=0;
        loads=0;
    }

}
インターセプタには二種類あります:Session スコープとと SessionFactory スコープ。
Session スコープのインターセプタは、セッションをオープンするときに指定します。 Interceptor を引数に取る SessionFactory.openSession() のオーバーロードメソッドの一つを使います。
Session session = sf.openSession( new AuditInterceptor() );
SessionFactory スコープのインターセプタは SessionFactory の構築の前に、Configuration オブジェクトを使って登録します。この場合、提供されるインターセプタは SessionFactory からオープンされたすべてのセッションに適用されます。これは使用するインターセプタを明示的に指定してセッションをオープンしない限り、そうなります。SessionFactory スコープのインターセプタはスレッドセーフでなければなりません。複数のセッションがこのインターセプタを同時に使用する可能性があるため、セッション固有の状態を格納しないように気をつけてください。
new Configuration().setInterceptor( new AuditInterceptor() );

12.2. イベントシステム

永続化層で特定のイベントに対応しなければならない場合、Hibernate3 の イベント アーキテクチャを使うこともできます。さらにイベントシステムはインターセプタと一緒に使うか、またはインターセプタの代わりとして使うこともできます。
Session インターフェースのメソッドはすべて、1個のイベントと相関します。例えば LoadEventFlushEvent などがあります。定義済みのイベント型の完全一覧については、XML 設定ファイルの DTD や org.hibernate.event パッケージを調べてください。リクエストがこれらのメソッドの1つから作られるとき、Hibernate の Session は適切なイベントを生成し、そのイベント型に設定されたイベントリスナに渡します。追加設定なしで、これらのリスナはそのメソッドと同じ処理を実装します。とはいえ、リスナインターフェースの一つを自由にカスタム実装できます (つまり、 LoadEvent は登録された LoadEventListener インターフェースの実装により処理されます)。その場合、その実装には Session から作られたどのような load() リクエストをも処理する責任があります。
リスナは事実上シングルトンであると見なせます。つまり、リスナはリクエスト間で共有されるため、インスタンス変数として状態を保持するべきではありません。
カスタムリスナは処理したいイベントについて適切なインターフェースを実装するべきです。便利な基底クラスのうちの一つを継承してもよいです (または Hibernate がデフォルトで使用するイベントリスナを継承してもよいです。すばらしいことに、この目的のために非 final として宣言されています)。カスタムリスナは Configuration オブジェクトを使ってプログラムから登録するか、Hibernate の XML 設定ファイルで指定できます。プロパティファイルで宣言的に設定する方法はサポートされていません。ここで、カスタムロードイベントリスナの例を示します:
public class MyLoadListener implements LoadEventListener {
    // this is the single method defined by the LoadEventListener interface
    public void onLoad(LoadEvent event, LoadEventListener.LoadType loadType)
            throws HibernateException {
        if ( !MySecurity.isAuthorized( event.getEntityClassName(), event.getEntityId() ) ) {
            throw new MySecurityException("Unauthorized access");
        }
    }
}
デフォルトリスナ以外のリスナを使うには、 Hibernate への設定も必要です:
<hibernate-configuration>
    <session-factory>
        ...
        <event type="load">
            <listener class="com.eg.MyLoadListener"/>
            <listener class="org.hibernate.event.def.DefaultLoadEventListener"/>
        </event>
    </session-factory>
</hibernate-configuration>
代わりに、プログラムで登録する方法もあります:
Configuration cfg = new Configuration();
LoadEventListener[] stack = { new MyLoadListener(), new DefaultLoadEventListener() };
cfg.getEventListeners().setLoadEventListeners(stack);
リスナを宣言的に登録するとインスタンスを共有できません。複数の <listener/> 要素で同じクラス名が使われると、それぞれの参照はそのクラスの別インスタンスを指すことになります。リスナ型の間でリスナインスタンスを共有する必要があれば、プログラムで登録する方法を採らなければなりません。
なぜインターフェースを実装して、特化した型を設定時に指定するのでしょうか?リスナの実装に、複数のイベントリスナインターフェースを実装できるからです。登録時に追加で型を指定することで、カスタムリスナの on/off を設定時に簡単に切り替えられます。

12.3. Hibernate の宣言的なセキュリティ

一般的に Hibernate アプリケーションの宣言的なセキュリティは、セッションファサード層で管理します。Hiberenate3 は JACC で許可し、さらに JAAS で認証したアクションも可能です。これはイベントアーキテクチャの最上位に組み込まれているオプション機能です。
まず最初に、適切なイベントリスナを設定して JAAS 認証を使えるようにしなければなりません。
<listener type="pre-delete" class="org.hibernate.secure.JACCPreDeleteEventListener"/>
<listener type="pre-update" class="org.hibernate.secure.JACCPreUpdateEventListener"/>
<listener type="pre-insert" class="org.hibernate.secure.JACCPreInsertEventListener"/>
<listener type="pre-load" class="org.hibernate.secure.JACCPreLoadEventListener"/>
特定のイベント型に対してちょうど一つのリスナがあるとき、<listener type="..." class="..."/><event type="..."><listener class="..."/></event> の簡略形に過ぎないことに注意してください。
次に、同じく hibernate.cfg.xml でロールにパーミッションをバインドしてください:
<grant role="admin" entity-name="User" actions="insert,update,read"/>
<grant role="su" entity-name="User" actions="*"/>
このロール名は使用する JACC プロバイダに理解されるロールです。

第13章 バッチ処理

Hibernate を使ってデータベースに10万行を挿入する愚直な方法は、このようなものです:
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
for ( int i=0; i<100000; i++ ) {
    Customer customer = new Customer(.....);
    session.save(customer);
}
tx.commit();
session.close();
これは50,000番目の行のあたりで OutOfMemoryException で失敗するでしょう。Hibernate がセッションレベルキャッシュで、新しく挿入されたすべての Customer インスタンスをキャッシュするからです。この章で、こういう問題を回避する方法を説明します。
バッチ処理をするなら、JDBC バッチが使用可能であることが非常に重要です。そうでなければ手頃なパフォーマンスが得られません。JDBC バッチサイズを手頃な数値(例えば、10から50)に設定してください:
hibernate.jdbc.batch_size 20
identiy 識別子生成を使う場合は、Hibernate は JDBC レベルでインサートバッチングを無効にします。
また二次キャッシュとの相互作用が完全に無効になっているプロセスで、このような作業をしたいと思うかもしれません:
hibernate.cache.use_second_level_cache false
しかし、これは絶対に必要というわけではありません。なぜなら明示的に CacheMode を設定して、二次キャッシュとの相互作用を無効にすることができるからです。

13.1. バッチ挿入

新しいオブジェクトを永続化する場合、一次キャッシュのサイズを制限するため、定期的にセッションを flush() して clear() してください。
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
   
for ( int i=0; i<100000; i++ ) {
    Customer customer = new Customer(.....);
    session.save(customer);
    if ( i % 20 == 0 ) { //20, same as the JDBC batch size
        //flush a batch of inserts and release memory:
        session.flush();
        session.clear();
    }
}
   
tx.commit();
session.close();

13.2. バッチ更新

データの復元や更新を行うには、同じ考えを適用します。それに加えて、データの行を多く返すクエリに対して有効なサーバーサイドのカーソルの利点を生かすには scroll() を使う必要があります。
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
   
ScrollableResults customers = session.getNamedQuery("GetCustomers")
    .setCacheMode(CacheMode.IGNORE)
    .scroll(ScrollMode.FORWARD_ONLY);
int count=0;
while ( customers.next() ) {
    Customer customer = (Customer) customers.get(0);
    customer.updateStuff(...);
    if ( ++count % 20 == 0 ) {
        //flush a batch of updates and release memory:
        session.flush();
        session.clear();
    }
}
   
tx.commit();
session.close();

13.3. StatelessSession インターフェース

また別の方法として、Hibernate はコマンド指向の API を用意しています。これは分離オブジェクトの形で、データベースとのデータストリームのやり取りに使うことができます。StatelessSession は関連する永続コンテキストを持たず、上層レベルのライフサイクルセマンティクスの多くを提供しません。特にステートレスセッションは、一次キャッシュを実装せず、またどのような二次キャッシュやクエリキャッシュとも相互作用しません。トランザクション write-behind や自動ダーティチェックも実装しません。ステートレスセッションを使って行われる操作が、関連するインスタンスへカスケードされることは決してありません。コレクションは、ステートレスセッションからは無視されます。ステートレスセッションを通して行われる操作は、 Hibernate のイベントモデルやインターセプタの影響を受けません。一次キャッシュを持たないため、ステートレスセッションはエイリアスの影響を受けるデータに上手く対処できません。ステートレスセッションは低レベルの抽象化であり、基盤のJDBC にはるかによく似ています。
StatelessSession session = sessionFactory.openStatelessSession();
Transaction tx = session.beginTransaction();
   
ScrollableResults customers = session.getNamedQuery("GetCustomers")
    .scroll(ScrollMode.FORWARD_ONLY);
while ( customers.next() ) {
    Customer customer = (Customer) customers.get(0);
    customer.updateStuff(...);
    session.update(customer);
}
   
tx.commit();
session.close();
このコード例では、クエリが返す Customer インスタンスは即座に 分離されます。これは、どのような永続コンテキストとも決して関連しません。
StatelessSession インターフェースで定義されている insert(), update()delete() の操作は、行レベルの直接的なデータベース操作と考えられます。結果として、 SQL の INSERT, UPDATE または DELETE がそれぞれ即座に実行されます。このように、これらは Session インターフェースで定義されている save(), saveOrUpdate()delete() とは異なる意味を持ちます。

13.4. DML スタイルの操作

すでに議論したように、自動的かつ透過的なオブジェクト/リレーショナルマッピングは、オブジェクト状態の管理であると考えられます。このオブジェクトの状態は、メモリ内で利用できます。そのため (SQLの データ操作言語 (DML) 文: INSERTUPDATEDELETE を使って)データベース内のデータを直接操作しても、インメモリの状態には影響を与えません。しかし Hibernate は、バルク SQL スタイルの DML 文実行に対応するメソッドを用意しています。これは Hibernate クエリ言語 (14章HQL: Hibernate クエリ言語) を通して実行されます。
UPDATEDELETE 文の疑似構文は: ( UPDATE | DELETE ) FROM? EntityName (WHERE where_conditions)? です。注意すべき点がいくつかあります:
注意点:
  • from 節において、 FROM キーワードはオプションです。
  • from 節ではエンティティ名1つだけが可能ですが、別名を付けることができます。エンティティ名に別名が与えられると、どのようなプロパティ参照も、その別名を使って修飾しなければなりません。エンティティ名に別名が与えられなければ、どのようなプロパティ参照も修飾してはなりません。
  • 暗黙的であれ明示的であれ 「結合構文の形式」をバルク HQL クエリ内で指定することはできません。サブクエリは where 節で使うことができます。サブクエリそのものは、結合を含められます。
  • where 節はオプションです。
例として、HQL の UPDATE を実行するには、Query.executeUpdate() メソッドを使ってください。このメソッドはおなじみの JDBC PreparedStatement.executeUpdate() から名付けられました:
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();

String hqlUpdate = "update Customer c set c.name = :newName where c.name = :oldName";
// or String hqlUpdate = "update Customer set name = :newName where name = :oldName";
int updatedEntities = session.createQuery( hqlUpdate )
        .setString( "newName", newName )
        .setString( "oldName", oldName )
        .executeUpdate();
tx.commit();
session.close();
EJB3 仕様を受け継いでおり、HQL の UPDATE 文は、デフォルトでは、作用するエンティティの 「Version(オプション)」 バージョンや 「Timestamp(オプション)」 タイムスタンプのプロパティの値には影響しません。しかし versioned update を使って、 versiontimestamp プロパティの値を強制的にリセットさせることができます。これは UPDATE キーワードの後に VERSIONED キーワードを追加することで行えます。
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();
String hqlVersionedUpdate = "update versioned Customer set name = :newName where name = :oldName";
int updatedEntities = session.createQuery( hqlVersionedUpdate )
        .setString( "newName", newName )
        .setString( "oldName", oldName )
        .executeUpdate();
tx.commit();
session.close();
カスタムバージョン型(org.hibernate.usertype.UserVersionType)は update versioned 文と一緒に使えません。
HQL の DELETE を実行するには、同じ Query.executeUpdate() メソッドを使ってください:
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();

String hqlDelete = "delete Customer c where c.name = :oldName";
// or String hqlDelete = "delete Customer where name = :oldName";
int deletedEntities = session.createQuery( hqlDelete )
        .setString( "oldName", oldName )
        .executeUpdate();
tx.commit();
session.close();
Query.executeUpdate() メソッドが返す int の値は、この操作が影響を及ぼしたエンティティの数です。これが影響するデータベース内の行数と、相互に関係する場合と、しない場合があります。HQL バルク操作は、結果として、実際の SQL 文が複数実行されることがあります(例:joined-subclass)。返される数は、その文によって影響を受けた実際のエンティティの数を示します。joined-subclass の例に戻ると、サブクラスの一つに対する削除は、そのサブクラスがマッピングされたテーブルだけではなく、「ルート」テーブルと継承階層をさらに下った joined-subclass のテーブルの削除になります。
INSERT 文の疑似構文は: INSERT INTO エンティティ名プロパティリスト select 文 です。注意すべき点がいくつかあります:
  • INSERT INTO ... SELECT ... の形式だけがサポートされています。 INSERT INTO ... VALUES ... の形式はサポートされていません。
    properties_list は、SQL の INSERT 文における カラムの仕様 に類似しています。継承のマッピングに含まれるエンティティに対して、クラスレベルで直接定義されたプロパティだけが、プロパティリストに使えます。スーパークラスのプロパティは認められず、サブクラスのプロパティは効果がありません。言い換えると INSERT 文は、本質的にポリモーフィックではありません。
  • select_statementは有効なHQL select クエリになりえますが、注意としては、返り値の型が insert 文の期待する型とマッチしていなければなりません。現在このチェックをデータベースへ任せるのではなく、クエリのコンパイル時にチェックします。このことは、 equal とは違い、Hibernate の Type 間の equivalent に関する問題を引き起こすことに注意してください。これは org.hibernate.type.DateType として定義されたプロパティと、 org.hibernate.type.TimestampType として定義されたプロパティの間のミスマッチの問題を引き起こします。データベースがそれらを区別できなくても、変換することができても、この問題は発生します。
  • id プロパティに対して、insert 文には二つの選択肢があります。properties_listで明示的に id プロパティを指定するか (この場合、対応する select 式から値が取られます)、プロパティリストからそれを除外するかのいずれかです (この場合、生成される値が使われます)。後者の選択肢は、データベース内を操作する id ジェネレータを使うときのみ、利用可能です。この選択肢を採る場合、「インメモリ」型のジェネレータを使うと、構文解析時に例外が発生します。この議論では、インデータベース型ジェネレータは org.hibernate.id.SequenceGenerator (とそのサブクラス) と、 org.hibernate.id.PostInsertIdentifierGenerator の実装であると考えています。ここで最も注意すべき例外は、 org.hibernate.id.TableHiLoGenerator です。値を取得する選択可能な方法がないため、このジェネレータを使うことはできません。
  • versiontimestamp としてマッピングされるプロパティに対して、insert 文には二つの選択肢があります。properties_listで明示的にプロパティを指定するか(この場合、対応する select 式から値が取られます)、プロパティリストから除外するか(この場合、 org.hibernate.type.VersionType で定義された シード値 が使われます)のいずれかです。
以下は、HQL の INSERT 文の実行例です:
Session session = sessionFactory.openSession();
Transaction tx = session.beginTransaction();

String hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ...";
int createdEntities = session.createQuery( hqlInsert )
        .executeUpdate();
tx.commit();
session.close();

第14章 HQL: Hibernate クエリ言語

Hibernate は SQL に似た 強力な問い合わせ言語 ( HQL ) を利用しています。しかし SQL と比較すると、HQL は完全にオブジェクト指向であり、継承、ポリモーフィズムや関連などの概念を理解します。

14.1. 大文字と小文字の区別

クエリは Java のクラス名とプロパティ名を除いて大文字、小文字を区別しません。従って SeLeCTsELEct と同じで、かつ SELECT とも同じですが org.hibernate.eg.FOOorg.hibernate.eg.Foo とは違い、かつ foo.barSetfoo.BARSET とも違います。
このマニュアルでは小文字の HQL キーワードを使用します。大文字のキーワードのクエリの方が読みやすいと感じるユーザーもいると思いますが、この方法は Java コード内に埋め込まれたクエリーには適していません。

14.2. from 節

もっとも単純な Hibernate クエリは次の形式です:
from eg.Cat
これは、eg.Cat クラスのインスタンスをすべて返します。auto-import がデフォルトになっているため、クラス名を修飾する必要はありません。例えば、
from Cat
クエリーの別の箇所でCat を参照するには、別名 を割り当てる必要があります。例えば、
from Cat as cat
このクエリでは Cat インスタンスに cat という別名を付けているため、後にこのクエリ内で、この別名を使うことができます。as キーワードはオプションです。つまりこのように書くこともできます:
from Cat cat
直積集合、あるいは「クロス」結合によって多数のクラスが出現することもあります。
from Formula, Parameter
from Formula as form, Parameter as param
これは、ローカル変数の Java のネーミング基準と一致しているため、頭文字に小文字を使ったクエリの別名を付けることはいい習慣です (例:domesticCat)。

14.3. 関連と結合

関連するエンティティあるいは値コレクションの要素にも、join を使って別名を割り当てることが出来ます。例えば、
from Cat as cat
    inner join cat.mate as mate
    left outer join cat.kittens as kitten
from Cat as cat left join cat.mate.kittens as kittens
from Formula form full join form.parameter param
サポートしている結合のタイプは ANSI SQL から採っています:
  • inner join
  • left outer join
  • right outer join
  • full join (たいていの場合使いづらい)
inner joinleft outer joinright outer join には省略形を使うこともできます。
from Cat as cat
    join cat.mate as mate
    left join cat.kittens as kitten
HQL の with キーワードを使うと、結合条件を付け加えることができます。
from Cat as cat
    left join cat.kittens as kitten
        with kitten.bodyWeight > 10.0
「フェッチ」結合は関連や値のコレクションを親オブジェクトと一緒に1度の select で初期化します。これは特にコレクションの場合に有用です。また、効果的に関連とコレクションに対し、マッピングファイルの外部結合や遅延宣言をオーバーライドします。詳細は 「フェッチ戦略」 を参照してください。
from Cat as cat
    inner join fetch cat.mate
    left join fetch cat.kittens
関連オブジェクトを where 節 (または他のどんな節でも) で使うべきではないため、フェッチ結合には通常別名を割り当てる必要がありません。また関連オブジェクトはクエリ結果として直接返されません。代わりに親オブジェクトからアクセスできます。別名が必要となる唯一の理由として、さらにコレクションを再帰的に結合フェッチする場合というのが挙げられます:
from Cat as cat
    inner join fetch cat.mate
    left join fetch cat.kittens child
    left join fetch child.kittens

重要

fetch 構文は iterate() を使ったクエリ呼び出しで使用できません(一方で scroll() は使用できます)。また、これらの操作は結果の行に基づいているため、 fetchsetMaxResults()setFirstResult() と一緒に使用する必要があります。通常 即時コレクションフェッチをすると重複が出てしまうため、期待するような行数にはならないのです。そしてまた fetch は、アドホックな with 条件を一緒に使うこともできません。一つのクエリで複数のコレクションを結合フェッチすることにより直積集合を作成できるので、この場合注意してくださいuまた、複数のコレクションに対する結合フェッチは bag マッピングに対して予期せぬ結果をもたらすことがあるので、この場合のクエリの作成には注意してください。最後に 全外部結合によるフェッチ右外部結合によるフェッチ は意味がない点に注意してください。
プロパティレベルの遅延フェッチを使う場合(バイトコード処理をする場合)、fetch all properties を使うことで Hibernate に遅延プロパティを速やかに最初のクエリでフェッチさせることができます。
from Document fetch all properties order by name
from Document doc fetch all properties where lower(doc.name) like '%cats%'

14.4. 結合構文の形式

HQL は2つの関連結合形式をサポートします: 暗黙的明示的
これまでのセクションでお見せした使い方はすべて 明示的な 形式で、 from 節で明示的に join キーワードを使っています。この形式をおすすめします。
暗黙的 フォームは、 join キーワードを使いません。代わりに、参照する関連にドット表記を使います。 暗黙的 結合は、さまざまな HQL に出てきます。 暗黙的 結合の結果は、 SQL ステートメントの内部結合結果です。
from Cat as cat where cat.mate.name like '%s%'

14.5. 識別子プロパティの参照

エンティティの識別子プロパティは、2つの方法で参照されます:
  • エンティティが id と名付けられた非識別子プロパティを定義しない場合、特別なプロパティ (小文字) id は、 エンティティの識別子プロパティを参照するのに使用されることがあります。
  • エンティティが指定された識別子プロパティを定義したら、そのプロパティ名を使用できます。
複合識別子プロパティへの参照は同じ命名ルールに従います。エンティティが id と名付けられた非識別子プロパティを持つ場合、複合識別子プロパティはその定義された名前で参照することができます。そうでないと、特別な id プロパティは、識別子プロパティを参照するのに使用されます。

重要

これは、バージョン 3.2.2 から大幅に変更されている点に注意してください。前バージョンでは、 id は、その実際の名前に関係なく 常に 識別子プロパティを参照していました。その結果、 id と名付けられた非識別子プロパティは、Hibernate クエリで決して参照されませんでした。

14.6. Select 節

select 節は、どのオブジェクトと属性をクエリ結果に返すかを選択します。以下を考えて見ましょう。
select mate
from Cat as cat
    inner join cat.mate as mate
クエリは他の Catmate を選択します。実際には次のように、より簡潔に表現できます:
select cat.mate from Cat cat
クエリはコンポーネント型のプロパティを含む、あらゆる値型のプロパティも返せます:
select cat.name from DomesticCat cat
where cat.name like 'fri%'
select cust.name.firstName from Customer as cust
クエリは複数のオブジェクトと (または) プロパティを Object[] 型の配列として返せます:
select mother, offspr, mate.name
from DomesticCat as mother
    inner join mother.mate as mate
    left outer join mother.kittens as offspr
もしくは List として:
select new list(mother, offspr, mate.name)
from DomesticCat as mother
    inner join mother.mate as mate
    left outer join mother.kittens as offspr
あるいは Family クラスが適切なコンストラクタを持っているとするならば、実際の型安全なjava オブジェクトとして:
select new Family(mother, mate, offspr)
from DomesticCat as mother
    join mother.mate as mate
    left join mother.kittens as offspr
選択した表現に as を使って別名をつけることもできます:
select max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n
from Cat cat
select new map と一緒に使うときに最も役立ちます:
select new map( max(bodyWeight) as max, min(bodyWeight) as min, count(*) as n )
from Cat cat
このクエリは別名から select した値へ Map を返します。

14.7. 集約関数

HQL のクエリはプロパティの集約関数の結果も返せます:
select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat)
from Cat cat
サポートしている集約関数は以下のものです:
  • avg(...), sum(...), min(...), max(...)
  • count(*)
  • count(...), count(distinct ...), count(all...)
select 節において演算操作、連結と承認された SQL 関数を使うことができます:
select cat.weight + sum(kitten.weight)
from Cat cat
    join cat.kittens kitten
group by cat.id, cat.weight
select firstName||' '||initial||' '||upper(lastName) from Person
SQL と同じ意味を持つ distinctall キーワードを使うことができます。
select distinct cat.name from Cat cat

select count(distinct cat.name), count(cat) from Cat cat

14.8. ポリモーフィズムを使ったクエリ

次のようなクエリ:
from Cat as cat
Cat インスタンスだけではなく、DomesticCat のようなサブクラスも返されます。Hibernate クエリは どんな Java クラスやインターフェースも from 節に入れることができます。クエリはそのクラスを拡張した、もしくはインターフェースを実装した全ての永続クラスを返します。次のクエリは永続オブジェクトをすべて返します:
from java.lang.Object o
Named インターフェースは様々な永続クラスによって実装されます。:
from Named n, Named m where n.name = m.name
最後の2つのクエリは、2つ以上の SQL SELECT を必要としています。このことは order by 節が結果セット全体を正確には整列しないことを意味します。さらにそれは、 Query.scroll() を使用してこれらのクエリを呼ぶことができないことを意味します。

14.9. where 節

where 節は返されるインスタンスのリストを絞ることができます。もし別名がない場合、名前でプロパティを参照することができます。
from Cat where name='Fritz'
別名がある場合、修飾名を使ってください:
from Cat as cat where cat.name='Fritz'
名前が 'Fritz' という Cat のインスタンスを返します。
以下のクエリ:
select foo
from Foo foo, Bar bar
where foo.startDate = bar.date
FoostartDate プロパティと等しい date プロパティを持った bar インスタンスが存在する、すべての Foo インスタンスを返します。複合パスの表現は where 節を非常に強力にします。以下を考えてみましょう:
from Cat cat where cat.mate.name is not null
このクエリはテーブル(内部)結合を持つ SQL クエリに変換されます。例:
from Foo foo
where foo.bar.baz.customer.address.city is not null
上のクエリを記述したらクエリ内に4つのテーブル結合を必要とする SQL に変換されます。
= 演算子は以下のように、プロパティだけでなくインスタンスを比較するためにも使われます:
from Cat cat, Cat rival where cat.mate = rival.mate
select cat, mate
from Cat cat, Cat mate
where cat.mate = mate
id (小文字) は特別なプロパティであり、オブジェクトの一意の識別子を参照するために使用できます。詳細については 「識別子プロパティの参照」 を参照ください。
from Cat as cat where cat.id = 123

from Cat as cat where cat.mate.id = 69
2番目のクエリは効率的で、テーブル結合が必要ありません。
また複合識別子のプロパティも使用できます。ここで PersoncountrymedicareNumber からなる複合識別子を持つと仮定します。
from bank.Person person
where person.id.country = 'AU'
    and person.id.medicareNumber = 123456
from bank.Account account
where account.owner.id.country = 'AU'
    and account.owner.id.medicareNumber = 123456
繰り返しますが、2番目のクエリにはテーブル結合が必要ありません.
識別子のプロパティ参照に関するさらなる情報については、「識別子プロパティの参照」 を参照してください。
class は特別なプロパティであり、ポリモーフィックな永続化におけるインスタンスの 弁別子値にアクセスします。where 節に埋め込まれた Java のクラス名はその弁別子値に変換されます。
from Cat cat where cat.class = DomesticCat
またコンポーネントや複合ユーザー型、又はそのコンポーネントのプロパティも使用できます。詳細については、「コンポーネント」 を参照下さい。
"any" 型は特別なプロパティである idclass を持ち、以下の方法で結合を表現することを可能にします (AuditLog.item<any> でマッピングされたプロパティの場合)。
from AuditLog log, Payment payment
where log.item.class = 'Payment' and log.item.id = payment.id
log.item.classpayment.class が上記のクエリで全く異なるデータベースカラムの値を参照します。

14.10. Expressions 式

where 節で使用する表現には以下が含まれます:
  • 算術演算子:+, -, *, /
  • 2項比較演算子:=, >=, <=, <>, !=, like
  • 論理演算子 and, or, not
  • グループ分けを表す括弧 ( )
  • in, not in, between, is null, is not null, is empty, is not empty, member of and not member of
  • "シンプル"な case case ... when ... then ... else ... end、 "探索的"な case case when ... then ... else ... end
  • ストリングの連結 ...||... または concat(...,...)
  • current_date()current_time()current_timestamp()
  • second(...)minute(...)hour(...)day(...)month(...)year(...)
  • EJB-QL 3.0 で定義されている関数や演算子: substring(), trim(), lower(), upper(), length(), locate(), abs(), sqrt(), bit_length(), mod()
  • coalesce()nullif()
  • 数字や時間の値を String にコンバートする str()
  • 2番目の引数が Hibernate 型の名前である cast(... as ...)extract(... from ...)。ただし使用するデータベースが ANSI cast()extract() をサポートする場合に限ります。
  • 結合したインデックス付きのコレクションの別名に適用される HQL の index() 関数。
  • コレクション値のパス表現を取る HQL 関数:size(), minelement(), maxelement(), minindex(), maxindex()some, all, exists, any, in を使って修飾することができる特別な elements()indices 関数と一緒に使います。
  • sign()trunc()rtrim()sin() など、データベース対応のSQL スカラ関数。
  • JDBC スタイルの位置パラメータ ?
  • 名前付きパラメータ: :name, :start_date, :x1
  • SQL リテラル: 'foo'696.66E+2'1970-01-01 10:00:01.0'
  • Java の public static final 定数: eg.Color.TABBY
inbetween は以下のように使用できます:
from DomesticCat cat where cat.name between 'A' and 'B'
from DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )
また、否定形で以下のように記述することもできます。
from DomesticCat cat where cat.name not between 'A' and 'B'
from DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )
同様に is nullis not null は null 値をテストするために使用できます。
Hibernate 設定で HQL query substitutions を宣言すれば、boolean 値を式の中で簡単に使用できます:
<property name="hibernate.query.substitutions">true 1, false 0</property>
こうすることで下記の HQL を SQL に変換するときに truefalse キーワードは 10 に置き換えられます:
from Cat cat where cat.alive = true
特別なプロパティ size、または特別な関数 size() を使ってコレクションのサイズをテストできます。
from Cat cat where cat.kittens.size > 0
from Cat cat where size(cat.kittens) > 0
インデックス付きのコレクションでは、minindexmaxindex 関数を使って、インデックスの最小値と最大値を参照できます。同様に、 minelementmaxelement 関数を使って、基本型のコレクションの最小要素と最大要素を参照できます。
from Calendar cal where maxelement(cal.holidays) > current_date
from Order order where maxindex(order.items) > 100
from Order order where minelement(order.items) > 10000
コレクションの要素やインデックスのセット(elementsindices 関数)、または副問い合わせの結果が受け取れるときは、SQL 関数 any, some, all, exists, in がサポートされます(以下参照)。
select mother from Cat as mother, Cat as kit
where kit in elements(foo.kittens)
select p from NameList list, Person p
where p.name = some elements(list.names)
from Cat cat where exists elements(cat.kittens)
from Player p where 3 > all elements(p.scores)
from Show show where 'fizard' in indices(show.acts)
sizeelementsindicesminindexmaxindexminelementmaxelement は Hibernate3 の where 節だけで利用可能であることに注意してください。
インデックス付きのコレクション(arrays, lists, maps)の要素は、where節内でのみインデックスで参照できます:
from Order order where order.items[0].id = 1234
select person from Person person, Calendar calendar
where calendar.holidays['national day'] = person.birthDay
    and person.nationality.calendar = calendar
select item from Item item, Order order
where order.items[ order.deliveredItemIndices[0] ] = item and order.id = 11
select item from Item item, Order order
where order.items[ maxindex(order.items) ] = item and order.id = 11
[] 内部の式は、算術式の場合もあります。
select item from Item item, Order order
where order.items[ size(order.items) - 1 ] = item
HQL は一対多関連や値のコレクションの要素に対して、組み込みの index() 関数も用意しています。
select item, index(item) from Order order
    join order.items item
where index(item) < 5
ベースとなるデータベースがサポートしているスカラ SQL 関数が使用できます:
from DomesticCat cat where upper(cat.name) like 'FRI%'
下のクエリがSQL ではどれだけ長く、読みづらくなるか考えてください:
select cust
from Product prod,
    Store store
    inner join store.customers cust
where prod.name = 'widget'
    and store.location.name in ( 'Melbourne', 'Sydney' )
    and prod = all elements(cust.currentOrder.lineItems)
ヒント: 例えばこのように出来ます。
SELECT cust.name, cust.address, cust.phone, cust.id, cust.current_order
FROM customers cust,
    stores store,
    locations loc,
    store_customers sc,
    product prod
WHERE prod.name = 'widget'
    AND store.loc_id = loc.id
    AND loc.name IN ( 'Melbourne', 'Sydney' )
    AND sc.store_id = store.id
    AND sc.cust_id = cust.id
    AND prod.id = ALL(
        SELECT item.prod_id
        FROM line_items item, orders o
        WHERE item.order_id = o.id
            AND cust.current_order = o.id
    )

14.11. order by 節

クエリが返す list は、返されるクラスやコンポーネントのプロパティによって並べ替えることができます。
from DomesticCat cat
order by cat.name asc, cat.weight desc, cat.birthdate
オプションの ascdesc はそれぞれ昇順か降順の整列を示します。

14.12. group by 節

集約値を返すクエリは、返されるクラスやコンポーネントのプロパティによってグループ化できます:
select cat.color, sum(cat.weight), count(cat)
from Cat cat
group by cat.color
select foo.id, avg(name), max(name)
from Foo foo join foo.names name
group by foo.id
having 節も使えます。
select cat.color, sum(cat.weight), count(cat)
from Cat cat
group by cat.color
having cat.color in (eg.Color.TABBY, eg.Color.BLACK)
基盤のデータベースがサポートしている場合、 havingorder by 節で SQL 関数と集約関数が使えます(例えば MySQL にはありません)。
select cat
from Cat cat
    join cat.kittens kitten
group by cat.id, cat.name, cat.other, cat.properties
having avg(kitten.weight) > 100
order by count(kitten) asc, sum(kitten.weight) desc
group by 節や order by 節に算術式を含むことができません。また、Hibernate は今のところグループエンティティを拡張しないため、cat の全てのプロパティが非集合体の場合、group by cat を書くことはできません。全ての非集合体のプロパティを明示的にリストする必要があります。

14.13. 副問い合わせ

サブセレクトをサポートするデータベースのため、 Hibernate は副問い合わせをサポートしています。副問い合わせは括弧で囲まなければなりません( SQL の集約関数呼び出しによる事が多いです)。関連副問い合わせ (外部クエリ中の別名を参照する副問い合わせのこと) さえ許可されます。
from Cat as fatcat
where fatcat.weight > (
    select avg(cat.weight) from DomesticCat cat
)
from DomesticCat as cat
where cat.name = some (
    select name.nickName from Name as name
)
from Cat as cat
where not exists (
    from Cat as mate where mate.mate = cat
)
from DomesticCat as cat
where cat.name not in (
    select name.nickName from Name as name
)
select cat.id, (select max(kit.weight) from cat.kitten kit)
from Cat as cat
HQL 副問い合わせは、select または where 節だけで使用可能な点に注意してください。
サブクエリは row value constructor 構文も使用できる点に注意してください。詳細については 「行値コンストラクタ構文」を参照してください。

14.14. HQL の例

Hibernate クエリは非常に強力で複雑になりえます。実際、クエリ言語の威力は Hibernate の主要なセールスポイントの一つです。以下のクエリ例は、最近のプロジェクトで使用したクエリと非常によく似ています。ほとんどのクエリはこれらの例より簡単に記述できることに注意してください。
以下のクエリは、特定の顧客に関する未払いの注文すべてに対し、注文 ID 、商品の数、最小の合計値、注文の合計値を返します。結果は合計値別に整列されます。価格を決定する際、現在のカタログを使います。結果として返される SQL クエリは ORDERORDER_LINEPRODUCTCATALOG および PRICE テーブルに対し4つの内部結合と (関連しない) 副問い合わせを持ちます。
select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog.effectiveDate < sysdate
    and catalog.effectiveDate >= all (
        select cat.effectiveDate
        from Catalog as cat
        where cat.effectiveDate < sysdate
    )
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc
何て巨大なクエリなのでしょう。普段私は副問い合わせをあまり使いません。したがって私のクエリは実際には以下のようになります。:
select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog = :currentCatalog
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc
次のクエリは各ステータスの支払い数を数えます。ただしすべての支払いが現在の利用者による最新のステータス変更である AWAITING_APPROVAL である場合を除きます。このクエリは2つの内部結合と PAYMENT, PAYMENT_STATUS および PAYMENT_STATUS_CHANGE テーブルに対する関連副問い合わせを備えた SQL クエリに変換されます。
select count(payment), status.name
from Payment as payment
    join payment.currentStatus as status
    join payment.statusChanges as statusChange
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or (
        statusChange.timeStamp = (
            select max(change.timeStamp)
            from PaymentStatusChange change
            where change.payment = payment
        )
        and statusChange.user <> :currentUser
    )
group by status.name, status.sortOrder
order by status.sortOrder
set の代わりに list として statusChanges コレクションをマッピングすると、はるかに簡単にクエリを記述できるでしょう。
select count(payment), status.name
from Payment as payment
    join payment.currentStatus as status
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser
group by status.name, status.sortOrder
order by status.sortOrder
次のクエリは現在のユーザーが所属する組織に対するアカウントおよび未払いの支払いをすべて返す MS SQL Server の isNull() 関数を使用しています。このクエリは3つの内部結合と1つの外部結合、そして ACCOUNTPAYMENTPAYMENT_STATUSACCOUNT_TYPEORGANIZATION および ORG_USER テーブルに対する副問い合わせ持った SQL に変換されます。
select account, payment
from Account as account
    left outer join account.payments as payment
where :currentUser in elements(account.holder.users)
    and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID)
order by account.type.sortOrder, account.accountNumber, payment.dueDate
いくつかのデータベースについては、 (関連させられた) 副問い合わせの使用を避ける必要があるでしょう。
select account, payment
from Account as account
    join account.holder.users as user
    left outer join account.payments as payment
where :currentUser = user
    and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID)
order by account.type.sortOrder, account.accountNumber, payment.dueDate

14.15. 大量の UPDATE と DELETE

HQL は現在 updatedeleteinsert ... select ... 文をサポートしています。詳細については 「DML スタイルの操作」 を参照ください。

14.16. Tips & Tricks

実際に結果を返さなくてもクエリの結果数を数えることができます:
( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue()
コレクションのサイズにより結果を並べ替えるためには以下のクエリを使用します:
select usr.id, usr.name
from User as usr
    left join usr.messages as msg
group by usr.id, usr.name
order by count(msg)
使用しているデータベースがサブセレクトをサポートする場合、クエリの where 節でサイズによる選択条件を設定できます:
from User usr where size(usr.messages) >= 1
使用しているデータベースが副問い合わせ(Subselect)に対応していない場合は、次のクエリを使用してください:
select usr.id, usr.name
from User usr
    join usr.messages msg
group by usr.id, usr.name
having count(msg) >= 1
この解決法は、内部結合をしているせいでメッセージの件数がゼロの User を返すことができないため、以下の形式も役立ちます:
select usr.id, usr.name
from User as usr
    left join usr.messages as msg
group by usr.id, usr.name
having count(msg) = 0
JavaBean のプロパティは、名前付きのクエリパラメータに結びつけることが出来ます:
Query q = s.createQuery("from foo Foo as foo where foo.name=:name and foo.size=:size");
q.setProperties(fooBean); // fooBean has getName() and getSize()
List foos = q.list();
コレクションはフィルタ付き Query インターフェースを使用することでページをつけることができます:
Query q = s.createFilter( collection, "" ); // the trivial filter
q.setMaxResults(PAGE_SIZE);
q.setFirstResult(PAGE_SIZE * pageNumber);
List page = q.list();
コレクション要素はクエリフィルタを使って、並べ替えやグループ分けが出来ます:
Collection orderedCollection = s.createFilter( collection, "order by this.amount" ).list();
  Collection counts = s.createFilter( collection, "select this.type, count(this) group by this.type" ).list();
コレクションを初期化せずにコレクションのサイズを得ることができます:
( (Integer) session.createQuery("select count(*) from ....").iterate().next() ).intValue();

14.17. コンポーネント

同様に、HQL クエリで使用しているシンプルな値型にコンポーネントを使用できます。以下のように select 節の中に現われます:
select p.name from Person p
select p.name.first from Person p
人名のプロパティがコンポーネントの場所。コンポーネントは、 where 節でも使用可能です:
from Person p where p.name = :name
from Person p where p.name.first = :firstName
コンポーネントは order by 節でも使用可能です:
from Person p order by p.name
from Person p order by p.name.first
さらに、コンポーネントの一般的な用途は、「行値コンストラクタ構文」にあります。

14.18. 行値コンストラクタ構文

基盤のデータベースが ANSI SQL row value constructor 構文 (tuple 構文とよばれることもあります) をサポートしていないとしても、HQL はその使用をサポートしています。ここでは、一般的にコンポーネントと連繋するマルチバリュー比較を指します。名前コンポーネントを定義する Person エンティティを考えましょう:
from Person p where p.name.first='John' and p.name.last='Jingleheimer-Schmidt'
それは少々詳細になりますが、有効な構文です。row value constructor 構文を使用することで、この構文を簡潔化できます:
from Person p where p.name=('John', 'Jingleheimer-Schmidt')
それを select 節で指定するのも効果的です。
select p.name from Person p
複数の値と比較する必要のあるサブクエリを利用する場合、row value constructor 構文の使用も利点がある場合があります。
from Cat as cat
where not ( cat.name, cat.color ) in (
    select cat.name, cat.color from DomesticCat cat
)
この構文を使用するかを決定するときに考慮しなければならないことは、クエリがメタデータ内のコンポーネントのサブプロパティの順番に依存していることです。

第15章 Criteria クエリ

Hibernate には、直感的で拡張可能な criteria クエリ API が用意されています。

15.1. Criteria インスタンスの作成

org.hibernate.Criteria インターフェースは特定の永続性クラスに対するクエリを表現します。 SessionCriteria インスタンスのファクトリです。
Criteria crit = sess.createCriteria(Cat.class);
crit.setMaxResults(50);
List cats = crit.list();

15.2. リザルトセットの絞込み

org.hibernate.criterion.Criterion インターフェースのインスタンスは、個別のクエリクライテリオン(問い合わせの判定基準)を表します。 org.hibernate.criterion.Restrictions クラスは、ある組み込みの Criterion 型を取得するためのファクトリメソッドを持っています。
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.like("name", "Fritz%") )
    .add( Restrictions.between("weight", minWeight, maxWeight) )
    .list();
Restriction(制限)は論理的にグループ化できます。
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.like("name", "Fritz%") )
    .add( Restrictions.or(
        Restrictions.eq( "age", new Integer(0) ),
        Restrictions.isNull("age")
    ) )
    .list();
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) )
    .add( Restrictions.disjunction()
        .add( Restrictions.isNull("age") )
        .add( Restrictions.eq("age", new Integer(0) ) )
        .add( Restrictions.eq("age", new Integer(1) ) )
        .add( Restrictions.eq("age", new Integer(2) ) )
    )
    .list();
様々なCriterion 型(Restrictions のサブクラス)が同梱されていますが、最も有用なものの1つとして SQL を直接指定できます。
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.sqlRestriction("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) )
    .list();
{alias} というプレースホルダは、問い合わせを受けたエンティティの行の別名によって置き換えられます。
また Property インスタンスから条件を取得できます。Property.forName() を呼び出して、 Property インスタンスを作成できます。
Property age = Property.forName("age");
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.disjunction()
        .add( age.isNull() )
        .add( age.eq( new Integer(0) ) )
        .add( age.eq( new Integer(1) ) )
        .add( age.eq( new Integer(2) ) )
    )
    .add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) )
    .list();

15.3. 結果の整列

org.hibernate.criterion.Order を使って結果を並べることができます。
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.like("name", "F%") )
    .addOrder( Order.asc("name") )
    .addOrder( Order.desc("age") )
    .setMaxResults(50)
    .list();
List cats = sess.createCriteria(Cat.class)
    .add( Property.forName("name").like("F%") )
    .addOrder( Property.forName("name").asc() )
    .addOrder( Property.forName("age").desc() )
    .setMaxResults(50)
    .list();

15.4. 関連

createCriteria()を利用し関連を遷移することで、関連エンティティの制約を指定できます:
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.like("name", "F%") )
    .createCriteria("kittens")
        .add( Restrictions.like("name", "F%") )
    .list();
2番目の createCriteria() は、kittens コレクションの要素を参照する新しい Criteria インスタンスを返します。
特定の状況において有用な方法もほかにあります:
List cats = sess.createCriteria(Cat.class)
    .createAlias("kittens", "kt")
    .createAlias("mate", "mt")
    .add( Restrictions.eqProperty("kt.name", "mt.name") )
    .list();
createAlias() は新しい Criteria インスタンスを作成しません。)
前の2つのクエリが返す Cat インスタンスにより保持される kittens コレクションは、criteria によって事前にフィルタリング されません。criteria と一致する kitten を取得したい場合、 ResultTransformer を使わなければなりません。
List cats = sess.createCriteria(Cat.class)
    .createCriteria("kittens", "kt")
        .add( Restrictions.eq("name", "F%") )
    .setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP)
    .list();
Iterator iter = cats.iterator();
while ( iter.hasNext() ) {
    Map map = (Map) iter.next();
    Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS);
    Cat kitten = (Cat) map.get("kt");
}

15.5. 関連の動的フェッチ

setFetchMode() を使い、実行時に関連のフェッチセマンティクスを指定できます。
List cats = sess.createCriteria(Cat.class)
    .add( Restrictions.like("name", "Fritz%") )
    .setFetchMode("mate", FetchMode.EAGER)
    .setFetchMode("kittens", FetchMode.EAGER)
    .list();
このクエリは外部結合により matekittens の両方をフェッチします。詳細については 「フェッチ戦略」 を参照してください。

15.6. クエリの例

org.hibernate.criterion.Example クラスは、与えられたインスタンスからクエリクライテリオンを構築できます。
Cat cat = new Cat();
cat.setSex('F');
cat.setColor(Color.BLACK);
List results = session.createCriteria(Cat.class)
    .add( Example.create(cat) )
    .list();
バージョンプロパティ、識別子、関連は無視されます。デフォルトでは null 値のプロパティは除外されます。
どのように Example を適用するか調整することができます。
Example example = Example.create(cat)
    .excludeZeroes()           //exclude zero valued properties
    .excludeProperty("color")  //exclude the property named "color"
    .ignoreCase()              //perform case insensitive string comparisons
    .enableLike();             //use like for string comparisons
List results = session.createCriteria(Cat.class)
    .add(example)
    .list();
関連オブジェクトに criteria を指定するために、 example を使うことも可能です。
List results = session.createCriteria(Cat.class)
    .add( Example.create(cat) )
    .createCriteria("mate")
        .add( Example.create( cat.getMate() ) )
    .list();

15.7. 射影、集約、グループ化

org.hibernate.criterion.Projections クラスは Projection インスタンスのファクトリです。 setProjection() を呼び出すことで、クエリに射影を適用します。
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.rowCount() )
    .add( Restrictions.eq("color", Color.BLACK) )
    .list();
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.projectionList()
        .add( Projections.rowCount() )
        .add( Projections.avg("weight") )
        .add( Projections.max("weight") )
        .add( Projections.groupProperty("color") )
    )
    .list();
criteria クエリに「group by」を明示する必要はありません。ある種の Projection 型は グループ化射影 として定義され、 SQL の group by 節にも現れます。
射影に別名を付けることができるため、射影される値は restriction や ordering 内から参照できます。以下に別名をつける方法を2つ示します:
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) )
    .addOrder( Order.asc("colr") )
    .list();
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.groupProperty("color").as("colr") )
    .addOrder( Order.asc("colr") )
    .list();
alias()as() メソッドは、 Projection インスタンスを別の名前の Projection インスタンスでラップするだけです。ショートカットとして、射影を射影リストに追加する際に、別名をつけられます:
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.projectionList()
        .add( Projections.rowCount(), "catCountByColor" )
        .add( Projections.avg("weight"), "avgWeight" )
        .add( Projections.max("weight"), "maxWeight" )
        .add( Projections.groupProperty("color"), "color" )
    )
    .addOrder( Order.desc("catCountByColor") )
    .addOrder( Order.desc("avgWeight") )
    .list();
List results = session.createCriteria(Domestic.class, "cat")
    .createAlias("kittens", "kit")
    .setProjection( Projections.projectionList()
        .add( Projections.property("cat.name"), "catName" )
        .add( Projections.property("kit.name"), "kitName" )
    )
    .addOrder( Order.asc("catName") )
    .addOrder( Order.asc("kitName") )
    .list();
射影の式に Property.forName() も使用できます:
List results = session.createCriteria(Cat.class)
    .setProjection( Property.forName("name") )
    .add( Property.forName("color").eq(Color.BLACK) )
    .list();
List results = session.createCriteria(Cat.class)
    .setProjection( Projections.projectionList()
        .add( Projections.rowCount() )
        .add( Property.forName("weight").avg().as("avgWeight") )
        .add( Property.forName("weight").max().as("maxWeight") )
        .add( Property.forName("color").group().as("color" )
    ) )
    .addOrder( Order.desc("catCountByColor") )
    .addOrder( Order.desc("avgWeight") )
    .list();

15.8. クエリおよびサブクエリの分離

DetachedCriteria クラスにより、セッションスコープ外にクエリを作成でき、その後、任意の Session を使って、実行できます。
DetachedCriteria query = DetachedCriteria.forClass(Cat.class)
    .add( Property.forName("sex").eq('F') );
    
Session session = ....;
Transaction txn = session.beginTransaction();
List results = query.getExecutableCriteria(session).setMaxResults(100).list();
txn.commit();
session.close();
DetachedCriteria は、サブクエリを表現するためにも使えます。サブクエリを伴う Criterion インスタンスは、 Subqueries もしくは Property から得ることができます。
DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class)
    .setProjection( Property.forName("weight").avg() );
session.createCriteria(Cat.class)
    .add( Property.forName("weight").gt(avgWeight) )
    .list();
DetachedCriteria weights = DetachedCriteria.forClass(Cat.class)
    .setProjection( Property.forName("weight") );
session.createCriteria(Cat.class)
    .add( Subqueries.geAll("weight", weights) )
    .list();
相互関係のあるサブクエリも可能です:
DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2")
    .setProjection( Property.forName("weight").avg() )
    .add( Property.forName("cat2.sex").eqProperty("cat.sex") );
session.createCriteria(Cat.class, "cat")
    .add( Property.forName("weight").gt(avgWeightForSex) )
    .list();

15.9. 自然識別子によるクエリ

criteria クエリなど多くのクエリにとって、クエリキャッシュは効率があまりよくありません。なぜなら、クエリキャッシュが過剰なほど頻繁に無効になるためです。しかしながら、キャッシュを無効にするアルゴリズムを最適化できる特別なクエリの種類が1つあります。それは、更新されない自然キーによる検索です。いくつかのアプリケーションでは、この種類のクエリが頻繁に現れます。このユースケースに対し、criteria API は特別な対策を提供します。
最初に、<natural-id> を使って、エンティティの自然キーをマップしてください。そして、二次キャッシュを有効にします。
<class name="User">
    <cache usage="read-write"/>
    <id name="id">
        <generator class="increment"/>
    </id>
    <natural-id>
        <property name="name"/>
        <property name="org"/>
    </natural-id>
    <property name="password"/>
</class>
この機能は、可変の 自然キーを持つエンティティと使用するために設計されたいません。
Hiberbate クエリキャッシュを有効にすると、Restrictions.naturalId() により、より効率的なキャッシュアルゴリズムを使用できます。
session.createCriteria(User.class)
    .add( Restrictions.naturalId()
        .set("name", "gavin")
        .set("org", "hb") 
    ).setCacheable(true)
    .uniqueResult();

第16章 ネイティブ SQL

データベースのネイティブ SQL 方言を使ってクエリを表現することもできます。クエリヒントや Oracle の CONNECT キーワードのように、データベース独自の機能を利用したいときに使えます。SQL/JDBC ベースのアプリケーションからHibernate への明確な移行パスを提供しています。
Hibernate3 では、ストアドプロシージャなど、生成、更新、削除、読み込み処理のような手書きのSQL を指定できます。

16.1. SQLQueryを使用

ネイティブな SQL クエリの実行は SQLQuery インターフェースを通して制御します。SQLQuery インターフェースは Session.createSQLQuery() を呼び出して取得します。以下の章では、この API を使って問い合わせする方法について説明します。

16.1.1. スカラーのクエリ

最も基本的な SQL クエリはスカラー(値)のリストを得ることです。
sess.createSQLQuery("SELECT * FROM CATS").list();
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").list();
これらはどちらも、 CATS テーブルの各カラムのスカラ値を含む Object 配列(Object[ ])のリストを返します。返すスカラ値の実際の順番と型を推定するために、Hibernate は ResultSetMetadata を使用します。
ResultSetMetadata を使用するオーバーヘッドを避けるため、もしくは単に何が返されるか明確にするため、addScalar() を使えます:
sess.createSQLQuery("SELECT * FROM CATS")
 .addScalar("ID", Hibernate.LONG)
 .addScalar("NAME", Hibernate.STRING)
 .addScalar("BIRTHDATE", Hibernate.DATE);
このクエリで指定されているものを下記に示します:
  • SQL クエリ文字列
  • 返されるカラムと型
これは Object 配列を返しますが、ResultSetMetdata を使用しません。ただし、その代わりに基礎にあるリザルトセットから ID、NAME、BIRTHDATE カラムをそれぞれ Long、String、Short として明示的に取得します。これは3つのカラムを返すのみであることも意味します。たとえ、クエリが * を使用し、列挙した3つより多くのカラムを返せるとしてもです。
スカラーの型情報を省くこともできます。
sess.createSQLQuery("SELECT * FROM CATS")
 .addScalar("ID", Hibernate.LONG)
 .addScalar("NAME")
 .addScalar("BIRTHDATE");
これは本質的に前と同じクエリですが、NAME と BIRTHDATE の型を決めるために ResultSetMetaData を使用します。一方、ID の型は明示的に指定されています。
Dialectの制御で、どのようにResultSetMetaData から返される java.sql.Types を Hibernate の型に マッピングされるかが決まります。特定の型がマッピングされていないか、結果の型が期待したものと異なる場合、 Dialect のregisterHibernateType を呼び出すことでカスタマイズできます。

16.1.2. エンティティのクエリ

ここまでのクエリは、すべてスカラー値を返すものでした。基本的に、リザルトセットから「未加工」の値を返します。以降では、 addEntity() により、ネイティブ SQL クエリからエンティティオブジェクトを取得する方法を示します。
sess.createSQLQuery("SELECT * FROM CATS").addEntity(Cat.class);
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").addEntity(Cat.class);
このクエリで指定されているものを下記に示します:
  • SQL クエリ文字列
  • クエリが返すエンティティと SQL テーブルの別名
Cat が ID 、 NAME 、 BIRTHDATE のカラムを使ってクラスにマッピングされる場合、上記のクエリはどちらも、要素が Cat エンティティであるリストを返します。
エンティティを別のエンティティに 多対一 でマッピングしている場合は、ネイティブクエリを実行する際に、この別のエンティティを返すことも要求します。さもなければ、データベース固有の「column not found(カラムが見つかりません)」エラーが発生します。 * 表記を使用した際は、追加のカラムが自動的に返されますが、次の例のように、 Dog多対一 であることを明示することを私たちは好みます。
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, DOG_ID FROM CATS").addEntity(Cat.class);
これにより cat.getDog() が正しく機能します。

16.1.3. 関連とコレクションの操作

プロキシを初期化するための余分な処理を避けるため、 Dog の中で即時結合できます。これは addJoin() メソッドにより行います。関連もしくはコレクションに結合できます。
sess.createSQLQuery("SELECT c.ID, NAME, BIRTHDATE, DOG_ID, D_ID, D_NAME FROM CATS c, DOGS d WHERE c.DOG_ID = d.D_ID")
 .addEntity("cat", Cat.class)
 .addJoin("dog", "cat.dog");
この例の中で、返される Cat は、データベースへの余分処理なしで、完全に初期化された dog プロパティを持ちます。結合対象のプロパティへのパスを指定できるように、別名(「cat」)を追加したことに注意してください。コレクションの即時結合も同じようにできます。たとえば、 Cat が一対多で Dog を持っていた場合などです。
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, D_ID, D_NAME, CAT_ID FROM CATS c, DOGS d WHERE c.ID = d.CAT_ID")
 .addEntity("cat", Cat.class)
 .addJoin("dog", "cat.dogs");
今の段階では、Hibernate で使えるように SQL クエリの拡張を始めなければ、ネイティブクエリで実現できることも限界に達してしまいます。同じ型のエンティティを複数返す際や、デフォルトの別名や列名で十分ではない場合に、問題が発生する可能性があります。

16.1.4. 複数エンティティの取得

ここまでは、結果のカラム名は、マッピングドキュメントで指定したカラム名と同じであると仮定していました。複数のテーブルが同じカラム名を持つ場合があるため、複数テーブルを結合する SQL クエリで問題となる場合があります。
下記のような(失敗しそうな)クエリでは、カラム別名インジェクション(column alias injection)が必要です:
sess.createSQLQuery("SELECT c.*, m.*  FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID")
 .addEntity("cat", Cat.class)
 .addEntity("mother", Cat.class)
このクエリは、1行ごとに2つの Cat インスタンス、つまりCatとそのmotherを返すように設計されていました。しかし、インスタンスを同じカラム名にマッピングすること、つまり名前が衝突するため、このクエリは失敗します。また、データベースによっては、返されるカラムの別名が "c.ID"、"c.NAME" などの形式であり、マッピングで指定されたカラム("ID" と "NAME")と等しくないため、失敗します。
下記の形式は、カラム名が重複しても大丈夫です:
sess.createSQLQuery("SELECT {cat.*}, {mother.*}  FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID")
 .addEntity("cat", Cat.class)
 .addEntity("mother", Cat.class)
このクエリで指定されているものを下記に示します:
  • SQL クエリ文字列 (Hibernate がカラムの別名を挿入するためのプレースホルダを含む)
  • クエリによって返されるエンティティ
上記で使用している {cat.*} と {mother.*} という表記は、「すべてのプロパティ」を表す省略形です。代わりに、明示的にカラムを列挙することも可能ですが、この場合でも、Hibernate は各プロパティに対応する SQL カラムの別名を挿入します。カラムの別名のためのプレースホルダは、テーブルの別名によって修飾されたプロパティ名です。下記の例では、別のテーブル(cat_log)から マッピングメタデータデータで宣言したテーブルへCatとそのMotherをリトリーブします。where 節の中でも、プロパティの別名を使えます。
String sql = "SELECT ID as {c.id}, NAME as {c.name}, " + 
         "BIRTHDATE as {c.birthDate}, MOTHER_ID as {c.mother}, {mother.*} " +
         "FROM CAT_LOG c, CAT_LOG m WHERE {c.mother} = c.ID";

List loggedCats = sess.createSQLQuery(sql)
        .addEntity("cat", Cat.class)
        .addEntity("mother", Cat.class).list()

16.1.4.1. 別名とプロパティのリファレンス

多くの場合、上記のような別名インジェクションが必要です。複合プロパティ、継承識別子、コレクションなど、より複雑なマッピングと関連するクエリについて、Hibernate は、特定の別名を使用することにより適切な別名を挿入できます。
以下の表で、別名インジェクションを利用できる様々な方法を示しています。注記:下表の別名は一例です。それぞれの別名は一意であり、使用する際にはおそらく異なる名前を持ちます。

表16.1 別名に挿入する名前

説明 構文
単純なプロパティ {[aliasname].[propertyname] A_NAME as {item.name}
複合プロパティ {[aliasname].[componentname].[propertyname]} CURRENCY as {item.amount.currency}, VALUE as {item.amount.value}
エンティティのクラスを識別する値 {[aliasname].class} DISC as {item.class}
エンティティの全プロパティ {[aliasname].*} {item.*}
コレクションのキー {[aliasname].key} ORGID as {coll.key}
コレクションの ID {[aliasname].id} EMPID as {coll.id}
コレクションの要素 {[aliasname].element} XID as {coll.element}
コレクションにある要素プロパティ {[aliasname].element.[propertyname]} NAME as {coll.element.name}
コレクションの要素の全プロパティ {[aliasname].element.*} {coll.element.*}
コレクションの全プロパティ {[aliasname].*} {coll.*}

16.1.5. 管理されていないエンティティの取得

ネイティブ SQL クエリに ResultTransformer を適用でき、管理されていないエンティティを返すことができるようになります。
sess.createSQLQuery("SELECT NAME, BIRTHDATE FROM CATS")
        .setResultTransformer(Transformers.aliasToBean(CatDTO.class))
このクエリで指定されているものを下記に示します:
  • SQL クエリ文字列
  • 結果を変換したもの
上記のクエリは、インスタンス化し、 NAME と BIRTHDATE の値を対応するプロパティもしくはフィールドに挿入した CatDTO のリストを返します。

16.1.6. 継承の制御

継承の一部としてマッピングされたエンティティを問い合わせるネイティブ SQL クエリは、ベースクラスとそのすべてのサブクラスの全プロパティを含まなければなりません。

16.1.7. パラメータ

ネイティブ SQL クエリは、名前付きパラメータや位置パラメータをサポートします:
Query query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like ?").addEntity(Cat.class);
List pusList = query.setString(0, "Pus%").list();
     
query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like :name").addEntity(Cat.class);
List pusList = query.setString("name", "Pus%").list();

16.2. 名前付き SQL クエリ

名前付き SQL クエリはマッピングドキュメントで定義することができ、名前付き HQL クエリと全く同じ方法で呼ぶことができます。この場合、 addEntity() を呼び出す必要は ありません
<sql-query name="persons">
    <return alias="person" class="eg.Person"/>
    SELECT person.NAME AS {person.name},
           person.AGE AS {person.age},
           person.SEX AS {person.sex}
    FROM PERSON person
    WHERE person.NAME LIKE :namePattern
</sql-query>
List people = sess.getNamedQuery("persons")
    .setString("namePattern", namePattern)
    .setMaxResults(50)
    .list();
<return-join> 要素を使って関連を結合し、<load-collection> 要素を使ってコレクションを初期化するクエリを定義します。
<sql-query name="personsWith">
    <return alias="person" class="eg.Person"/>
    <return-join alias="address" property="person.mailingAddress"/>
    SELECT person.NAME AS {person.name},
           person.AGE AS {person.age},
           person.SEX AS {person.sex},
           address.STREET AS {address.street},
           address.CITY AS {address.city},
           address.STATE AS {address.state},
           address.ZIP AS {address.zip}
    FROM PERSON person
    JOIN ADDRESS address
        ON person.ID = address.PERSON_ID AND address.TYPE='MAILING'
    WHERE person.NAME LIKE :namePattern
</sql-query>
名前付き SQL クエリはスカラ値を返すこともできます。 <return-scalar> 要素を使って、列の別名と Hibernate の型を宣言しなければなりません:
<sql-query name="mySqlQuery">
    <return-scalar column="name" type="string"/>
    <return-scalar column="age" type="long"/>
    SELECT p.NAME AS name,
           p.AGE AS age,
    FROM PERSON p WHERE p.NAME LIKE 'Hiber%'
</sql-query>
リザルトセットのマッピング情報を <resultset> 要素に外部化することができます。複数の名前付きクエリか setResultSetMapping() API で再利用できます。
<resultset name="personAddress">
    <return alias="person" class="eg.Person"/>
    <return-join alias="address" property="person.mailingAddress"/>
</resultset>

<sql-query name="personsWith" resultset-ref="personAddress">
    SELECT person.NAME AS {person.name},
           person.AGE AS {person.age},
           person.SEX AS {person.sex},
           address.STREET AS {address.street},
           address.CITY AS {address.city},
           address.STATE AS {address.state},
           address.ZIP AS {address.zip}
    FROM PERSON person
    JOIN ADDRESS address
        ON person.ID = address.PERSON_ID AND address.TYPE='MAILING'
    WHERE person.NAME LIKE :namePattern
</sql-query>
代わりに、hbm ファイル内のリザルトセットのマッピング情報を直接 Java コードで使用できます。
List cats = sess.createSQLQuery(
        "select {cat.*}, {kitten.*} from cats cat, cats kitten where kitten.mother = cat.id"
    )
    .setResultSetMapping("catAndKitten")
    .list();

16.2.1. 列と列の別名を明示的に指定するために return-property を使う

Hibernate が別名を挿入できるようにするには、{} 構文を使う代わりに、<return-property> を使い、どの列の別名を使うのかを Hibernate に対して明示できます。
<sql-query name="mySqlQuery">
    <return alias="person" class="eg.Person">
        <return-property name="name" column="myName"/>
        <return-property name="age" column="myAge"/>
        <return-property name="sex" column="mySex"/>
    </return>
    SELECT person.NAME AS myName,
           person.AGE AS myAge,
           person.SEX AS mySex,
    FROM PERSON person WHERE person.NAME LIKE :name
</sql-query>
<return-property> は複数の列も扱えます。これは、複数列のプロパティをきめ細かく制御できないという、{} 構文の制限を解決します。
<sql-query name="organizationCurrentEmployments">
    <return alias="emp" class="Employment">
        <return-property name="salary">
            <return-column name="VALUE"/>
            <return-column name="CURRENCY"/>
        </return-property>
        <return-property name="endDate" column="myEndDate"/>
    </return>
        SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer},
        STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate},
        REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY
        FROM EMPLOYMENT
        WHERE EMPLOYER = :id AND ENDDATE IS NULL
        ORDER BY STARTDATE ASC
</sql-query>
この例では、挿入のための {} 構文と組み合わせて、 <return-property> を使いました。こうすることで、ユーザーは列とプロパティをどのように参照するかを選べます。
マッピングに discriminator が含まれている場合、 discriminator の列を指定するために、 <return-discriminator> を使わなければなりません。

16.2.2. 問い合わせにストアドプロシージャを使う

Hibernate3 は、ストアドプロシージャや関数経由のクエリに対応しています。以下のドキュメントの多くが両方で同じとなっています。ストアドプロシージャやストアド関数を Hibernate と連携するには1番目の出力パラメータとしてリザルトセットを返さなければなりません。Oracle 9以降のバージョンにおける、このようなストアドプロシージャの例を以下に示します:
CREATE OR REPLACE FUNCTION selectAllEmployments
    RETURN SYS_REFCURSOR
AS
    st_cursor SYS_REFCURSOR;
BEGIN
    OPEN st_cursor FOR
 SELECT EMPLOYEE, EMPLOYER,
 STARTDATE, ENDDATE,
 REGIONCODE, EID, VALUE, CURRENCY
 FROM EMPLOYMENT;
      RETURN  st_cursor;
 END;
Hibernate でこのクエリを使うためには、名前付きクエリでマッピングする必要があります。
<sql-query name="selectAllEmployees_SP" callable="true">
    <return alias="emp" class="Employment">
        <return-property name="employee" column="EMPLOYEE"/>
        <return-property name="employer" column="EMPLOYER"/>
        <return-property name="startDate" column="STARTDATE"/>
        <return-property name="endDate" column="ENDDATE"/>
        <return-property name="regionCode" column="REGIONCODE"/>
        <return-property name="id" column="EID"/>
        <return-property name="salary">
            <return-column name="VALUE"/>
            <return-column name="CURRENCY"/>
        </return-property>
    </return>
    { ? = call selectAllEmployments() }
</sql-query>
今のところ、ストアドプロシージャはスカラとエンティティを返すのみです。 <return-join><load-collection> はサポートされていません。

16.2.2.1. ストアドプロシージャを使う上でのルールと制限

プロシージャや関数のルールに従わない限り、Hibernate でストアドプロシージャや関数を使えません。ルールに準拠していないプロシージャは、 Hibernate で使うことはできません。それでも、これらのプロシージャを使いたい場合、 session.connection() を通じて実行しなければなりません。ストアドプロシージャのセマンティックスと構文は、データベースベンダごとに違うため、これらのルールもデータベースごとに異なります。
setFirstResult()/setMaxResults() を使って、ストアドプロシージャクエリをページすることはできません。
推奨する呼び出し方は、{ ? = call functionName(<parameters>) }{ ? = call procedureName(<parameters>}など、標準である SQL92 に従うことです。ネイティブな呼び出し構文はサポートされていません。
Oracle には下記のルールが適用されます:
  • 関数はリザルトセットを返さなければなりません。プロシージャの第一パラメータはリザルトセットを返す OUT でなければなりません。Oracle 9 と 10 では、SYS_REFCURSOR を使うことでこれを行います。 Oracle では REF CURSOR 型を定義する必要があります。Oracle の文献を参照してください。
Sybase と MS SQL サーバーに適用されるルールを下記に示します:
  • プロシージャはリザルトセットを返さなければなりません。サーバーは複数のリザルトセットと更新カウントを返すことができるため、Hibernate は結果を反復し、リザルトセットである1つ目の結果を戻し値として取ることに注意してください。その他はすべて捨てられます。
  • プロシージャの中で SET NOCOUNT ON を有効にできれば、おそらく効率がよくなるでしょう。しかし、これは必要条件ではありません。

16.3. 作成、更新、削除のためのカスタム SQL

Hibernate3 は作成、更新、削除処理のためのカスタム SQL 文を使用できます。クラスとコレクションの永続化機構は、コンフィグレーション時に生成された文字列 (insertsql、deletesql、updatesql など)のセットをすでに保持しています。これらの文字列より、 <sql-insert><sql-delete><sql-update> というマッピングタグが優先されます:
<class name="Person">
    <id name="id">
        <generator class="increment"/>
    </id>
    <property name="name" not-null="true"/>
    <sql-insert>INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? )</sql-insert>
    <sql-update>UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?</sql-update>
    <sql-delete>DELETE FROM PERSON WHERE ID=?</sql-delete>
</class>
SQL を直接データベースで実行するため、好みの方言を自由に使用できます。データベース独自の SQL を使えば、マッピングの移植性が下がります。
callable 属性をセットすれば、ストアドプロシージャを使用できます:
<class name="Person">
    <id name="id">
        <generator class="increment"/>
    </id>
    <property name="name" not-null="true"/>
    <sql-insert callable="true">{call createPerson (?, ?)}</sql-insert>
    <sql-delete callable="true">{? = call deletePerson (?)}</sql-delete>
    <sql-update callable="true">{? = call updatePerson (?, ?)}</sql-update>
</class>
Hibernate が期待する順序と同じでなければならないため、位置パラメータの順番はとても重要です。
org.hiberante.persister.entity レベルのデバッグログを有効にすることによって、期待される順番を参照できます。このレベルを有効にすることにより、Hibernate は、エンティティの作成、更新、削除などで使用される静的な SQL を出力します。期待される順序を確認する際、マッピングファイルにカスタムSQLを含めないでください。含めてしまうと、Hibernate が生成する静的 SQL をオーバーライドするためです。
ストアドプロシージャは多くの場合、挿入/更新/削除された行数を返す必要があります。実行時に Hibernate が 文の成功をチェックするからです。Hibernate は、 CUD 操作で数値の出力パラメータとして、SQL 文の最初のパラメータをいつも記録します:
CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN VARCHAR2)
    RETURN NUMBER IS
BEGIN

    update PERSON
    set
        NAME = uname,
    where
        ID = uid;

    return SQL%ROWCOUNT;

END updatePerson;

16.4. ロードのためのカスタム SQL

エンティティを読み込むための独自の SQL (もしくは HQL)クエリも宣言できます:
<sql-query name="person">
    <return alias="pers" class="Person" lock-mode="upgrade"/>
    SELECT NAME AS {pers.name}, ID AS {pers.id}
    FROM PERSON
    WHERE ID=?
    FOR UPDATE
</sql-query>
これは、まさに前述した名前付きクエリの宣言です。この名前付きクエリをクラスのマッピングから参照できます:
<class name="Person">
    <id name="id">
        <generator class="increment"/>
    </id>
    <property name="name" not-null="true"/>
    <loader query-ref="person"/>
</class>
これはストアドプロシージャでさえも動作します。
コレクションをロードするためのクエリさえ定義することもできます。
<set name="employments" inverse="true">
    <key/>
    <one-to-many class="Employment"/>
    <loader query-ref="employments"/>
</set>
<sql-query name="employments">
    <load-collection alias="emp" role="Person.employments"/>
    SELECT {emp.*}
    FROM EMPLOYMENT emp
    WHERE EMPLOYER = :id
    ORDER BY STARTDATE ASC, EMPLOYEE ASC
</sql-query>
結合フェッチによりコレクションをロードするエンティティローダーも定義できます:
<sql-query name="person">
    <return alias="pers" class="Person"/>
    <return-join alias="emp" property="pers.employments"/>
    SELECT NAME AS {pers.*}, {emp.*}
    FROM PERSON pers
    LEFT OUTER JOIN EMPLOYMENT emp
        ON pers.ID = emp.PERSON_ID
    WHERE ID=?
</sql-query>

第17章 データのフィルタリング

Hibernate3 では「可視性」ルールに基づきデータ処理の画期的な方法を用意しています。Hibernate filter はグローバルで、名前付きで、パラメータ化されたフィルタです。これは Hibernate セッションごとに有効あるいは無効を切り替えられます。

17.1. Hibernate のフィルタ

Hibernate3 はフィルタ基準をあらかじめ定義し、これらのフィルタをクラスやコレクションレベルに加える機能を加えました。フィルタ基準は制約節を定義ができ、クラスや様々なコレクション要素で利用できる「Where」要素に似ています。しかし、これらのフィルタ条件はパラメータ化できます。その後アプリケーションは、与えられたフィルタを可能にすべきか、そしてそのパラメータ値を何にすべきかを実行時に決定することができます。フィルタはデータベースビューのように使用されますが、アプリケーション内ではパラメータ化されます。
フィルタを使うためにはまず、適切なマッピング要素に定義、追加しなくてはなりません。フィルタを定義するためには、 <hibernate-mapping/> 要素内で <filter-def/> 要素を使用します:
<filter-def name="myFilter">
    <filter-param name="myFilterParam" type="string"/>
</filter-def>
そうしてフィルタはクラスへと結び付けられます:
<class name="myClass" ...>
    ...
    <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
</class>
また、コレクションに対しては次のようになります:
<set ...>
    <filter name="myFilter" condition=":myFilterParam = MY_FILTERED_COLUMN"/>
</set>
また、両方またはそれぞれを複数、 同時に設定することもできます。
Session 上のメソッドは enableFilter(String filterName)getEnabledFilter(String filterName)disableFilter(String filterName) です。デフォルトでは、フィルタは与えられたセッションに対して使用 できませんFilter インスタンスを返り値とする Session.enabledFilter() メソッドを使うことで、フィルタは明示的に使用可能となります。上で定義した単純なフィルタの使用は、このようになります:
session.enableFilter("myFilter").setParameter("myFilterParam", "some-value");
org.hibernate.Filter インターフェースのメソッドは、Hibernate の多くに共通しているメソッド連鎖が可能です。
以下は、有効なレコードデータパターンを持つ一時データを使った完全な例です:
<filter-def name="effectiveDate">
    <filter-param name="asOfDate" type="date"/>
</filter-def>

<class name="Employee" ...>
...
    <many-to-one name="department" column="dept_id" class="Department"/>
    <property name="effectiveStartDate" type="date" column="eff_start_dt"/>
    <property name="effectiveEndDate" type="date" column="eff_end_dt"/>
...
    <!--
        Note that this assumes non-terminal records have an eff_end_dt set to
        a max db date for simplicity-sake
    -->
    <filter name="effectiveDate"
            condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
</class>

<class name="Department" ...>
...
    <set name="employees" lazy="true">
        <key column="dept_id"/>
        <one-to-many class="Employee"/>
        <filter name="effectiveDate"
                condition=":asOfDate BETWEEN eff_start_dt and eff_end_dt"/>
    </set>
</class>
常に現在の有効なレコードが提供されるようにするため、社員データの検索より前にセッション上のフィルタを有効にします:
Session session = ...;
session.enableFilter("effectiveDate").setParameter("asOfDate", new Date());
List results = session.createQuery("from Employee as e where e.salary > :targetSalary")
         .setLong("targetSalary", new Long(1000000))
         .list();
上記の HQL では、給料の制約について結果で明示的に触れましたが、有効になっているフィルタのおかげで、このクエリは給料が100万ドル以上の現役の社員だけを返します。
HQL かロードフェッチで外部結合を持つフィルタを使いたい場合、条件式の方向に注意してください。これは左外部結合のために設定するのが最も安全です。最初にパラメータを配置し、演算子の後カラム名を続けてください。
定義の後、フィルタは、それぞれ独自の条件を持つ複数のエンティティやコレクションに紐付けされます。条件がいつも同じ場合、面倒かもしれません。従って、 <filter-def/> を利用することで、属性または CDATA としてデフォルトの条件を定義することが可能になります:
<filter-def name="myFilter" condition="abc > xyz">...</filter-def>
<filter-def name="myOtherFilter">abc=xyz</filter-def>
このデフォルトの条件は、条件を指定せずに何かに紐付けされる場合いつでも使われます。これは、特定のケースにおいてデフォルトの条件をオーバーライドするフィルターのアタッチメントの一部として、特定の条件を与えることができることを意味します。

第18章 XML マッピング

XML マッピングは Hibernate3.0 では試験的な機能であり、積極的に開発中です。

18.1. XML データでの作業

Hibernate では永続性の POJO を使って作業するのとほぼ同じようなやり方で、永続性の XML データを使って作業できます。解析された XML ツリーは POJO の代わりにオブジェクトレベルで関係データを表わす別の方法であるとみなされています。
Hibernate は XML ツリーを操作するための API として dom4j をサポートしています。データベースから dom4j のツリーを復元するクエリを書くことができ、ツリーに対して行った修正は自動的にデータベースと同期されます。また XML ドキュメントを取得することができ、 dom4j を使ってドキュメントをパースし、 Hibernate の任意の基本操作を使ってデータベースへ書き込むことができます。: つまり、 persist(), saveOrUpdate(), merge(), delete(), replicate() 操作です (マージはまだサポートしていません)。
データのインポート/エクスポート、 JMS によるエンティティデータの外部化や SOAP 、 XSLT ベースのレポートなど、この機能には多くの用途があります。
単一のマッピングは、クラスのプロパティと XML ドキュメントのノードを同時にデータベースへマッピングするために使うことができます。またマッピングするクラスがなければ、XML だけをマッピングするために使うことができます。

18.1.1. XML とクラスのマッピングを同時に指定する

これは POJO と XML を同時にマッピングする例です:
<class name="Account" 
        table="ACCOUNTS" 
        node="account">
        
    <id name="accountId" 
            column="ACCOUNT_ID" 
            node="@id"/>
            
    <many-to-one name="customer" 
            column="CUSTOMER_ID" 
            node="customer/@id" 
            embed-xml="false"/>
            
    <property name="balance" 
            column="BALANCE" 
            node="balance"/>
            
    ...
    
</class>

18.1.2. XML マッピングだけを指定する

これは POJO クラスがないマッピングの例です:
<class entity-name="Account" 
        table="ACCOUNTS" 
        node="account">
        
    <id name="id" 
            column="ACCOUNT_ID" 
            node="@id" 
            type="string"/>
            
    <many-to-one name="customerId" 
            column="CUSTOMER_ID" 
            node="customer/@id" 
            embed-xml="false" 
            entity-name="Customer"/>
            
    <property name="balance" 
            column="BALANCE" 
            node="balance" 
            type="big_decimal"/>
            
    ...
    
</class>
このマッピングにより、dom4j ツリーか、プロパティ名/値の組のグラフ(java の Map)としてデータにアクセスできます。プロパティ名は、 HQL クエリ内で参照できる純粋な論理構造です。

18.2. XML マッピングのメタデータ

様々な Hibernate のマッピング要素は node 属性を受け付けます。これにより XML 属性の名前やプロパティやエンティティデータを保持する要素を指定できます。node 属性のフォーマットは以下の中の1つでなければなりません:
  • "element-name":指定の XML 要素へマッピングします
  • "@attribute-name":指定の XML 属性へマッピングします
  • ".":親要素へマッピングします
  • "element-name/@attribute-name":指定要素の指定属性へマッピングします
コレクションと単一の値の関連に対して、embed-xml 属性がもう1つあります。デフォルトの embed-xml="true" と設定した場合、関連するエンティティ (値型のコレクション) の XML ツリーは、直接関連を所有するエンティティの XML ツリー内に埋め込まれます。そうでなければ、embed-xml="false" と設定した場合、参照される識別子の値だけが多重度1側の関連に対する XML に現れ、コレクションはまったく現れなくなります。
XMLは循環制をうまく扱えないため、あまりに多くの関連に対して embed-xml="true" としないでください。
<class name="Customer" 
        table="CUSTOMER" 
        node="customer">
        
    <id name="id" 
            column="CUST_ID" 
            node="@id"/>
            
    <map name="accounts" 
            node="." 
            embed-xml="true">
        <key column="CUSTOMER_ID" 
                not-null="true"/>
        <map-key column="SHORT_DESC" 
                node="@short-desc" 
                type="string"/>
        <one-to-many entity-name="Account"
                embed-xml="false" 
                node="account"/>
    </map>
    
    <component name="name" 
            node="name">
        <property name="firstName" 
                node="first-name"/>
        <property name="initial" 
                node="initial"/>
        <property name="lastName" 
                node="last-name"/>
    </component>
    
    ...
    
</class>
この例では、実際の account のデータではなく、account id のコレクションを埋め込むことにしました。以下のHQL クエリは:
from Customer c left join fetch c.accounts where c.lastName like :lastName
このようなデータセットを返すでしょう:
<customer id="123456789">
    <account short-desc="Savings">987632567</account>
    <account short-desc="Credit Card">985612323</account>
    <name>
        <first-name>Gavin</first-name>
        <initial>A</initial>
        <last-name>King</last-name>
    </name>
    ...
</customer>
<one-to-many> マッピングで embed-xml="true" と設定した場合、データはこのようになるでしょう。
<customer id="123456789">
    <account id="987632567" short-desc="Savings">
        <customer id="123456789"/>
        <balance>100.29</balance>
    </account>
    <account id="985612323" short-desc="Credit Card">
        <customer id="123456789"/>
        <balance>-2370.34</balance>
    </account>
    <name>
        <first-name>Gavin</first-name>
        <initial>A</initial>
        <last-name>King</last-name>
    </name>
    ...
</customer>

18.3. XML データを扱う

このアプリケーションでXML ドキュメントを再読み込みや更新することも可能です。dom4j のセッションを取得することで実行できます:
Document doc = ....;
       
Session session = factory.openSession();
Session dom4jSession = session.getSession(EntityMode.DOM4J);
Transaction tx = session.beginTransaction();

List results = dom4jSession
    .createQuery("from Customer c left join fetch c.accounts where c.lastName like :lastName")
    .list();
for ( int i=0; i<results.size(); i++ ) {
    //add the customer data to the XML document
    Element customer = (Element) results.get(i);
    doc.add(customer);
}

tx.commit();
session.close();
Session session = factory.openSession();
Session dom4jSession = session.getSession(EntityMode.DOM4J);
Transaction tx = session.beginTransaction();

Element cust = (Element) dom4jSession.get("Customer", customerId);
for ( int i=0; i<results.size(); i++ ) {
    Element customer = (Element) results.get(i);
    //change the customer name in the XML and database
    Element name = customer.element("name");
    name.element("first-name").setText(firstName);
    name.element("initial").setText(initial);
    name.element("last-name").setText(lastName);
}

tx.commit();
session.close();
XML ベースのデータのインポート/エクスポートを実装するために、Hibernate の replicate() 操作をこの機能に結びつけると便利です。

第19章 パフォーマンスの改善

19.1. フェッチ戦略

フェッチ戦略 は、アプリケーションが関連をナビゲートする必要があるときに、Hibernate が関連オブジェクトを復元するために使用する戦略です。フェッチ戦略は O/R マッピングのメタデータに宣言するか、特定の HQL 、 Criteria クエリでオーバーライドできます。
Hibernate3 は次に示すフェッチ戦略を定義しています:
  • 結合フェッチ:Hibernate は OUTER JOIN を使って、関連するインスタンスやコレクションを同じSELECT 内で獲得します。
  • セレクトフェッチ:2回目の SELECT で関連するエンティティやコレクションを獲得します。 lazy="false" で明示的に遅延フェッチを無効にしなければ、この2回目の select は関連にアクセスしたときのみ実行されます。
  • サブセレクトフェッチ:2回目の SELECT で、直前のクエリやフェッチで復元したすべての要素に関連するコレクションを復元します。lazy="false" を指定し、明示的に遅延フェッチを無効にしなければ、この2回目の select は関連にアクセスしたときのみ実行されます。
  • バッチフェッチ:セレクトフェッチのための最適化された戦略 - Hibernate は、主キーや外部キーのリストを指定することによりエンティティのインスタンスやコレクションの一群を1回の SELECT で獲得します。
Hibernate は次に示す戦略とも区別をします:
  • 即時フェッチ:所有者のオブジェクトがロードされたときに、関連、コレクション、あるいは属性は即時にフェッチされます。
  • 遅延コレクションフェッチ:アプリケーションがコレクションに対して操作を行ったときにコレクションをフェッチします。これはコレクションでデフォルトとなっています。
  • 「Extra-lazy」コレクションフェッチ:コレクションの個別要素は随時データベースから取得されます。Hibernate は必要でなければ、コレクション全体をメモリにフェッチしないようにします。これは大規模なコレクションに敵しています。
  • プロキシフェッチ:単一値関連は、識別子の getter 以外のメソッドが関連オブジェクトで呼び出されるときにフェッチされます。
  • 「プロキシなし」フェッチ:単一値関連は、インスタンス変数にアクセスがあるとフェッチされます。プロキシフェッチと比較すると、この方法は遅延の度合いが少なく、識別子のみにアクセスがあっても、この間連はフェッチされます。また、このアプリケーションにはプロキシを見せないため、より透過的となっています。この方法はビルド時のバイトコード組み込みが必要になり、使う場面はまれです。
  • 遅延属性フェッチ:属性や単一値関連は、インスタンス変数にアクセスがあればフェッチされます。この方法はビルド時のバイトコード組み込みが必要になり、使う場面はまれです。
ここでは、直交概念が2つあります: いつ 関連をフェッチするか、そして、 どのように フェッチするか。重要なのは、これらを混同しないことです。fetch はパフォーマンスチューニングに使い、lazy はあるクラスの分離されたインスタンスのうち、どのデータを常に使用可能にするかの取り決めを定義するのに利用可能です。

19.1.1. 遅延関連の使いかた

デフォルトでは、Hibernate3 はコレクションに対し遅延セレクトフェッチを使い、単一値関連には遅延プロキシフェッチを使います。このようなデフォルトとなっているのは、 大半のアプリケーションにある関連の多くで、つじつまがあいます。
hibernate.default_batch_fetch_size をセットすると、Hibernate は遅延フェッチにバッチフェッチの最適化を利用します。この最適化はより細かいレベルで実現できます。
Hibernate の session がオープンでないコンテキストで遅延関連にアクセスすると、例外が発生することに注意してください。例:
s = sessions.openSession();
Transaction tx = s.beginTransaction();
            
User u = (User) s.createQuery("from User u where u.name=:userName")
    .setString("userName", userName).uniqueResult();
Map permissions = u.getPermissions();

tx.commit();
s.close();

Integer accessLevel = (Integer) permissions.get("accounts");  // Error!
Session がクローズされたとき、permissions コレクションは初期化されていないため、このコレクションは自身の状態をロードできません。Hibernate は切り離されたオブジェクトの遅延初期化はサポートしていません。修正方法として、コレクションから読み込むコードをトランザクションをコミットする直前に移動させます。
他には、lazy="false" を関連マッピングに指定することで、遅延処理をしないコレクションや関連を使うことが出来ます。しかしながら、遅延初期化はほぼすべてのコレクションや関連で使われることを意図しています。オブジェクトモデル内に遅延処理なしの関連を多く定義してしまうと、 Hibernate は、トランザクション毎にデータベース全体をメモリにフェッチすることになるでしょう。
一方、特定のトランザクションにおいてセレクトフェッチの代わりに結合フェッチ(基本的にこれはnon-lazy)を選択することができます。これからフェッチ戦略をカスタマイズする方法をお見せします。Hibernate3 では、単一値関連とコレクションにおいてフェッチ戦略を選択する仕組みは、全く同じです。

19.1.2. フェッチ戦略のチューニング

セレクトフェッチ(デフォルト)は N+1 セレクト問題という大きな弱点があるため、マッピング定義で結合フェッチを有効にすることができます:
<set name="permissions" 
            fetch="join">
    <key column="userId"/>
    <one-to-many class="Permission"/>
</set
<many-to-one name="mother" class="Cat" fetch="join"/>
マッピング定義で定義した フェッチ 戦略は次のものに影響します:
  • get()load() による復元
  • 関連にナビゲートしたときに発生する暗黙的な復元
  • Criteria クエリ
  • サブセレクト フェッチを使う HQL クエリ
どのフェッチ戦略を使ったとしても、遅延ではない定義済みグラフはメモリに読み込まれることが保証されます。しかし、つまり、特定の HQL クエリを実行するためにいくつかの SELECT 文が即時実行されることがあります。
通常は、マッピングドキュメントでフェッチのカスタマイズは行いません。代わりに、デフォルトの動作を保ち、HQL で left join fetch を指定することで特定のトランザクションで動作をオーバーライドします。これは Hibernate に初回のセレクトで外部結合を使って関連を先にフェッチするように指定しています。Criteria クエリの API では、 setFetchMode(FetchMode.JOIN) を使うことが出来ます。
get()load() で使われるフェッチ戦略を変えたいと感じたときには、単純に Criteria クエリを使うことができます。例:
User user = (User) session.createCriteria(User.class)
                .setFetchMode("permissions", FetchMode.JOIN)
                .add( Restrictions.idEq(userId) )
                .uniqueResult();
これはいくつかの ORM ソリューションが「fetch plan」と呼んでいるものと同じです。
N+1 セレクト問題へのまったく違うアプローチは、2次キャッシュを使うことです。

19.1.3. 単一端関連プロキシ

コレクションの遅延フェッチは、Hibernate 自身の実装による永続コレクションを使って実現しています。しかし、単一端関連における遅延処理では、違う仕組みが必要です。対象の関連エンティティはプロキシでなければなりません。Hibernate はCGLIB ライブラリを介し、実行時のバイトコード拡張を使って永続オブジェクトの遅延初期化プロキシを実現しています。
デフォルトでは、Hibernate3 はすべての永続クラスのプロキシを生成し、それらを使って、many-to-oneone-to-one 関連の遅延フェッチを可能にしています。
マッピングファイルで proxy 属性によって、クラスのプロキシインターフェースとして使うインターフェースを宣言できます。デフォルトでは、Hibernate はそのクラスのサブクラスを使います。プロキシクラスは少なくともパッケージ可視でデフォルトコンストラクタを実装する必要があります。すべての永続クラスにこのコンストラクタを推奨します。
ポリモーフィズムのクラスに対してもこの方法を適用する場合、いくつか問題が発生する可能性があります。例:
<class name="Cat" proxy="Cat">
    ......
    <subclass name="DomesticCat">
        .....
    </subclass>
</class>
第一に、 Cat のインスタンスは DomesticCat にキャストできません。たとえ基となるインスタンスが DomesticCat であったとしてもです:
Cat cat = (Cat) session.load(Cat.class, id);  // instantiate a proxy (does not hit the db)
if ( cat.isDomesticCat() ) {                  // hit the db to initialize the proxy
    DomesticCat dc = (DomesticCat) cat;       // Error!
    ....
}
第二に、プロキシの == は成立しないことがあります:
Cat cat = (Cat) session.load(Cat.class, id);            // instantiate a Cat proxy
DomesticCat dc = 
        (DomesticCat) session.load(DomesticCat.class, id);  // acquire new DomesticCat proxy!
System.out.println(cat==dc);                            // false
しかし、これは見かけほど悪い状況というわけではありません。たとえ異なったプロキシオブジェクトへの二つの参照があったとしても、基となるインスタンスは同じオブジェクトです:
cat.setWeight(11.0);  // hit the db to initialize the proxy
System.out.println( dc.getWeight() );  // 11.0
第三に、 final クラスや final メソッドを持つクラスに CGLIB プロキシを使えません。
最後に、永続オブジェクトのインスタンス化時 (例えば、初期化子やデフォルトコンストラクタの中で) になんらかのリソースを取得するなら、そのリソースもまたプロキシを通して取得されます。実際には、プロキシクラスは永続クラスにある実際のサブクラスです。
これらの問題は Java の単一継承モデルにある原理上の制限が原因となっています。これらの問題を避けたいのなら、ビジネスメソッドを宣言したインターフェースをそれぞれ永続クラスで実装しなければなりません。CatImpl がインターフェース DomesticCat 実装のCatDomesticCatImplと言うインターフェースを実装するマッピングファイルでこれらのインターフェースを指定する必要があります。例:
<class name="CatImpl" proxy="Cat">
    ......
    <subclass name="DomesticCatImpl" proxy="DomesticCat">
        .....
    </subclass>
</class>
そうすると、load() あるいは iterate()CatDomesticCat のインスタンスのプロキシを返すことができます。
Cat cat = (Cat) session.load(CatImpl.class, catid);
Iterator iter = session.createQuery("from CatImpl as cat where cat.name='fritz'").iterate();
Cat fritz = (Cat) iter.next();

注記

list() は通常、プロキシを返しません。
関連も遅延初期化されます。これはプロパティを Cat 型で宣言しなければならないことを意味します。 CatImpl ではありません。
プロキシの初期化を 必要としない 操作も存在します:
  • equals():永続クラスが equals() をオーバーライドしないとき
  • hashCode():永続クラスが hashCode() をオーバーライドしないとき
  • 識別子の getter メソッド
Hibernate は equals()hashCode() をオーバーライドした永続クラスを検出します。
デフォルトの lazy="proxy" の代わりに、 lazy="no-proxy" を選ぶと、型変換(キャスト)に関連する問題を回避することが出来ます。しかし、ビルド時のバイトコード組み込みが必要になり、どのような操作であっても、ただちにプロキシの初期化を行われます。

19.1.4. コレクションとプロキシの初期化

LazyInitializationException は、Session のスコープ外から初期化していないコレクションやプロキシにアクセスがあると、Hibernate によってスローされます。すなわち、コレクションやプロキシへの参照を持つエンティティが分離された状態の時です。
Session をクローズする前にプロキシやコレクションの初期化を確実に行いたいときがあります。もちろん、cat.getSex()cat.getKittens().size() などを常に呼び出すことで初期化を強制することはできます。しかしこれはコードを読む人を混乱させ、汎用的なコードという点からも不便です。
static メソッドの Hibernate.initialize()Hibernate.isInitialized() は遅延初期化のコレクションやプロキシを扱うときに便利な方法をアプリケーションに提供します。 Hibernate.initialize(cat) は、Session がオープンしている限りは cat プロキシを強制的に初期化します。Hibernate.initialize( cat.getKittens() ) は kittens コレクションに対して同様の効果があります。
別の選択肢として、必要なすべてのコレクションやプロキシがロードされるまで Session をオープンにしておく方法があります。アプリケーションのアーキテクチャによって、特に Hibernate によるデータアクセスを行うコードと、それを使うコードが異なるアプリケーションのレイヤーや、物理的に異なるプロセスにある場合、コレクション初期化時に Session を確実にオープンに保つ部分で問題があります。この問題の対応には2つの基本的な方法があります:
  • Web ベースのアプリケーションでは、ビューのレンダリングが完了し、ユーザーリクエストの最後でのみ、サーブレットフィルタを利用し Session をクローズすることができます(Open Session in View パターンです)。もちろん、アプリケーション基盤の例外処理の正確性が非常に重要になります。ビューのレンダリング中に例外が発生したときでさえ、ユーザーに処理が戻る前に Session のクローズとトランザクションの終了を行うことが不可欠になります。 Hibernate の Wiki に載っている 「Open Session in View」 パターンの例を参照してください。
  • ビジネス層が分離しているアプリケーションでは、ビジネスロジックは Web 層で必要になるすべてのコレクションを(値を)返す前に「準備」する必要があります。つまり、これは特定のユースケースで必要となるプレゼンテーション/ Web 層に対し、ビジネス層がすべてのデータをロードし、すべてのデータを初期化して返すべきということです。通常、アプリケーションは Web 層で必要な各コレクションに対して Hibernate.initialize() を呼び出すか(この呼び出しはセッションをクローズする前に行う必要があります)、 Hibernate クエリの FETCH 節や CriteriaFetchMode.JOIN を使ってコレクションを先に取得します。普通は Session Facade の代わりに Command パターンを採用するほうがより簡単です。
  • 初期化されていないコレクション、もしくは他のプロキシにアクセスする前に、 merge()lock() を使って新しい Session に以前にロードされたオブジェクトを追加することも出来ます。臨時トランザクションのセマンティクスを導入したので、 Hibernate はこれを自動的に行わず、行うべきでもありません
大きなコレクションを初期化したくはないが、コレクションについてのなんらかの情報(サイズのような)やデータのサブセットを必要とすることがあります。
コレクションフィルタを使うことで、初期化せずにコレクションのサイズを取得することが出来ます:
( (Integer) s.createFilter( collection, "select count(*)" ).list().get(0) ).intValue()
createFilter() メソッドは、コレクション全体を初期化する必要なしに、コレクションのサブセットを復元するために効果的に使えます:
s.createFilter( lazyCollection, "").setFirstResult(0).setMaxResults(10).list();

19.1.5. バッチフェッチの使用

バッチフェッチを利用し、Hibernate は一つのプロキシにアクセスがあると、Hibernate は初期化していない複数のプロキシをロードすることができます。バッチフェッチは遅延セレクトフェッチ戦略に対する最適化です。バッチフェッチの調整には2つの方法があります。クラスレベルとコレクションレベルです。
クラス、要素のバッチフェッチは理解が比較的簡単です。実行時の次の場面を想像してください。Session にロードされた25個の Cat インスタンスが存在し、各 Catowner である Person への関連を持ちます。Person クラスは lazy="true" のプロキシでマッピングされています。今すべての Cat に対して繰り返し getOwner() を呼び出すと、Hibernate はデフォルトでは25回の SELECT を実行し、owner プロキシの取得をします。この動作を Person のマッピングの batch-size の指定で調整できます。
<class name="Person" batch-size="10">...</class>
Hibernate はクエリを3回だけを実行するようになります:パターンは 10, 10, 5 です。
コレクションのバッチフェッチも有効にすることが出来ます。例として、それぞれの PersonCat の遅延コレクションを持っており、 10 個の Person が Sesssion にロードされたとすると、すべての Person に対して繰り返し getCats() を呼び出すことで、計10回の SELECT が発生します。Person のマッピングで cats コレクションのバッチフェッチを有効にすれば、 Hibernate はコレクションの事前フェッチが出来ます。
<class name="Person">
    <set name="cats" batch-size="3">
        ...
    </set>
</class>
batch-size が 3 なので、 Hibernate は 4 回の SELECT で 3 個、3 個、3 個、1 個をロードします。繰り返すと、属性の値は特定の Session の中の初期化されていないコレクションの期待数に依存します。
コレクションのバッチフェッチはアイテムのネストしたツリー、すなわち、代表的な部品表のパターンがある場合に特に有用です。しかし、読み込みが多いツリーでは ネストした set具体化したパス のほうが選択肢としては良いでしょう。

19.1.6. サブセレクトフェッチの使用

一つの遅延コレクションや単一値プロキシがフェッチされなければならない場合、 Hibernate はそれらすべてをロードし、サブセレクトのオリジナルクエリが再度実行されます。これはバッチフェッチと同じ方法で動き、逐次ロードはありません。

19.1.7. 遅延プロパティフェッチの使用

Hibernate3 はプロパティごとの遅延フェッチをサポートしています。この最適化手法は グループのフェッチ としても知られています。これは多くの場合マーケティング機能であることに注意してください。実際には列読み込みの最適化よりも、行読み込みの最適化が非常に重要です。しかし、クラスのプロパティの一部だけを読み込むことは極端な事例において便利です。たとえば、レガシーテーブルが何百ものカラムを持ち、データモデルを改善できないなどです。
遅延プロパティ読み込みを有効にするには、対象のプロパティのマッピングで lazy 属性をセットしてください:
<class name="Document">
       <id name="id">
        <generator class="native"/>
    </id>
    <property name="name" not-null="true" length="50"/>
    <property name="summary" not-null="true" length="200" lazy="true"/>
    <property name="text" not-null="true" length="2000" lazy="true"/>
</class>
遅延プロパティ読み込みはビルド時のバイトコード組み込みを必要とします。永続クラスが拡張されていない場合、Hibernate は遅延プロパティの設定を無視して、即時フェッチに戻します。
バイトコード組み込みは以下の Ant タスクを使ってください:
<target name="instrument" depends="compile">
    <taskdef name="instrument" classname="org.hibernate.tool.instrument.InstrumentTask">
        <classpath path="${jar.path}"/>
        <classpath path="${classes.dir}"/>
        <classpath refid="lib.class.path"/>
    </taskdef>

    <instrument verbose="true">
        <fileset dir="${testclasses.dir}/org/hibernate/auction/model">
            <include name="*.class"/>
        </fileset>
    </instrument>
</target>
不要な列を読み込まないための別の方法は、少なくとも読み込みのみのトランザクションにおいては、HQL や Criteria クエリの射影機能を使うことです。この方法はビルド時のバイトコード組み込みが不要になり、確実のこちらのほうが推奨される解決方法です。
HQL で fetch all properties を使うことで、普通どおりのプロパティの即時フェッチングを強制することが出来ます。

19.2. 2次レベルキャッシュ

Hibernate のSession は永続データのトランザクションレベルのキャッシュです。class-by-class と collection-by-collection ごとの、クラスタレベルや JVM レベル ( SessionFactory レベル)のキャッシュを設定することが出来ます。クラスタ化されたキャッシュにつなぐことさえ出来ます。キャッシュは他のアプリケーションによる永続層の変更を考慮しない点に注意してください。キャッシュデータを定期的に無効化する設定は出来ます。
Hibernate は、hibernate.cache.provider_class プロパティを利用して org.hibernate.cache.CacheProvider を実装するクラス名を指定することで、どのキャッシュ実装を使用するか指示できます。Hibernate では、以下に示された複数のオープンソースのキャッシュプロバイダが組み込みで統合されています。また、上記のように、独自のキャッシュプロバイダを実装して組み込むことも出来ます。

表19.1 キャッシュプロバイダ

キャッシュ プロバイダクラス タイプ クラスタセーフ クエリキャッシュのサポート
Hashtable(本番利用向けではありません) org.hibernate.cache.HashtableCacheProvider メモリ yes
EHCache org.hibernate.cache.EhCacheProvider メモリ、ディスク yes
OSCache org.hibernate.cache.OSCacheProvider メモリ、ディスク yes
SwarmCache org.hibernate.cache.SwarmCacheProvider クラスタ(ip マルチキャスト) yes(クラスタ無効化)
JBoss Cache 1.x org.hibernate.cache.TreeCacheProvider クラスタ(ip マルチキャスト)、トランザクショナル yes(複製) yes(時刻同期が必要)
JBoss Cache 2 org.hibernate.cache.jbc2.JBossCacheRegionFactory クラスタ(ip マルチキャスト)、トランザクショナル yes(複製または無効化) yes(時刻同期が必要)

19.2.1. キャッシュのマッピング

クラスやコレクションのマッピングの <cache> 要素は以下の形式です。
<cache 
    usage="transactional|read-write|nonstrict-read-write|read-only"   1
    region="RegionName"                                               2
    include="all|non-lazy"                                            3
/>

1

usage (必須) キャッシング戦略を指定します: transactionalread-writenonstrict-read-write または read-only

2

region (オプション:クラスまたはコレクションのロール名のデフォルト) 2次キャッシュ領域の名前を指定します

3

include (オプション:all に対してデフォルト) non-lazy は、 属性レベルの lazy フェチが有効になっている場合 lazy="true" でマッピングされるエンティティのプロパティはキャッシュされなくてもよいことを指定します。
または、 hibernate.cfg.xml<class-cache><collection-cache> 要素を指定することも出来ます。
usage 属性は キャッシュの並列性戦略 を指定します。

19.2.2. read only 戦略

アプリケーションが永続クラスのインスタンスを修正するのではなく、読み込みを必要とする場合、read-only キャッシュを使うことが出来ます。これはもっとも単純でもっともパフォーマンスの良い戦略です。クラスタでの使用も安全です。
<class name="eg.Immutable" mutable="false">
    <cache usage="read-only"/>
    ....
</class>

19.2.3. read/write 戦略

アプリケーションがデータを更新する必要があるなら、read-write キャッシュが適当かもしれません。このキャッシュ戦略は、シリアル化トランザクション分離レベルが必要な場合決して使うべきではありません。キャッシュが JTA 環境で使われるなら、JTA TransactionManager を取得するための方法を示す hibernate.transaction.manager_lookup_class プロパティを指定しなければなりません。他の環境では、 Session.close()Session.disconnect() が呼ばれたときに、確実にトランザクションが完了していなければなりません。もしクラスタでこの戦略を使いたいなら、基となるキャッシュの実装がロックをサポートしていることを保証しなければなりません。組み込みのキャッシュプロバイダは サポートしていません
<class name="eg.Cat" .... >
    <cache usage="read-write"/>
    ....
    <set name="kittens" ... >
        <cache usage="read-write"/>
        ....
    </set>
</class>

19.2.4. Nonstrict (非正格)read/write 戦略

アプリケーションがたまにしかデータを更新する必要はなく(すなわち二つのトランザクションが同時に同じアイテムを更新しようとすることはほとんど起こらない場合)、厳密なトランザクション分離が要求されないなら、nonstrict-read-write キャッシュが適当かもしれません。キャッシュが JTA 環境で使われるなら、 hibernate.transaction.manager_lookup_class を指定しなければなりません。他の環境では、 Session.close()Session.disconnect() が呼ばれたときに、確実にトランザクションが完了していなければなりません。

19.2.5. transactional 戦略

transactional キャッシュ戦略は JBoss TreeCache のような完全なトランザクショナルキャッシュプロバイダのサポートを提供します。このようなキャッシュは JTA 環境でのみ使用可能で、hibernate.transaction.manager_lookup_class を指定しなければなりません。

19.2.6. キャッシュプロバイダ/同時並行性戦略の互換性

重要

すべてのキャッシュの同時並行性戦略をサポートしているキャッシュプロバイダはありません。
以下の表はどのプロバイダがどの同時並列性戦略に対応するかを表しています。

表19.2 同時並行性キャッシュ戦略のサポート

キャッシュ read-only 厳密ではない read-write read-write transactional
Hashtable(本番利用向けではありません) yes yes yes
EHCache yes yes yes
OSCache yes yes yes
SwarmCache yes yes
JBoss Cache 1.x yes yes
JBoss Cache 2 yes yes

19.3. キャッシュの管理

オブジェクトを save()update()saveOrUpdate() に渡すとき、そして load()get()list()iterate()scroll() を使ってオブジェクトを取得するときには常に、そのオブジェクトは Session の内部キャッシュに追加されます。
次に flush() が呼ばれると、オブジェクトの状態はデータベースと同期化されます。この同期が起こることを望まないときや、膨大な数のオブジェクトを処理していてメモリを効率的に扱う必要があるときは、evict() メソッドを使って一次キャッシュからオブジェクトやコレクションを削除することが出来ます。
ScrollableResults cats = sess.createQuery("from Cat as cat").scroll(); //a huge result set
while ( cats.next() ) {
    Cat cat = (Cat) cats.get(0);
    doSomethingWithACat(cat);
    sess.evict(cat);
}
Session はインスタンスがセッションキャッシュに含まれるかどうかを判断するための contains() メソッドも提供します。
すべてのオブジェクトをセッションキャッシュから完全に取り除くには、 Session.clear() を呼び出してください。
二次キャッシュのために、 SessionFactory にはインスタンス、クラス全体、コレクションのインスタンス、コレクション全体をキャッシュから削除するためのメソッドがそれぞれ定義されています。
sessionFactory.evict(Cat.class, catId); //evict a particular Cat
sessionFactory.evict(Cat.class);  //evict all Cats
sessionFactory.evictCollection("Cat.kittens", catId); //evict a particular collection of kittens
sessionFactory.evictCollection("Cat.kittens"); //evict all kitten collections

注記

SessionFactory.evictXXX(..., Serializable id) APIを使い、アプリケーションの結果として、このメソッドが呼び出されます。この API を使ったアプリケーションは、これに対する呼び出しにより、他のトランザクションがJBoss Cache ベースの二次キャッシュで完了するまで待機させないようにしてしまう可能性があると認識しているはずです。
さらに、トランザクションの最中で発生した呼び出しは、トランザクションがコミットするまでロックを保持しますが、他のノードをアップデートしません。これが問題な場合は、トランザクション開始前、かつコミット前にエビクションを行うと便利でしょう。
CacheMode は特定のセッションが二次キャッシュとどのように相互作用するかを制御します。
  • CacheMode.NORMAL:アイテムの読み込みと書き込みで二次キャッシュを使います
  • CacheMode.GET:読み込みは二次キャッシュから行いますが、データを更新した場合を除いて二次キャッシュに書き込みをしません。
  • CacheMode.PUT:二次キャッシュにアイテムを書き込みますが、読み込みには二次キャッシュを使いません。
  • CacheMode.REFRESH:二次キャッシュにアイテムを書き込みますが、読み込みには二次キャッシュを使いません。hibernate.cache.use_minimal_puts の影響を受けずに、データベースから読み込むすべてのアイテムの二次キャッシュを強制的にリフレッシュします。
二次キャッシュの内容やクエリキャッシュ領域を見るために、 Statistics API を使ってください:
Map cacheEntries = sessionFactory.getStatistics()
        .getSecondLevelCacheStatistics(regionName)
        .getEntries();
統計情報を有効にして、さらにオプションとして、キャッシュエントリをより読解可能な形式で保持することを Hibernate に強制する必要があります:
hibernate.generate_statistics true
hibernate.cache.use_structured_entries true

19.4. クエリキャッシュ

クエリの結果もキャッシュ化出来ます。これは同じパラメータで何度も実行されるクエリに対してのみ有用です。クエリキャッシュを使うには、まず設定で有効にしなくてはなりません:
hibernate.cache.use_query_cache true
この設定は新たに二つのキャッシュ領域の作成を行います。一つはクエリのリザルトセットのキャッシュ( org.hibernate.cache.StandardQueryCache )を保持し、もう1つはクエリ可能なテーブルへの最新の更新タイムスタンプ ( org.hibernate.cache.UpdateTimestampsCache)を保持します。クエリキャッシュはリザルトセットの実際の要素の状態はキャッシュしないことに注意してください。キャッシュするのは識別子の値と、値型の結果のみです。そのため、クエリキャッシュは常に二次キャッシュと一緒に使うべきです。
ほとんどのクエリはキャッシュの恩恵を受けないので、デフォルトではクエリはキャッシュされません。キャッシュを有効にするには、Query.setCacheable(true) を呼び出してください。そうすればクエリが既存のキャッシュ結果を探し、クエリ実行時にその結果をキャッシュに追加するようになります。
クエリキャッシュの無効化ポリシーを細かく制御したいときは、 Query.setCacheRegion() を呼び出して特定のクエリに対するキャッシュ領域を指定することが出来ます。
List blogs = sess.createQuery("from Blog blog where blog.blogger = :blogger")
    .setEntity("blogger", blogger)
    .setMaxResults(15)
    .setCacheable(true)
    .setCacheRegion("frontpages")
    .list();
クエリが自身のクエリキャッシュ領域のリフレッシュを強制しなければならないなら、 Query.setCacheMode(CacheMode.REFRESH) を呼び出すべきです。これは元となるデータが別のプロセスによって更新されたり(すなわち Hibernate を通じて更新されない)、アプリケーションに特定のクエリリザルトセットを選択してリフレッシュさせる場合に特に有用です。さらに有用なもう一つの方法は、 SessionFactory.evictQueries() によってクエリキャッシュ領域を消去することです。

19.5. コレクションのパフォーマンスの理解

前章ではコレクションとそのアプリケーションについて見てきました。本章では、実行時のコレクション関連の問題についてもう少し見ていきましょう。

19.5.1. 分類

Hibernate は3つの基本的なコレクションの種類を定義しています:
  • 値のコレクション
  • 一対多関連
  • 多対多関連
この分類はさまざまなテーブルや外部キー関連を区別しますが、私たちが知る必要のある関連モデルについてほとんどなにも教えてくれません。関連構造やパフォーマンスの特徴を完全に理解するには、 Hibernate がコレクションの行を更新、削除するために使う主キーの構造もまた考えなければなりません。これは以下の分類を提示します。
  • インデックス付きコレクション
  • set
  • bag
すべてのインデックス付きコレクション(マップ、リスト、配列)は <key><index> カラムからなる主キーを持っています。この場合、コレクションの更新は非常に効率的です。主キーは効率的にインデックス化され、Hibernate が特定の行を更新または削除しようとすると、その行を効率的に見つけることができます。
set は <key> からなる主キーと要素のカラムを持っています。これはコレクション要素のいくつかの型については効率的ではないかもしれません。特に複合要素、大きなテキスト、バイナリフィールドでは非効率です。データベースは複合主キーに効率的にインデックスを付けることができないからです。一方、一対多や多対多関連において、特に人工識別子の場合は同じぐらい効率的です。SchemaExport で実際に <set> の主キーを作りたいなら、すべてのカラムで not-null="true" を宣言しなければなりません。
<idbag> マッピングは代理キーを定義するため、更新は常に非常に効率的です。事実上、これは最善のケースです。
bag は最悪のケースです。 bag は要素の値の重複が可能で、インデックスカラムを持たないため、主キーは定義されないかもしれません。Hibernate には重複した行を区別する方法がありません。Hibernate はこの問題の解決のために、変更があったときには常に一回のDELETE による完全な削除を行い、コレクションの再作成を行います。これは非常に非効率的かもしれません。
一対多関連では、「主キー」はデータベースのテーブルの物理的な主キーではないかもしれないことに注意してください。しかしこの場合でさえ、上記の分類はまだ有用です。Hibernateがコレクションの個々の行をどのように「見つけるか」を表しています。

19.5.2. 更新にもっとも効率的なコレクション list、map、idbag、set

上での議論から、インデックス付きコレクションと set は要素の追加、削除、更新でもっとも効率的な操作が出来ることは明らかでしょう。
ほぼ間違いなく、多対多関連や値のコレクションにおいて、インデックス付きコレクションが set よりも優れている点がもう一つあります。Set はその構造が原因で、Hibernate は要素が「変更」されたときに行を決して UPDATE しません。Set への変更は常に各行のINSERTDELETE によって行います。繰り返しますが、これは一対多関連には当てはまりません。
配列は遅延処理ができないという決まりなので、結論として、list、map、idbag がもっともパフォーマンスの良い(inverse ではない)コレクションタイプとなります。set もそれほど違いはありません。Hibernate のアプリケーションでは、set はコレクションのもっとも一般的な種類として考えることができます。これは、「set」の表現が関連モデルでもっとも自然だからです。
しかし、よく設計された Hibernate のドメインモデルでは、通常もっとも多いコレクションは事実上 inverse="true" を指定した一対多関連です。これらの関連では、更新は多対一の関連端で扱われ、コレクションの更新パフォーマンスの問題は単純に当てはまりません。

19.5.3. inverse コレクションにもっとも最適な bag と list

しかし、bag そして list が set よりもずっとパフォーマンスが良い特別なケースを紹介します。inverse="true" のコレクション(一般的な双方向の一対多関連の慣用句な)、bag 要素を初期化(フェッチ)する必要なく bag や list に要素を追加できます。これは Setとは違って、Collection.add()Collection.addAll() は bag や List では常に true を返さなければならないからです。これは以下の共通処理をより速くすることができます:
Parent p = (Parent) sess.load(Parent.class, id);
Child c = new Child();
c.setParent(p);
p.getChildren().add(c);  //no need to fetch the collection!
sess.flush();

19.5.4. 一括削除

コレクションの要素を一つずつ削除するのは極めて非効率的になることがあります。Hibernate は新しい空のコレクションの場合( list.clear() を呼び出した場合など)はこれをすべきでないことを知っています。この場合は、Hibernate は DELETE を一回発行します。
サイズ20のコレクションに要素を1つ追加し、それから二つの要素を削除するとします。Hibernate は、コレクションが bag でなければ、一つの INSERT 文と二つの DELETE 文を発行します。これは確かに望ましい動作です。
しかし、18個の要素を削除して2つを残し、それから3つ新しい要素を追加するとします。このとき二つの方法があります。
  • 18行を順に削除して、3行を追加する
  • 一回のSQL DELETE でコレクション全体を削除し、5つの要素すべてを一つずつ挿入します。
Hibernate はこの場合に2番目の方法が早いことはおそらく分からないでしょう。このような振る舞いはデータベースのトリガなどを混乱させる場合があるため、Hibernateがここまで直感的なのはおそらく好ましくありません。
幸いにも、元のコレクションを捨て(つまり参照をやめて)、現在の要素をすべて持つ新しいコレクションのインスタンスを返すことで、いつでもこの動作(2番目の戦略)を強制することが出来ます。
一括削除は inverse="true" をマッピングしたコレクションに適用しません。

19.6. パフォーマンスのモニタリング

最適化はモニタリングやパフォーマンスを示す数値がなければ十分に行えません。 Hibernate は内部処理のすべての範囲の数値を提供します。 Hibernate の統計情報は SessionFactory 単位で取得可能です。

19.6.1. SessionFactory のモニタリング

SessionFactory のメトリクスにアクセスするには2つの方法があります。最初の方法は、 sessionFactory.getStatistics() を呼び出し、自分で Statistics の読み込みや表示を行います。
StatisticsService MBean を有効にしていれば、Hibernate は JMX を使ってメトリクスを発行することもできます。1つの MBean をすべての SessionFactory に対して有効にするか、SessionFactory ごとに一つの MBean を有効にすることが出来ます。最小限の設定例については、以下のコードを見てください:
// MBean service registration for a specific SessionFactory
Hashtable tb = new Hashtable();
tb.put("type", "statistics");
tb.put("sessionFactory", "myFinancialApp");
ObjectName on = new ObjectName("hibernate", tb); // MBean object name

StatisticsService stats = new StatisticsService(); // MBean implementation
stats.setSessionFactory(sessionFactory); // Bind the stats to a SessionFactory
server.registerMBean(stats, on); // Register the Mbean on the server
// MBean service registration for all SessionFactory's
Hashtable tb = new Hashtable();
tb.put("type", "statistics");
tb.put("sessionFactory", "all");
ObjectName on = new ObjectName("hibernate", tb); // MBean object name

StatisticsService stats = new StatisticsService(); // MBean implementation
server.registerMBean(stats, on); // Register the MBean on the server
SessionFactory に対してモニタリングの開始や終了を行うことが出来ます。
  • 設定時には、 hibernate.generate_statisticsfalse にします
  • 実行時に、 sf.getStatistics().setStatisticsEnabled(true) または hibernateStatsBean.setStatisticsEnabled(true) を呼び出します
統計は clear() メソッドを使ってプログラムでリセットすることが出来ます。サマリは logSummary() メソッドを使って logger に送ることが出来ます(info レベルです)。

19.6.2. メトリクス

Hibernate は、基本情報から、特定のシナリオのみに該当するような、さらに特化された情報まで、多くのメトリクスを用意しています。すべての使用可能なカウンタは Statistics インターフェースの API に書かれており、3つの分類があります:
  • 一般的な Session の使い方と関係するメトリクス。オープンセッションの数、取得した JDBC 接続など
  • 全体として、要素、コレクション、クエリ、キャッシュに関連するメトリクス(別名はグローバルメトリクスです)。
  • 特定のエンティティ、コレクション、クエリ、キャッシュ領域に関係した詳細のメトリクス。
例として、キャッシュのヒット、ヒットミスや、要素、コレクション、クエリの割合、クエリの実行に必要な平均時間を確認できます。ミリ秒の数値は Java の近似の影響を受けることに注意してください。Hibernate は JVM の精度に制限され、プラットフォームによっては10秒単位でしか正確でないかもしれません。
単純な getter はグローバルメトリクス(すなわち特定のエンティティ、コレクション、キャッシュ領域などに縛られない)にアクセスするために使います。特定のエンティティ、コレクション、キャッシュ領域のメトリクスは、それらの名前や、クエリの HQL、SQL 表現によってアクセスすることが出来ます。さらに詳しい情報は、 StatisticsEntityStatisticsCollectionStatisticsSecondLevelCacheStatisticsQueryStatistics API の javadoc を参照してください。以下のコードは簡単な例です:
Statistics stats = HibernateUtil.sessionFactory.getStatistics();

double queryCacheHitCount  = stats.getQueryCacheHitCount();
double queryCacheMissCount = stats.getQueryCacheMissCount();
double queryCacheHitRatio =
  queryCacheHitCount / (queryCacheHitCount + queryCacheMissCount);

log.info("Query Hit ratio:" + queryCacheHitRatio);

EntityStatistics entityStats =
  stats.getEntityStatistics( Cat.class.getName() );
long changes =
        entityStats.getInsertCount()
        + entityStats.getUpdateCount()
        + entityStats.getDeleteCount();
log.info(Cat.class.getName() + " changed " + changes + "times"  );
すべてのエンティティ、コレクション、クエリ、キャッシュ領域に対して作業を行う場合は、以下のメソッドを利用しそれぞれの名称リストを取得することができます:getQueries()getEntityNames()getCollectionRoleNames()getSecondLevelCacheRegionNames()

第20章 ツールセットガイド

Hibernate を使ったラウンドトリップエンジニアリングは、Eclipse プラグインやコマンドラインツール、Ant タスクを使うことで可能です。
Hibernate Tools は現在、既存データベースのリバースエンジニアリングの Ant タスクに加えて、Eclipse IDE のプラグインを含みます:
  • マッピングエディタ: Hibernate の XML マッピングファイル用のエディタで、自動補完と構文強調表示をサポートしています。クラス名やプロパティ/フィールド名に対する自動補完もサポートし、通常の XML エディタよりも強力です。
  • Console: コンソールはEclipseの新しいビューです。コンソール構成のツリーの全体図に加えて、永続クラスとその関連の相互作用ビューも得られます。データベースに HQL を実行し、結果を直接Eclipse上で見ることができます。
  • 開発ウィザード Hibernate の Eclipse ツールはいくつかのウィザードを提供します。ウィザードを使って Hibernate の設定ファイル (cfg.xml) をすばやく生成し、あるいは、既存のデータベーススキーマを POJO のソースファイルと Hibernate のマッピングファイルへと、完全にリバースエンジニアリングすることができます。リバースエンジニアリングウィザードはカスタマイズ可能なテンプレートをサポートします。
より詳しい情報は Hibernate Tools パッケージドキュメントを参照してください。
しかし、 Hibernate のメインパッケージは SchemaExport 、別名 hbm2ddl という統合ツールも同梱しています。Hibernate 「内」でも使用できます。

20.1. スキーマの自動生成

DDL は Hibernate ユーティリティによりマッピングファイルから生成することができます。生成されたスキーマはエンティティやコレクションのテーブルに対する参照整合性制約、主キー、外部キーを含みます。テーブルとシーケンスはマッピングされた識別子ジェネレータに対しても生成されます。
DDL は非常にベンダーに依存しており、このツールを使うときは、hibernate.dialect プロパティで SQL の 方言 を指定 しなければなりません
まず、生成されるスキーマを改善するように、マッピングファイルをカスタマイズしてください。次の章でスキーマのカスタマイズについて説明します。

20.1.1. スキーマのカスタマイズ

多くの Hibernate のマッピング要素では、lengthprecisionscale という名のオプション属性を定義しています。この属性でカラムの長さ、精度、スケールを設定することができます。
<property name="zip" length="5"/>
<property name="balance" precision="12" scale="2"/>
テーブルカラムに NOT NULL 制約を生成するnot-nullとテーブルカラムに UNIQUE 制約を生成する unique 属性を受け付けるタグもあります。
<many-to-one name="bar" column="barId" not-null="true"/>
<element column="serialNumber" type="long" not-null="true" unique="true"/>
unique-key 属性は、カラムを一意のキー制約1つにグループ化して使われます。現在、 unique-key 属性で指定された値は制約の指定には 使われず 、マッピングファイルでカラムをグループ化することにのみ使われます。
<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
<property name="employeeId" unique-key="OrgEmployee"/>
index 属性は、1つ以上のマッピングされたカラムを使って生成したインデックスの名前を指定します。複数カラムを1つのインデックスにグループ化できます。単に、同じインデックス名を指定するだけです。
<property name="lastName" index="CustName"/>
<property name="firstName" index="CustName"/>
foreign-key 属性は、生成外部キー制約の名前をオーバーライドするために使用できます。
<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>
多くのマッピング要素は、子 <column> 要素を記述できます。これは複数カラム型のマッピングには特に有用です:
<property name="name" type="my.customtypes.Name"/>
    <column name="last" not-null="true" index="bar_idx" length="30"/>
    <column name="first" not-null="true" index="bar_idx" length="20"/>
    <column name="initial"/>
</property>
default 属性はカラムのデフォルト値を指定します。マッピングしたクラスの新しいインスタンスを保存する前に、マッピングしたプロパティへ同じ値を代入する必要があります。
<property name="credits" type="integer" insert="false">
    <column name="credits" default="10"/>
</property>
<version name="version" type="integer" insert="false">
    <column name="version" default="0"/>
</property>
sql-type 属性で、デフォルトの Hibernate 型から SQL のデータ型へのマッピングをオーバーライドできます。
<property name="balance" type="float">
    <column name="balance" sql-type="decimal(13,3)"/>
</property>
check 属性でチェック制約を指定することができます。
<property name="foo" type="integer">
    <column name="foo" check="foo > 10"/>
</property>
<class name="Foo" table="foos" check="bar < 100.0">
    ...
    <property name="bar" type="float"/>
</class>
以下のテーブルにて、これらのオプション属性についてまとめています。

表20.1 要約

属性 説明
length 数値 カラムの長さ
precision 数値 カラムの DECIMAL 型の精度(precision)
scale 数値 カラムの DECIMAL 型のスケール(scale)
not-null true|false カラムが null 値を取らないことを指定します。
unique true|false カラムがユニーク制約を持つことを指定します
index index_name (複数カラムの)インデックスの名前を指定します
unique-key unique_key_name 複数カラムのユニーク制約の名前を指定します
foreign-key foreign_key_name <one-to-one><many-to-one><key>、 または <many-to-many> マッピングエレメントのために、関連に対して生成された外部キー制約の名前を指定します。 inverse="true" 側は SchemaExport によって考慮されないことに注意してください。
sql-type SQL column type デフォルトのカラム型をオーバーライドします ( <column> 要素の属性に限る)
default SQL 式 カラムのデフォルト値を指定します
check SQL 式 カラムかテーブルに SQL のチェック制約を作成します
<comment> 要素で生成するスキーマにコメントを指定することができます。
<class name="Customer" table="CurCust">
    <comment>Current customers only</comment>
    ...
</class>
<property name="balance">
    <column name="bal">
        <comment>Balance in USD</comment>
    </column>
</property>
これにより、対応している場合、生成した DDL に comment on tablecomment on column 文が書かれます。

20.1.2. ツールの実行

SchemaExport は標準出力に対して DDL スクリプトを書き出し、 DDL 文を実行したりもします。
以下の表で、SchemaExport のコマンドラインオプションを示しています。
java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files

表20.2 SchemaExport のコマンドラインオプション

オプション 説明
--quiet 標準出力(stdout)にスクリプトを出力しません
--drop テーブルの削除だけを行います
--create テーブルの生成のみを行います
--text データベースにエクスポートしません
--output=my_schema.ddl DDL スクリプトをファイルに出力します
--naming=eg.MyNamingStrategy NamingStrategy を選択
--config=hibernate.cfg.xml XML ファイルから Hibernate の定義情報を読み込みます
--properties=hibernate.properties ファイルからデータベースのプロパティを読み込みます
--format スクリプト内に生成する SQL を読みやすいようにフォーマットします
--delimiter=; スクリプトの行区切り文字を設定します
アプリケーションに SchemaExport を組み込むこともできます:
Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);

20.1.3. プロパティ

データベースのプロパティを指定することができます:
  • -D<property> を使って、システムプロパティとして
  • hibernate.properties ファイル内で
  • --properties を使って指定したプロパティファイル内で
必要なプロパティは以下のものです:

表20.3 SchemaExport コネクションプロパティ

プロパティ名 説明
hibernate.connection.driver_class jdbc のドライバークラス
hibernate.connection.url jdbc の url
hibernate.connection.username データベースのユーザー
hibernate.connection.password ユーザーパスワード
hibernate.dialect データベース方言

20.1.4. Ant を使用する

Ant のビルドスクリプトから SchemaExport を呼び出すことができます:
<target name="schemaexport">
    <taskdef name="schemaexport"
        classname="org.hibernate.tool.hbm2ddl.SchemaExportTask"
        classpathref="class.path"/>
    
    <schemaexport
        properties="hibernate.properties"
        quiet="no"
        text="no"
        drop="no"
        delimiter=";"
        output="schema-export.sql">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaexport>
</target>

20.1.5. インクリメンタルなスキーマ更新

SchemaUpdate ツールは既存のスキーマを「インクリメンタル」に更新します。SchemaUpdate は JDBC のメタデータ API に依存します。そのため、すべての JDBC ドライバで正常に機能するとは限りません。
java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files

表20.4 SchemaUpdate のコマンドラインオプション

オプション 説明
--quiet 標準出力(stdout)にスクリプトを出力しません
--text データベースにスクリプトをエクスポートしません
--naming=eg.MyNamingStrategy NamingStrategy を選択
--properties=hibernate.properties ファイルからデータベースのプロパティを読み込みます
--config=hibernate.cfg.xml .cfg.xml ファイルを指定
アプリケーションに SchemaUpdate を組み込むことができます:
Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);

20.1.6. インクリメンタルなスキーマ更新に対する Ant の使用

Ant スクリプトから SchemaUpdate を呼び出すことができます:
<target name="schemaupdate">
    <taskdef name="schemaupdate"
        classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask"
        classpathref="class.path"/>
    
    <schemaupdate
        properties="hibernate.properties"
        quiet="no">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaupdate>
</target>

20.1.7. スキーマバリデーション

SchemaValidator ツールは、既存のデータベーススキーマとマッピングドキュメントが「一致する」ことを検証します。 SchemaValidator は JDBC のメタデータ API に強く依存します。そのため、すべての JDBC ドライバーで作動するものではありません。このツールはテスト時に非常に有用です。
java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaValidator options mapping_files
以下の表で、SchemaValidator のコマンドラインオプションを示しています。

表20.5 SchemaValidator のコマンドラインオプション

オプション 説明
--naming=eg.MyNamingStrategy NamingStrategy を選択
--properties=hibernate.properties ファイルからデータベースのプロパティを読み込みます
--config=hibernate.cfg.xml .cfg.xml ファイルを指定
SchemaValidator をアプリケーションに組み込むことが出来ます:
Configuration cfg = ....;
new SchemaValidator(cfg).validate();

20.1.8. スキーマのバリデーションに Ant を使用

Ant スクリプトから SchemaValidator を呼び出せます:
<target name="schemavalidate">
    <taskdef name="schemavalidator"
        classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask"
        classpathref="class.path"/>
    
    <schemavalidator
        properties="hibernate.properties">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemavalidator>
</target>

第21章 例: 親/子

新規ユーザーが Hibernate を使ってまず最初に扱うモデルの一つに、親子型関係のモデル化があります。このモデル化には二つのアプローチが存在します。とりわけ新規ユーザーにとって、さまざまな理由から最も便利だと思われるアプローチは、 から への <one-to-many> 関連により の両方をエンティティクラスとしてモデリングする方法です。もう一つの方法は、<composite-element> として定義するものです。これで、Hibernate における一対多関連のデフォルトのセマンティクスが、通常の複合要素のマッピングよりも、親子関係のセマンティクスから遠いことがわかります。それでは親子関係を効率的かつ簡潔にモデリングするために、 カスケード操作を使った双方向一対多関連 の扱い方を説明します。

21.1. コレクションに関する注意

Hibernate のコレクションは自身のエンティティの論理的な部分と考えられ、決して包含するエンティティの一部ではありません。これは非常に大きく違い、以下のような結果をもたらす点に注意してください:
  • オブジェクトをコレクションから削除、またはコレクションに追加するとき、コレクションのオーナーのバージョン番号はインクリメントされます。
  • コレクションから削除されたオブジェクトが値型のインスタンス(例:複合要素) である場合、そのオブジェクトは永続的ではなくなり、その状態はデータベースから完全に削除されます。同じように、値型のインスタンスをコレクションに追加すると、その状態はすぐに永続的になります。
  • 一方、エンティティがコレクション(一対多または多対多関連) から削除されても、デフォルトではそれは削除されません。この動作は完全に一貫しています。すなわち、他のエンティティの内部状態を変更しても、関連するエンティティが消滅すべきではないということです。同様に、エンティティがコレクションに追加されても、デフォルトではそのエンティティは永続的にはなりません。
デフォルトの動作では、エンティティをコレクションに追加すると単に二つのエンティティ間のリンクを作成し、一方エンティティを削除するとリンクも削除します。これはすべてのケースにおいて非常に適切です。これが適切でないのは親/子関係の場合です。この場合、子の生存は親のライフサイクルに制限されるからです。

21.2. 双方向一対多

Parent から Child への単純な <one-to-many> 関連から始めるとします。
<set name="children">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>
以下のコードを実行したとすると、
Parent p = .....;
Child c = new Child();
p.getChildren().add(c);
session.save(c);
session.flush();
Hibernate は二つの SQL 文を発行します:
  • c に対するレコードを生成する INSERT
  • p から c へのリンクを作成する UPDATE
これは非効率的なだけではなく、parent_id カラムにおいて NOT NULL 制約に違反します。コレクションのマッピングで not-null="true" と指定することで、null 制約違反を解決することができます:
<set name="children">
    <key column="parent_id" not-null="true"/>
    <one-to-many class="Child"/>
</set>
しかしこの解決策は推奨できません。
この動作の根本的な原因は、 p から c へのリンク(外部キー parent_id) は Child オブジェクトの状態の一部とは考えられず、そのため INSERT によってリンクが生成されないことです。つまり、解決策はリンクを Child マッピングの一部にすることです。
<many-to-one name="parent" column="parent_id" not-null="true"/>
また Child クラスに parent プロパティを追加する必要があります。
それでは Child エンティティがリンクの状態を制御するようになったので、コレクションがリンクを更新しないようにしましょう。それには inverse 属性を使います:
<set name="children" inverse="true">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>
以下のコードを使えば、新しい Child を追加することができます:
Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
c.setParent(p);
p.getChildren().add(c);
session.save(c);
session.flush();
SQL の INSERT 文が一つだけが発行されるようになりました。
ParentaddChild() メソッドを作成することもできます。
public void addChild(Child c) {
    c.setParent(this);
    children.add(c);
}
Child を追加するコードはこのようになります:
Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
p.addChild(c);
session.save(c);
session.flush();

21.3. ライフサイクルのカスケード

明示的に save() をコールするのは面倒ですが、カスケードを使って対処することができます
<set name="children" inverse="true" cascade="all">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>
これにより先ほどのコードを以下のように単純化します:
Parent p = (Parent) session.load(Parent.class, pid);
Child c = new Child();
p.addChild(c);
session.flush();
同様に Parent を保存または削除するときに、子を一つずつ反復して扱う必要はありません。以下は p を削除し、そしてデータベースからその子をすべて削除します。
Parent p = (Parent) session.load(Parent.class, pid);
session.delete(p);
session.flush();
しかし、以下のコードは:
Parent p = (Parent) session.load(Parent.class, pid);
Child c = (Child) p.getChildren().iterator().next();
p.getChildren().remove(c);
c.setParent(null);
session.flush();
データベースから c を削除しません。この場合、 p へのリンクを削除するのみで、NOT NULL 制約違反を引き起こします。明示的にChilddelete()する必要があります。
Parent p = (Parent) session.load(Parent.class, pid);
Child c = (Child) p.getChildren().iterator().next();
p.getChildren().remove(c);
session.delete(c);
session.flush();
今このケースでは実際に Child が親なしでは存在できないようになりました。そのため、コレクションから Child を取り除く場合、これも削除します。そのためには cascade="all-delete-orphan" を使わなければなりません。
<set name="children" inverse="true" cascade="all-delete-orphan">
    <key column="parent_id"/>
    <one-to-many class="Child"/>
</set>
コレクションのマッピングで inverse="true" と指定しても、コレクションの要素の反復によって、依然カスケードが処理されます。そのため、カスケードでオブジェクトを保存、削除、更新する必要がある場合は、それをコレクションに追加しなければなりません。単に setParent() を呼ぶだけでは不十分です。

21.4. カスケードと unsaved-value

Parent が、ある Session でロードされ、 UI のアクションで何らかの変更が加えられ、update() を呼んでこの変更を新しいセッションで永続化したいとします。Parent が子のコレクションを持ち、カスケード更新が有効になっているため、 Hibernate はどの子が新しくインスタンス化されたか、どれがデータベースの既存の行に相当するのかを知る必要があります。ParentChild の両方が Long 型の識別プロパティを生成したとします。Hibernate はどの子が新しいものかを決定するために識別プロパティの値を使います ( 「自動的な状態検出」 を参照してください)。Hibernate3 では、もはやunsaved-valueを明示的に特定する必要がなくなりました。
以下のコードは parentchild を更新し、 newChild を挿入します:
//parent and child were both loaded in a previous session
parent.addChild(child);
Child newChild = new Child();
parent.addChild(newChild);
session.update(parent);
session.flush();
これらは生成された識別子の場合には非常に良いのですが、割り当てられた識別子と複合識別子の場合はどうでしょうか?これは Hibernate が、ユーザーにより割り当てられた識別子を持つ新しくインスタンス化されたオブジェクトと、以前の Session でロードされたオブジェクトを区別できないため、さらに難しくなっています。この場合、Hibernate はタイムスタンプかバージョンのプロパティのどちらを使うか、二次キャッシュに問い合わせます。最悪の場合、行が存在するかどうかデータベースを見ます。

21.5. 結論

ここでは簡単に説明しただけなので若干、混乱してしまうかもしれません。しかし実際は、すべて問題なく動作します。ほとんどの Hibernate アプリケーションでは、多くの場面で親子パターンを使用します。
最初の段落で代替方法について触れました。上記のような問題は <composite-element> マッピングの場合は存在せず、にもかかわらずそれはまさに親子関係のセマンティクスを持ちます。残念ながら、複合要素クラスには2つの大きな制限があります: 1つは複合要素はコレクションを持つことができないこと、もう1つは一意の親ではないエンティティの子になるべきではないということです。

第22章 例: Weblog アプリケーション

22.1. 永続クラス

ここでは、永続クラスがウェブログと、ウェブログに掲示された項目を表しています。それらは標準の親子関係としてモデリングされますが、 set ではなく順序を持った bag を使用することにします:
package eg;

import java.util.List;

public class Blog {
    private Long _id;
    private String _name;
    private List _items;

    public Long getId() {
        return _id;
    }
    public List getItems() {
        return _items;
    }
    public String getName() {
        return _name;
    }
    public void setId(Long long1) {
        _id = long1;
    }
    public void setItems(List list) {
        _items = list;
    }
    public void setName(String string) {
        _name = string;
    }
}
package eg;

import java.text.DateFormat;
import java.util.Calendar;

public class BlogItem {
    private Long _id;
    private Calendar _datetime;
    private String _text;
    private String _title;
    private Blog _blog;

    public Blog getBlog() {
        return _blog;
    }
    public Calendar getDatetime() {
        return _datetime;
    }
    public Long getId() {
        return _id;
    }
    public String getText() {
        return _text;
    }
    public String getTitle() {
        return _title;
    }
    public void setBlog(Blog blog) {
        _blog = blog;
    }
    public void setDatetime(Calendar calendar) {
        _datetime = calendar;
    }
    public void setId(Long long1) {
        _id = long1;
    }
    public void setText(String string) {
        _text = string;
    }
    public void setTitle(String string) {
        _title = string;
    }
}

22.2. Hibernate のマッピング

XML マッピングはわかりやすくなっています。例えば、
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

    <class
        name="Blog"
        table="BLOGS">

        <id
            name="id"
            column="BLOG_ID">

            <generator class="native"/>

        </id>

        <property
            name="name"
            column="NAME"
            not-null="true"
            unique="true"/>

        <bag
            name="items"
            inverse="true"
            order-by="DATE_TIME"
            cascade="all">

            <key column="BLOG_ID"/>
            <one-to-many class="BlogItem"/>

        </bag>

    </class>

</hibernate-mapping>
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
    "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
    "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

    <class
        name="BlogItem"
        table="BLOG_ITEMS"
        dynamic-update="true">

        <id
            name="id"
            column="BLOG_ITEM_ID">

            <generator class="native"/>

        </id>

        <property
            name="title"
            column="TITLE"
            not-null="true"/>

        <property
            name="text"
            column="TEXT"
            not-null="true"/>

        <property
            name="datetime"
            column="DATE_TIME"
            not-null="true"/>

        <many-to-one
            name="blog"
            column="BLOG_ID"
            not-null="true"/>

    </class>

</hibernate-mapping>

22.3. Hibernate のコード

以下のクラスは、Hibernate でこれらのクラスを使ってできることをいくつか示しています。
package eg;

import java.util.ArrayList;
import java.util.Calendar;
import java.util.Iterator;
import java.util.List;

import org.hibernate.HibernateException;
import org.hibernate.Query;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;
import org.hibernate.cfg.Configuration;
import org.hibernate.tool.hbm2ddl.SchemaExport;

public class BlogMain {
    
    private SessionFactory _sessions;
    
    public void configure() throws HibernateException {
        _sessions = new Configuration()
            .addClass(Blog.class)
            .addClass(BlogItem.class)
            .buildSessionFactory();
    }
    
    public void exportTables() throws HibernateException {
        Configuration cfg = new Configuration()
            .addClass(Blog.class)
            .addClass(BlogItem.class);
        new SchemaExport(cfg).create(true, true);
    }
    
    public Blog createBlog(String name) throws HibernateException {
        
        Blog blog = new Blog();
        blog.setName(name);
        blog.setItems( new ArrayList() );
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        try {
            tx = session.beginTransaction();
            session.persist(blog);
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return blog;
    }
    
    public BlogItem createBlogItem(Blog blog, String title, String text)
                        throws HibernateException {
        
        BlogItem item = new BlogItem();
        item.setTitle(title);
        item.setText(text);
        item.setBlog(blog);
        item.setDatetime( Calendar.getInstance() );
        blog.getItems().add(item);
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        try {
            tx = session.beginTransaction();
            session.update(blog);
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return item;
    }
    
    public BlogItem createBlogItem(Long blogid, String title, String text)
                        throws HibernateException {
        
        BlogItem item = new BlogItem();
        item.setTitle(title);
        item.setText(text);
        item.setDatetime( Calendar.getInstance() );
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        try {
            tx = session.beginTransaction();
            Blog blog = (Blog) session.load(Blog.class, blogid);
            item.setBlog(blog);
            blog.getItems().add(item);
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return item;
    }
    
    public void updateBlogItem(BlogItem item, String text)
                    throws HibernateException {
        
        item.setText(text);
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        try {
            tx = session.beginTransaction();
            session.update(item);
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
    }
    
    public void updateBlogItem(Long itemid, String text)
                    throws HibernateException {
    
        Session session = _sessions.openSession();
        Transaction tx = null;
        try {
            tx = session.beginTransaction();
            BlogItem item = (BlogItem) session.load(BlogItem.class, itemid);
            item.setText(text);
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
    }
    
    public List listAllBlogNamesAndItemCounts(int max)
                    throws HibernateException {
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        List result = null;
        try {
            tx = session.beginTransaction();
            Query q = session.createQuery(
                "select blog.id, blog.name, count(blogItem) " +
                "from Blog as blog " +
                "left outer join blog.items as blogItem " +
                "group by blog.name, blog.id " +
                "order by max(blogItem.datetime)"
            );
            q.setMaxResults(max);
            result = q.list();
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return result;
    }
    
    public Blog getBlogAndAllItems(Long blogid)
                    throws HibernateException {
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        Blog blog = null;
        try {
            tx = session.beginTransaction();
            Query q = session.createQuery(
                "from Blog as blog " +
                "left outer join fetch blog.items " +
                "where blog.id = :blogid"
            );
            q.setParameter("blogid", blogid);
            blog  = (Blog) q.uniqueResult();
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return blog;
    }
    
    public List listBlogsAndRecentItems() throws HibernateException {
        
        Session session = _sessions.openSession();
        Transaction tx = null;
        List result = null;
        try {
            tx = session.beginTransaction();
            Query q = session.createQuery(
                "from Blog as blog " +
                "inner join blog.items as blogItem " +
                "where blogItem.datetime > :minDate"
            );

            Calendar cal = Calendar.getInstance();
            cal.roll(Calendar.MONTH, false);
            q.setCalendar("minDate", cal);
            
            result = q.list();
            tx.commit();
        }
        catch (HibernateException he) {
            if (tx!=null) tx.rollback();
            throw he;
        }
        finally {
            session.close();
        }
        return result;
    }
}

第23章 例: いろいろなマッピング

この章では、さらに複雑な関連のマッピングをいくつか紹介します。

23.1. 雇用者/従業員

EmployerEmployee の関係を表す以下のモデルは、関連の表現に実際のエンティティクラス ( Employment ) を使います。同じ2つのグループに複数の期間雇用されるということがありえるからです。お金の値と従業員の名前をモデル化するためにコンポーネントを使っています。
ここでマッピングドキュメントの一例を挙げています:
<hibernate-mapping>
        
    <class name="Employer" table="employers">
        <id name="id">
            <generator class="sequence">
                <param name="sequence">employer_id_seq</param>
            </generator>
        </id>
        <property name="name"/>
    </class>

    <class name="Employment" table="employment_periods">

        <id name="id">
            <generator class="sequence">
                <param name="sequence">employment_id_seq</param>
            </generator>
        </id>
        <property name="startDate" column="start_date"/>
        <property name="endDate" column="end_date"/>

        <component name="hourlyRate" class="MonetaryAmount">
            <property name="amount">
                <column name="hourly_rate" sql-type="NUMERIC(12, 2)"/>
            </property>
            <property name="currency" length="12"/>
        </component>

        <many-to-one name="employer" column="employer_id" not-null="true"/>
        <many-to-one name="employee" column="employee_id" not-null="true"/>

    </class>

    <class name="Employee" table="employees">
        <id name="id">
            <generator class="sequence">
                <param name="sequence">employee_id_seq</param>
            </generator>
        </id>
        <property name="taxfileNumber"/>
        <component name="name" class="Name">
            <property name="firstName"/>
            <property name="initial"/>
            <property name="lastName"/>
        </component>
    </class>

</hibernate-mapping>
これは、SchemaExport で生成したテーブルスキーマです。
create table employers (
    id BIGINT not null, 
    name VARCHAR(255), 
    primary key (id)
)

create table employment_periods (
    id BIGINT not null,
    hourly_rate NUMERIC(12, 2),
    currency VARCHAR(12), 
    employee_id BIGINT not null, 
    employer_id BIGINT not null, 
    end_date TIMESTAMP, 
    start_date TIMESTAMP, 
    primary key (id)
)

create table employees (
    id BIGINT not null, 
    firstName VARCHAR(255), 
    initial CHAR(1), 
    lastName VARCHAR(255), 
    taxfileNumber VARCHAR(255), 
    primary key (id)
)

alter table employment_periods 
    add constraint employment_periodsFK0 foreign key (employer_id) references employers
alter table employment_periods 
    add constraint employment_periodsFK1 foreign key (employee_id) references employees
create sequence employee_id_seq
create sequence employment_id_seq
create sequence employer_id_seq

23.2. 作者/作業物

WorkAuthor そして Person の関係を表す以下のモデルを考えてみてください。WorkAuthor の関係を多対多関連で表しています。AuthorPerson の関係は一対一関連として表しています。他には AuthorPerson を拡張するという方法もあります。
以下のマッピングドキュメントはこのような関係を正確に表現しています:
<hibernate-mapping>

    <class name="Work" table="works" discriminator-value="W">

        <id name="id" column="id">
            <generator class="native"/>
        </id>
        <discriminator column="type" type="character"/>

        <property name="title"/>
        <set name="authors" table="author_work">
            <key column name="work_id"/>
            <many-to-many class="Author" column name="author_id"/>
        </set>

        <subclass name="Book" discriminator-value="B">
            <property name="text"/>
        </subclass>

        <subclass name="Song" discriminator-value="S">
            <property name="tempo"/>
            <property name="genre"/>
        </subclass>

    </class>

    <class name="Author" table="authors">

        <id name="id" column="id">
            <!-- The Author must have the same identifier as the Person -->
            <generator class="assigned"/> 
        </id>

        <property name="alias"/>
        <one-to-one name="person" constrained="true"/>

        <set name="works" table="author_work" inverse="true">
            <key column="author_id"/>
            <many-to-many class="Work" column="work_id"/>
        </set>

    </class>

    <class name="Person" table="persons">
        <id name="id" column="id">
            <generator class="native"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping>
このマッピングには4つのテーブルがあります:worksauthorspersons はそれぞれ、仕事、作者、人のデータを保持します。author_work は作者と作業物をリンクする関連テーブルです。以下は SchemaExport で生成したテーブルスキーマです:
create table works (
    id BIGINT not null generated by default as identity, 
    tempo FLOAT, 
    genre VARCHAR(255), 
    text INTEGER, 
    title VARCHAR(255), 
    type CHAR(1) not null, 
    primary key (id)
)

create table author_work (
    author_id BIGINT not null, 
    work_id BIGINT not null, 
    primary key (work_id, author_id)
)

create table authors (
    id BIGINT not null generated by default as identity, 
    alias VARCHAR(255), 
    primary key (id)
)

create table persons (
    id BIGINT not null generated by default as identity, 
    name VARCHAR(255), 
    primary key (id)
)

alter table authors 
    add constraint authorsFK0 foreign key (id) references persons
alter table author_work 
    add constraint author_workFK0 foreign key (author_id) references authors
alter table author_work
    add constraint author_workFK1 foreign key (work_id) references works

23.3. 顧客/注文/製品

この章では、 CustomerOrderLineItemProduct の関係を表すモデルを考えてみましょう。CustomerOrder は一対多の関連ですが、Order / LineItem / Product はどのように表現するべきでしょうか? この例では、LineItem を、OrderProduct の多対多関連を表現する関連クラスとしてマッピングしました。Hibernate ではこれを複合要素と呼びます。
このマッピングドキュメントは以下のようになります:
<hibernate-mapping>

    <class name="Customer" table="customers">
        <id name="id">
            <generator class="native"/>
        </id>
        <property name="name"/>
        <set name="orders" inverse="true">
            <key column="customer_id"/>
            <one-to-many class="Order"/>
        </set>
    </class>

    <class name="Order" table="orders">
        <id name="id">
            <generator class="native"/>
        </id>
        <property name="date"/>
        <many-to-one name="customer" column="customer_id"/>
        <list name="lineItems" table="line_items">
            <key column="order_id"/>
            <list-index column="line_number"/>
            <composite-element class="LineItem">
                <property name="quantity"/>
                <many-to-one name="product" column="product_id"/>
            </composite-element>
        </list>
    </class>

    <class name="Product" table="products">
        <id name="id">
            <generator class="native"/>
        </id>
        <property name="serialNumber"/>
    </class>

</hibernate-mapping>
customersordersline_itemsproducts はそれぞれ、顧客、注文、注文明細、製品のデータを保持します。 line_items は注文と製品をリンクする関連テーブルとしての役割も果たします。
create table customers (
    id BIGINT not null generated by default as identity, 
    name VARCHAR(255), 
    primary key (id)
)

create table orders (
    id BIGINT not null generated by default as identity, 
    customer_id BIGIN