Hibernate.orgCommunity Documentation

HIBERNATE - Relational Persistence for Idiomatic Java

Hibernate Reference Documentation

3.5.6-Final

Legal Notice

September 15, 2010


前書き
1. Tutorial
1.1. パート1 - 初めての Hibernate アプリケーション
1.1.1. Setup
1.1.2. 最初のクラス
1.1.3. マッピングファイル
1.1.4. Hibernate の設定
1.1.5. Maven によるビルド
1.1.6. スタートアップとヘルパ
1.1.7. オブジェクトのロードと格納
1.2. パート2 - 関連のマッピング
1.2.1. Person クラスのマッピング
1.2.2. 単方向 Set ベース関連
1.2.3. 関連を働かせる
1.2.4. 値のコレクション
1.2.5. 双方向関連
1.2.6. 双方向リンクの動作
1.3. パート3 - EventManager Web アプリケーション
1.3.1. 基本的な Servlet の記述
1.3.2. 処理と描画
1.3.3. デプロイとテスト
1.4. 要約
2. アーキテクチャ
2.1. 概観
2.2. インスタンスの状態
2.3. JMX との統合
2.4. JCA サポート
2.5. コンテキスト上のセッション
3. 設定
3.1. プログラム上の設定
3.2. SessionFactory を取得する
3.3. JDBC コネクション
3.4. オプション設定プロパティ
3.4.1. SQL 方言(Dialect)
3.4.2. 外部結合フェッチ
3.4.3. バイナリストリーム
3.4.4. ニ次キャッシュとクエリキャッシュ
3.4.5. クエリ言語の置き換え
3.4.6. Hibernate 統計
3.5. ロギング
3.6. NamingStrategy を選択
3.7. XML 設定ファイル
3.8. J2EE アプリケーションサーバーとの統合
3.8.1. トランザクション戦略設定
3.8.2. SessionFactory の JNDI への登録
3.8.3. JTA による現在のセッションコンテキストマネージメント
3.8.4. JMX デプロイメント
4. 永続クラス
4.1. 単純な POJO の例
4.1.1. 引数のないコンストラクタを実装する
4.1.2. 識別子プロパティを用意する(オプション)
4.1.3. final クラスにしない(オプション)
4.1.4. 永続フィールドに対するアクセサとミューテータを定義する(オプション)
4.2. 継承の実装
4.3. equals() と hashCode()の実装
4.4. 動的モデル
4.5. Tuplizer
4.6. EntityNameResolvers
5. 基本的な O/R マッピング
5.1. マッピング定義
5.1.1. Doctype
5.1.2. Hibernate-mapping
5.1.3. Class
5.1.4. id
5.1.5. Enhanced identifier generators
5.1.6. Identifier generator optimization
5.1.7. composite-id
5.1.8. discriminator
5.1.9. version(オプション)
5.1.10. timestamp(オプション)
5.1.11. property
5.1.12. many-to-one
5.1.13. one-to-one
5.1.14. natural-id
5.1.15. Component and dynamic-component
5.1.16. プロパティ
5.1.17. subclass
5.1.18. joined-subclass
5.1.19. union-subclass
5.1.20. join
5.1.21. Key
5.1.22. column と formula 要素
5.1.23. Import
5.1.24. Any
5.2. Hibernate の型
5.2.1. エンティティと値
5.2.2. 基本的な型
5.2.3. カスタム型
5.3. 1つのクラスに1つ以上のマッピング
5.4. バッククォートで囲んだ SQL 識別子
5.5. メタデータの代替手段
5.5.1. XDoclet マークアップの使用
5.5.2. JDK 5.0 アノテーションの使用
5.6. 生成プロパティ
5.7. Column read and write expressions
5.8. 補助的なデータベースオブジェクト
6. コレクションのマッピング
6.1. コレクションの永続化
6.2. コレクションのマッピング
6.2.1. コレクションの外部キー
6.2.2. コレクションの要素
6.2.3. インデックス付きのコレクション
6.2.4. 値のコレクションと多対多関連
6.2.5. 一対多関連
6.3. 高度なコレクションマッピング
6.3.1. ソートされたコレクション
6.3.2. 双方向関連
6.3.3. インデックス付きコレクションと双方向関連
6.3.4. 3項関連
6.3.5. Using an <idbag>
6.4. コレクションの例
7. 関連マッピング
7.1. イントロダクション
7.2. 単方向関連
7.2.1. Many-to-one
7.2.2. One-to-one
7.2.3. One-to-many
7.3. 結合テーブルを使った単方向関連
7.3.1. One-to-many
7.3.2. Many-to-one
7.3.3. One-to-one
7.3.4. Many-to-many
7.4. 双方向関連
7.4.1. 一対多/多対一
7.4.2. One-to-one
7.5. 結合テーブルを使った双方向関連
7.5.1. 一対多/多対一
7.5.2. 一対一
7.5.3. Many-to-many
7.6. より複雑な関連マッピング
8. コンポーネントのマッピング
8.1. 依存オブジェクト
8.2. 従属するオブジェクトのコレクション
8.3. Map のインデックスとしてのコンポーネント
8.4. 複合識別子としてのコンポーネント
8.5. 動的コンポーネント
9. 継承マッピング
9.1. 3つの戦略
9.1.1. クラス階層ごとのテーブル(table-per-class-hierarchy)
9.1.2. サブクラスごとのテーブル (table-per-subclass)
9.1.3. discriminator を用いた table-per-subclass
9.1.4. table-per-subclass と table-per-class-hierarchy の混合
9.1.5. 具象クラスごとのテーブル(table-per-concrete-class)
9.1.6. 暗黙的ポリモーフィズムを用いた table-per-concrete-class
9.1.7. 他の継承マッピングと暗黙的ポリモーフィズムの組み合わせ
9.2. 制限
10. オブジェクトを扱う
10.1. Hibernate におけるオブジェクトの状態
10.2. オブジェクトを永続状態にする
10.3. オブジェクトのロード
10.4. クエリ
10.4.1. クエリの実行
10.4.2. フィルタリングコレクション
10.4.3. クライテリアのクエリ
10.4.4. ネイティブ SQL のクエリ
10.5. 永続オブジェクトの修正
10.6. detached オブジェクトの修正
10.7. 自動的な状態検出
10.8. 永続オブジェクトの削除
10.9. 異なる二つのデータストア間でのオブジェクトのレプリケーション
10.10. セッションのフラッシュ
10.11. 連鎖的な永続化
10.12. メタデータの使用
11. Read-only entities
11.1. Making persistent entities read-only
11.1.1. Entities of immutable classes
11.1.2. Loading persistent entities as read-only
11.1.3. Loading read-only entities from an HQL query/criteria
11.1.4. Making a persistent entity read-only
11.2. Read-only affect on property type
11.2.1. Simple properties
11.2.2. Unidirectional associations
11.2.3. Bidirectional associations
12. Transactions and Concurrency
12.1. session スコープと transaction スコープ
12.1.1. 作業単位(Unit of work)
12.1.2. 長い対話
12.1.3. オブジェクト識別子を考える
12.1.4. 一般的な問題
12.2. データベーストランザクション境界
12.2.1. 管理されていない環境
12.2.2. JTA を使用する
12.2.3. 例外ハンドリング
12.2.4. トランザクションのタイムアウト
12.3. 楽観的同時実行制御
12.3.1. アプリケーションによるバージョンチェック
12.3.2. 拡張セッションと自動バージョニング
12.3.3. デタッチされたオブジェクトと自動バージョニング
12.3.4. 自動バージョニングのカスタマイズ
12.4. 悲観的ロック
12.5. コネクション開放モード
13. インターセプタとイベント
13.1. インターセプタ
13.2. イベントシステム
13.3. Hibernate の宣言的なセキュリティ
14. バッチ処理
14.1. バッチ挿入
14.2. バッチ更新
14.3. StatelessSession インターフェース
14.4. DML スタイルの操作
15. HQL: Hibernate クエリ言語
15.1. 大文字と小文字の区別
15.2. from 節
15.3. 関連と結合
15.4. 結合構文の形式
15.5. 識別子プロパティの参照
15.6. Select 節
15.7. 集約関数
15.8. ポリモーフィズムを使ったクエリ
15.9. where 節
15.10. Expressions 式
15.11. order by 節
15.12. group by 節
15.13. 副問い合わせ
15.14. HQL の例
15.15. 大量の UPDATE と DELETE
15.16. Tips & Tricks
15.17. コンポーネント
15.18. 行値コンストラクタ構文
16. Criteria クエリ
16.1. Criteria インスタンスの作成
16.2. リザルトセットの絞込み
16.3. 結果の整列
16.4. 関連
16.5. 関連の動的フェッチ
16.6. クエリの例
16.7. 射影、集約、グループ化
16.8. クエリおよびサブクエリの分離
16.9. 自然識別子によるクエリ
17. ネイティブ SQL
17.1. Using a SQLQuery
17.1.1. スカラーのクエリ
17.1.2. エンティティのクエリ
17.1.3. 関連とコレクションの操作
17.1.4. 複数エンティティの取得
17.1.5. 管理されていないエンティティの取得
17.1.6. 継承の制御
17.1.7. パラメータ
17.2. 名前付き SQL クエリ
17.2.1. 列と列の別名を明示的に指定するために return-property を使う
17.2.2. 問い合わせするためにストアドプロシージャを使う
17.3. 作成、更新、削除のためのカスタム SQL
17.4. ロードのためのカスタム SQL
18. データのフィルタリング
18.1. Hibernate のフィルタ
19. XML マッピング
19.1. XML データでの作業
19.1.1. XML とクラスのマッピングを同時に指定する
19.1.2. XML マッピングだけを指定する
19.2. XML マッピングのメタデータ
19.3. XML データを扱う
20. パフォーマンスの改善
20.1. フェッチ戦略
20.1.1. 遅延関連の働き
20.1.2. フェッチ戦略のチューニング
20.1.3. 単一端関連プロキシ
20.1.4. コレクションとプロキシの初期化
20.1.5. バッチフェッチの使用
20.1.6. サブセレクトフェッチの使用
20.1.7. Fetch profiles
20.1.8. 遅延プロパティフェッチの使用
20.2. 第2レベルキャッシュ
20.2.1. キャッシュのマッピング
20.2.2. read only 戦略
20.2.3. read/write 戦略
20.2.4. 厳密ではない read/write 戦略
20.2.5. transactional 戦略
20.2.6. Cache-provider/concurrency-strategy compatibility
20.3. キャッシュの管理
20.4. クエリキャッシュ
20.4.1. Enabling query caching
20.4.2. Query cache regions
20.5. コレクションのパフォーマンスの理解
20.5.1. 分類
20.5.2. 更新にもっとも効率的なコレクション list、map、idbag、set
20.5.3. inverse コレクションにもっとも最適な bag と list
20.5.4. 一括削除
20.6. パフォーマンスのモニタリング
20.6.1. SessionFactory のモニタリング
20.6.2. メトリクス
21. ツールセットガイド
21.1. スキーマの自動生成
21.1.1. スキーマのカスタマイズ
21.1.2. ツールの実行
21.1.3. プロパティ
21.1.4. Ant を使用する
21.1.5. インクリメンタルなスキーマ更新
21.1.6. インクリメンタルなスキーマ更新に対する Ant の使用
21.1.7. Schema validation
21.1.8. スキーマのバリデーションに Ant を使用します
22. 例: 親/子供
22.1. コレクションに関する注意
22.2. 双方向一対多
22.3. ライフサイクルのカスケード
22.4. カスケードと unsaved-value
22.5. 結論
23. 例: Weblog アプリケーション
23.1. 永続クラス
23.2. Hibernate のマッピング
23.3. Hibernate のコード
24. 例: いろいろなマッピング
24.1. 雇用者/従業員
24.2. 作者/作品
24.3. 顧客/注文/製品
24.4. 種々雑多なマッピング例
24.4.1. 「型付けされた」一対一関連
24.4.2. 複合キーの例
24.4.3. 複合キー属性を共有する多対多
24.4.4. discrimination に基づく内容
24.4.5. 代替キーの関連
25. ベストプラクティス
26. Database Portability Considerations
26.1. Portability Basics
26.2. Dialect
26.3. Dialect resolution
26.4. Identifier generation
26.5. Database functions
26.6. Type mappings
References

Working with object-oriented software and a relational database can be cumbersome and time consuming in today's enterprise environments. Hibernate is an Object/Relational Mapping tool for Java environments. The term Object/Relational Mapping (ORM) refers to the technique of mapping a data representation from an object model to a relational data model with a SQL-based schema.

Hibernate は Java クラスからデータベーステーブルへのマッピング(及び Java データタイプから SQL データタイプへのマッピング)を行うだけでなくデータのクエリや検索機能も提供するため、 SQL や JDBC での手作業によるデータ処理を除き開発に要する時間を大幅に削減することが可能になります。

Hibernate の目標は、 開発者にとってのプログラミングにおける一般的なデータ永続性の作業の 95 % を軽減することです。 Hibernate データベース内でビジネスロジックを実現するストアドプロシージャのみを使用するデータ処理中心のアプリケーションに対しては最適ではないかもしれませんが、 Java ベースの中間層でのビジネスロジック及びオブジェクト指向のドメインモデルを使用する場合に最も役に立ちます。 Hibernate は開発者がベンダー固有の SQL コードの除去あるいはカプセル化を行う際に便利なため、 表形式の表現からオブジェクトのグラフへの結果セットの変換に関する一般的な作業に役立ちます。

Hibernate 及びオブジェクト/リレーショナルマッピング、 あるいは Java が不慣れな方は、 次の手順を行ってください。

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

  2. Read 2章アーキテクチャ to understand the environments where Hibernate can be used.

  3. Hibernate ディストリビューション内の eg/ ディレクトリ内を見てください。 シンプルなスタンドアローンのアプリケーションが含まれています。 ご使用の JDBC ドライバを lib/ ディレクトリにコピーしてから使用するデータベースに対して正しい値を指定するよう etc/hibernate.properties を編集します。 ディストリビューションディレクトリ内のコマンドプロンプトから、 ant eg (Ant を使用)と入力するか、 Windows 環境の場合は build eg と入力します。

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

  5. よくある質問とその答え (FAQ) は Hibernate ウェブサイトでご覧ください。

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

  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) スィート製品の重要なコンポーネントになります。

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

重要項目

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

注意

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

仮に小さなデータベースアプリケーションが必要だとしましょう。そのアプリケーションには出席したいイベントと、そのイベントのホストについての情報を格納するものとします。

注意

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

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

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


<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>
    <name
>First Hibernate Tutorial</name>

    <build>
         <!-- we dont want the version to be part of the generated war file name -->
         <finalName
>${artifactId}</finalName>
    </build>

    <dependencies>
        <dependency>
            <groupId
>org.hibernate</groupId>
            <artifactId
>hibernate-core</artifactId>
        </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>
        </dependency>

        <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
        <dependency>
            <groupId
>org.slf4j</groupId>
            <artifactId
>slf4j-simple</artifactId>
        </dependency>

        <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
        <dependency>
            <groupId
>javassist</groupId>
            <artifactId
>javassist</artifactId>
        </dependency>
    </dependencies>

</project
>

ティップ

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

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

次にデータベースに格納するイベントを表すクラスを作成します。

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

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

id プロパティは、ある特定のイベントに対するユニークな識別子の値を保持します。 Hibernate の完全な機能を使いたければ、すべての永続エンティティクラス (それほど重要ではない依存クラスというものもあります) にこのような識別子プロパティが必要になります。事実上ほとんどのアプリケーション ( 特に web アプリケーション) では、識別子でオブジェクトを区別する必要があるため、これは制限というよりも特徴であると考えるべきです。しかし通常オブジェクトの ID を操作するようなことはしません。そのためセッターメソッドは private にするべきです。 Hibernate だけがオブジェクトがセーブされたときに識別子へ値を代入します。 Hibernate が(public, private, protected)フィールドに直接アクセスできるのと同様に、 public, private, protected のアクセサメソッドにアクセスできるということがわかるでしょう。選択はあなたに任されているので、あなたのアプリケーションの設計に合わせることができます。

引数のないコンストラクタはすべての永続クラスに必須です。これは Hibernate が Java のリフレクションを使って、オブジェクトを作成しなければならないためです。コンストラクタを private にすることは可能ですが、実行時のプロキシ生成と、バイトコード操作なしの効率的なデータの抽出には、 package 可視性が必要です。

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

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 が非常に洗練されていることに注目してください。この DTD は、エディタや IDE での XML マッピング要素と属性のオートコンプリーション機能に利用できます。また DTD ファイルをテキストエディタで開けてみてください。というのも、すべての要素と属性を概観し、コメントやデフォルトの値を見るには一番簡単な方法だからです。 Hibernate は、 web から DTD ファイルをロードせずに、まずアプリケーションのクラスパスからこれを探し出そうとすることに注意してください。 DTD ファイルは Hibernate ディストリビューションの src/ ディレクトリと同様、hibernate3.jar にも含まれています。

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
>

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

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

最後にクラスの永続プロパティの宣言をマッピングファイルに含めます。デフォルトでは、クラスのプロパティは永続と見なされません:



<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 属性をも欠いている点です。マッピングファイルで宣言して使う type は、おわかりかもしれませんが Java のデータ型ではありません。 SQL データベースの型でもありません。これは Hibernateマッピング型 と呼ばれる、 Java から SQL データの型へまたは SQL から Java データ型へ翻訳するコンバータです。繰り返しになりますが、 Hibernate は type 属性がマッピングファイル内になければ、正しいコンバージョンとマッピング型を自分で解決しようとします。 (Javaクラスのリフレクションを使った)この自動検知は、場合によってはあなたが期待または必要とするデフォルト値にならないかもしれません。 date プロパティの場合がそうでした。 Hibernate はこの( java.util.Date の)プロパティを SQL の date , timestamp , time のうち、どのカラムにマッピングするべきなのかわかりません。 timestamp コンバータでプロパティをマッピングすることにより、完全な日時を保存します。

ティップ

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

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

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

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

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

注意

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

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
>

注意

この XML の設定が異なる DTD を使うことに注意してください。

特定のデータベースを受け持つグローバルファクトリである Hibernate の SessionFactory を設定します。もし複数のデータベースがある場合には、 (スタートアップを簡単にするため)通常いくつかの設定ファイル内で、いくつかの <session-factory> を使う設定にしてください。

最初の4つの property 要素は JDBC コネクションに必要な設定を含んでいます。 dialect という名前の property 要素は、 Hibernate が生成する特定の SQL 方言を指定します。

ティップ

In most cases, Hibernate is able to properly determine which dialect to use. See 「Dialect resolution」 for more information.

永続的なコンテキストに対する Hibernate のセッションの自動管理は、後の例ですぐにわかるように、役に立つことでしょう。 hbm2ddl.auto オプションはデータベーススキーマの自動生成を on にします。これは直接データベースに対して生成されます。当然(config オプションを削除して) off にしたり、 SchemaExport という Ant タスクの助けを借りてファイルにリダイレクトしたりできます。最後に永続クラスのためのマッピングファイルを設定に追加します。

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

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

[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] ------------------------------------------------------------------------

さて Event オブジェクトをロードしたり格納したりする準備ができました。しかしまずはインフラストラクチャのコードを書いて、セットアップを完了する必要があります。まずは Hibernate をスタートアップしなければなりません。このスタートアップには、グローバルの SessionFactory オブジェクトを生成して、それをアプリケーションのコードでアクセスしやすい場所に格納することが含まれます。 org.hibernate.SessionFactory は新しく org.hibernate.Session をオープンすることができます。 org.hibernate.Session はシングルスレッドの作業単位(Unit of Work)を表現します。それに対し org.hibernate.SessionFactory はスレッドセーフのグローバルオブジェクトであり、一度だけインスタンス化されます。

ここでスタートアップを行い、便利に org.hibernate.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;
    }
}

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

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

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

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

チュートリアルのインフラは完全です。 Hibernate を使って実際の作業をする準備が整いました。

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

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

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

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

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

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

作業単位 (Unit of Work) の範囲に関して、 Hibernate の org.hibernate.Session は1つまたはいくつかのデータベースオペレーションを実行するために使用されるべきでしょうか?上記の例は、1つのオペレーションで1つの org.hibernate.Session を使用します。これは純粋な偶然で、例はその他のアプローチを示すほど込み入っていません。 Hibernate の org.hibernate.Session の範囲は柔軟ですが、 全ての データベースオペレーションのために新しい Hibernate org.hibernate.Session を使用するようにアプリケーションをデザインするべきではありません。従って、もしそれを以下の (普通の) 例で何度か見たとしても、アンチパターンである オペレーション毎の Session を考慮してください。実際の (ウェブ) アプリケーションは、このチュートリアルで後に見ることができます。

See 12章Transactions and Concurrency for more information about transaction handling and demarcation. The previous example also skipped any error handling and rollback.

To run this, we will make use of the Maven exec plugin to call our class with the necessary classpath setup: mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"

注意

You may need to perform mvn compile first.

コンパイルすると、 Hibernate がスタートし、設定によりますが、多くのログ出力があるはずです。その最後には以下の行があるでしょう:

[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)

This is the INSERT executed by Hibernate.

To list stored events an option is added to the main method:

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

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

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

永続エンティティクラスをテーブルにマッピングしました。さらにこの上にいくつかのクラスの関連を追加しましょう。まず初めにアプリケーションに人々を追加し、彼らが参加するイベントのリストを格納します。

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

public class Person {


    private Set events = new HashSet();
    public Set getEvents() {
        return events;
    }
    public void setEvents(Set events) {
        this.events = events;
    }
}

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


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

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

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

異なる作業単位 (Unit of Work) で人々とイベントをロードすることも当然できます。そうでなければ、永続状態にないとき(以前に永続であったなら、この状態を 分離(detached) と呼びます)、 org.hibernate.Session の外部でオブジェクトを修正します。分離されるときにはコレクションを変更することも可能です:

    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 の呼び出しは分離オブジェクトを再び永続化します。これは、新しい作業単位 (Unit of Work) にバインドすると言えるでしょう。そのため分離の間に加えられたどのような修正もデータベースにセーブできます。エンティティオブジェクトのコレクションへの修正(追加・削除)も同様にセーブできます。

これは今はあまり使いみちがありませんが、自分のアプリケーションの設計に組み込むことができる重要なコンセプトです。それではこのエクササイズの最後に、 EventManager のメインメソッドに新しいアクションを追加してコマンドラインから呼び出してみましょう。人やイベントの識別子が必要なら、 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 のようなものです。このようなクラスを 値型 と言います。このインスタンスは特定のエンティティに 依存 します。この型のインスタンスは独自の ID を持ちませんし、エンティティ間で共有されることもありません (ファーストネームが同じだったとしても、2人の人は同じ firstname オブジェクトを参照しません)。値型はもちろん JDK 内に見つかりますが、それだけではなく (実際、 Hibernate アプリケーションにおいてすべての JDK クラスは値型と見なせます)、 例えば AddressMonetaryAmount のような独自の依存クラスを書くこともできます。

値型のコレクションを設計することもできます。これは他のエンティティへの参照のコレクションとは概念的に非常に異なりますが、 Java ではほとんど同じように見えます。

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

    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 の部分ですが、 Hibernate にこのコレクションが他のエンティティへの参照を含まず、 string 型の要素のコレクションを含むことを教えます(小文字の名前 (string) は Hibernate のマッピング型またはコンバータであるということです)。繰り返しますが、set 要素の table 属性は、コレクションのためのテーブル名を指定します。 key 要素はコレクションテーブルの外部キーカラム名を定義します。 element 要素の column 属性は string の値が実際に格納されるカラムの名前を定義します。

更新したスキーマを見てください:

  _____________        __________________
 |             |      |                  |       _____________
 |   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   |
                                                |_____________|
 

コレクションテーブルの主キーは、実際は両方のカラムを使った複合キーであることがわかります。これは人ごとに E メールアドレスが重複できないということで、 Java の set に要求されるセマンティクスそのものです。

以前人とイベントを関連づけたときと全く同じように、今や試しにコレクションに要素を追加することができるようになりました。 両方とも 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();
    }

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

次に双方向関連をマッピングします。 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="events.Person"/>
        </set
>

ご覧のとおり、いずれのマッピングドキュメント (XMLファイル) でも、普通の set マッピングを使っています。 keymany-to-many のカラム名が、両方のマッピングドキュメントで入れ替えになっていることに注目してください。ここで最も重要な追加項目は、 Event のコレクションマッピングの set 要素にある inverse="true" 属性です。

この指定の意味は、2つの間のエンティティ間のリンクについての情報を探す必要があるとき、 Hibernate は反対側のエンティティ、つまり Person クラスから探すということです。一度2つのエンティティ間の双方向リンクがどのように作成されるかがわかれば、これを理解することはとても簡単です。

まず、 Hibernate が通常の Java のセマンティクスに影響を及ぼさないことを心に留めておいてください。私たちは、単方向の例としてどのように PersonEvent の間のリンクを作成したでしょうか? Person のインスタンスのイベントへの参照のコレクションに Event のインスタンスを追加しました。そのためこのリンクを双方向にしたければ、当たり前ですが反対側にも同じことをしなければなりません。 Event のコレクションに Person への参照を追加するということです。この「両側でリンクを設定すること」は絶対に必要なので、決して忘れないでください。

多くの開発者は慎重にプログラムするので、エンティティの両側に正しく関連を設定するリンク管理メソッドを作成します。例えば 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);
    }

コレクションのゲットとセットメソッドが現在 protected になっていることに注意してください。これは同じパッケージのクラスやサブクラスのメソッドは依然アクセスが可能ですが、 (ほとんど) そのパッケージ外のどのクラスでも直接そのコレクションを台無しにすることを防ぎます。おそらく反対側のコレクションにも同じことをした方がいいでしょう。

inverse マッピング属性とはいったい何でしょうか?開発者と Java にとっては、双方向リンクは単に両側の参照を正しく設定するということです。しかし Hibernate は(制約違反を避けるために) SQL の INSERTUPDATE 文を正確に変更するための十分な情報を持っていないので、双方向関連プロパティを扱うための何らかの助けを必要とします。関連の片側を inverse に設定することで、 Hibernate は基本的には設定した側を無視し、反対側の として考えます。これだけで、 Hibernate は方向を持つナビゲーションモデルを SQL データベーススキーマへ変換するときのすべての問題にうまく対処できます。覚えておかなければならないルールは簡単です。双方向関連は必ず片側を inverse にする必要があるということです。一対多関連ではそれは多側でなければなりません。多対多関連ではどちら側でも構いません。どちらでも違いはありません。

Hibernate の Web アプリケーションは、スタンドアローンのアプリケーションのように SessionTransaction を使用します。しかしいくつかの一般的なパターンが役立ちます。ここで EventManagerServlet を作成します。このサーブレットは、データベースに格納した全てのイベントをリストにでき、さらに HTML フォームから新しいイベントを入力できるものです。

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

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

これは session-per-request というパターンです。 Servlet がリクエストを受け取ると、 SessionFactorygetCurrentSession() の最初の呼び出しで、 Hibernate の新しい Session が開かれます。そのときデータベーストランザクションが開始されます。データの読み書きに関わらず、すべてのデータアクセスはトランザクション内で行います(アプリケーション内ではオートコミットモードを使用しません)。

全てのデータベースオペレーションで新しい Hibernate Session を使用 しないでください 。全てのリクエストで機能する、1つの Hibernate Session を使用してください。自動的に現在の Java スレッドにバインドされるので、 getCurrentSession() を使用してください。

次に、リクエストのアクションは処理され、レスポンスである HTML が描画されます。これについてはすぐに説明します。

最後にリクエストの処理と HTML 描画が完了したときに、作業単位 (Unit of Work) を終了します。もし処理や描画中に問題が発生した場合、例外が送出されててデータベーストランザクションをロールバックします。これで session-per-request パターンが完了します。全てのサーブレットにトランザクション境界のコードを書く代わりに、サーブレットフィルタに記述することも可能です。 Open Session in View と呼ばれるこのパターンについては、 Hibernate の Web サイトや Wiki を参照してください。サーブレットではなく JSP で HTML 描画をしようとすると、すぐにこのパターンについての情報が必要になるでしょう。

では、リクエストの処理とページの描画を実装します。

        // 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 を参照してください。

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


<?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 ファイルを Tomcat の webapp ディレクトリにコピーしてください。

注意

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

一度デプロイして Tomcat を起動すれば、 http://localhost:8080/hibernate-tutorial/eventmanager でアプリケーションへのアクセスが可能です。最初のリクエストが作成したサーブレットに渡ったときに、 Tomcat のログで Hibernate の初期化処理を確認してください ( HibernateUtil 内の静的初期化ブロックが呼ばれています)。また、例外が発生したなら詳細を確認してください。

Hibernate アーキテクチャの(非常に)高いレベルからのビュー:

We do not have the scope in this document to provide a more detailed view of all the runtime architectures available; Hibernate is flexible and supports several different approaches. We will, however, show the two extremes: "minimal" architecture and "comprehensive" architecture.

この図は Hibernate が、アプリケーションに対して永続化サービス (と永続オブジェクト)を提供するために、データベースと設定データを使うことを示しています。

The "minimal" architecture has the application provide its own JDBC connections and manage its own transactions. This approach uses a minimal subset of Hibernate's APIs:

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

以下は、図に含まれるオブジェクトの定義です:

SessionFactory (org.hibernate.SessionFactory)

A threadsafe, immutable cache of compiled mappings for a single database. A factory for Session and a client of ConnectionProvider, SessionFactory can hold an optional (second-level) cache of data that is reusable between transactions at a process, or cluster, level.

Session (org.hibernate.Session)

A single-threaded, short-lived object representing a conversation between the application and the persistent store. It wraps a JDBC connection and is a factory for Transaction. Session holds a mandatory first-level cache of persistent objects that are used when navigating the object graph or looking up objects by identifier.

Persistent objects と Collections

永続化状態とビジネス機能を持つ、短命でシングルスレッドのオブジェクト。これは通常の JavaBeans/POJO のこともありますが、特徴的なことは、その時点での(ただ1つの) Session と関連していることです。 Session がクローズされるとすぐに、それらは切り離されて他のアプリケーション層から自由に使うことができます(例えばデータトランスファオブジェクトとして、プレゼンテーション層から、またはプレゼンテーション層へ直接使用できます)。

Transient と detached な objects と Collections

現時点では Session と関連していない、永続クラスのインスタンス。すでにアプリケーション側でインスタンス化されていて、まだ永続化されていないか、クローズされた Session でインスタンス化されたかのどちらかです。

Transaction (org.hibernate.Transaction)

(オプション) 原子性を持つ作業単位 (Unit of Work) を指定するために、アプリケーションが使用する、シングルスレッドで短命なオブジェクト。下に位置する JDBC 、 JTA 、 CORBA トランザクションからアプリケーションを抽象化します。 Session は、時にはいくつかの Transaction をまたがるかもしれません。しかし、下の層の API を使うにせよ、 Transaction を使うにせよ、トランザクション境界を設定することは、決してオプションではありません。

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(オプション) JDBC コネクション(とそのプール)のファクトリ。下の層に位置する DatasourceDriverManager からアプリケーションを抽象化します。アプリケーションには公開されませんが、開発者が継承または実装することは可能です。

TransactionFactory (org.hibernate.TransactionFactory)

(オプション) Transaction インスタンスのファクトリ。アプリケーションには公開されませんが、開発者が継承または実装することは可能です。

Extension Interfaces

Hibernate は、永続層の振る舞いをカスタマイズするために、多くのオプション拡張インタフェースを用意しています。詳細は API ドキュメントを参照してください。

「軽い」アーキテクチャでは、アプリケーションは直接 JTA や JDBC と対話するために、 TransactionTransactionFactoryConnectionProvider の API をバイパスします。

JMX は Java コンポーネント管理の J2EE 標準です。 JMX 標準サービスを通して、 Hibernate は管理されます。ディストリビューションの中に org.hibernate.jmx.HibernateService という MBean 実装を用意しています。

JBoss アプリケーションサーバー上に Hibernate を JMX サービスとしてデプロイする方法の例としては、 JBoss ユーザーガイドを参照してください。 JBoss アプリケーションサーバーにおいて、 JMX を使ってデプロイすると、次のメリットが得られます:

これらのオプションについての詳細な情報は、 JBoss アプリケーションサーバーユーザーガイドを参考にしてください。

Another feature available as a JMX service is runtime Hibernate statistics. See 「Hibernate 統計」 for more information.

Hibernate を使ったアプリケーションは、ほとんど、なんらかの形で「コンテキスト上の」セッションが必要になります。「コンテキスト上のセッション」は、特定のコンテキストのスコープのなかで有効なセッションのことです。しかし、通常アプリケーションごとにコンテキストを構成するものの定義は異なります。しかも、異なる複数のコンテキストは、現時点に対して異なるスコープを定義します。バージョン3.0より前の Hibernate では、自作の ThreadLocal ベースの「コンテキスト上のセッション」を利用するか、 HibernateUtil のようなヘルパークラスを利用するか、 proxy/interception ベースの「コンテキスト上のセッション」を提供する (Spring や Pico のような)サードパーティのフレームワークを利用するかのいずれかでした。

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

しかし、バージョン 3.1 からは、 SessionFactory.getCurrentSession() の後の処理が、プラガブルになりました。これを受けて、現在のセッションを定義するスコープとコンテキストのプラガビリティを可能にするために、新しい拡張インタフェース ( org.hibernate.context.CurrentSessionContext ) と新しい構成パラメータ ( hibernate.current_session_context_class ) が追加されました。

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

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

hibernate.current_session_context_class 設定パラメータは、 org.hibernate.context.CurrentSessionContext のどの実装を使うかを指定します。下位互換性のため、このパラメータが設定されず org.hibernate.transaction.TransactionManagerLookup が設定されていた場合、 Hibernate は org.hibernate.context.JTASessionContext を使うことに注意してください。通常このパラメータの値には、3つの実装の中から使用する実装クラスの名前を直接指定します。しかし、"jta"、 "thread"、 "managed"というそれぞれの省略名も用意されています。

Hibernate は様々な環境で動作するようにデザインされているため、非常に多くの設定要素があります。幸いなことに、 Hibernate は、公開されているパッケージの etc/ フォルダの hibernate.properties に、ほとんどの設定要素の適切なデフォルト値が記述されています。この hibernate.properties をクラスパスに設定し、設定要素をカスタマイズするだけです。

org.hibernate.cfg.Configuration のインスタンスは、 Java の型と SQL データベースのマッピング情報をすべて持っています。 Configuration は、(不変の) 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つではありません。さまざまなオプションを用意しています:

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

org.hibernate.cfg.Configuration は、起動時にだけあるオブジェクトであり、一度 SessionFactory を生成した後は、破棄されることを意図しています。

通常、開発者は org.hibernate.SessionFactory を生成し、 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 を使います:


Hibernate のコネクションプールアルゴリズムは非常に初歩的なものです。これはすぐに始められるようにと用意されたもので、 製品として使用することを意図していません 。また、パフォーマンスのテストのためのものでもありません。最高のパフォーマンスと安定性を持ったプールを実現したければ、サードパーティのツールをお勧めします。 hibernate.connection.pool_size プロパティと適切なコネクションプールの設定を置き換えてください。これにより Hibernate のインターナルプールを無効にします。例えば次のように C3P0 を使います。

C3P0 はオープンソース JDBC コネクションプールで、 Hibernate の lib ディレクトリにあります。もし、 hibernate.c3p0.* プロパティをセットすれば、 Hibernate は、 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 を設定し、アプリケーションサーバーからコネクションを取得するようにしてください。 javax.sql.Datasource を JNDI に登録します。そしてプロパティを以下のように設定してください:


アプリケーションサーバーから提供された 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" プロパティ名によって与えられます。例えば、 charSet を設定したい場合は、 hibernate.connection.charSet を使います。

JDBC コネクションを取得する戦略を持つ独自のプラグインを定義する場合は、 org.hibernate.connection.ConnectionProvider インターフェースを実装してください。そして、実装クラスを hibernate.connection.provider_class に設定してください。

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

表3.3 Hibernate 設定プロパティ

プロパティ名意味
hibernate.dialect Hibernate のクラス名 org.hibernate.dialect.Dialect が入ります。これはリレーショナルデータベースごとに最適化された SQL を生成します。

full.classname.of.Dialect

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

hibernate.show_sql 発行されたすべての 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 バッチサイズを指定します。

例: 推奨する値は 4 , 8 , 16 です。

hibernate.default_entity_mode Sets a default mode for entity representation for all sessions opened from this SessionFactory

dynamic-map, dom4j, pojo

hibernate.order_updates 項目が更新されたときに、別の SQL で主キーを更新することを強制します。この場合、同時実行可能なシステムでは、まれにデッドロックが発生する可能性があります。

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

true | false

hibernate.jdbc.factory_class カスタム org.hibernate.jdbc.Batcher を選びます。ほとんどのアプリケーションに、この設定プロパティは必要ありません。

classname.of.BatcherFactory

hibernate.jdbc.use_scrollable_resultset Hibernate による JDBC2 のスクロール可能なリザルトセットの使用を有効にします。このプロパティは、ユーザーによって提供された JDBC コネクションを使用している場合のみ必要で、そうでなければ Hibernate はコネクションメタデータを使用します。

true | false

hibernate.jdbc.use_streams_for_binary 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 に提供する独自の 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 コネクションをリリースするかを指定します。デフォルトではセッションが明示的にクローズまたは切断されてもコネクションは保持します。アプリケーションサーバーの JTA データソースの場合、すべての JDBC コールの後、強制的にコネクションをリリースするために after_statement を使ってください。非 JTA コネクションの場合、各トランザクションが終了したときに after_transaction を使い、コネクションをリリースしてください。 auto にすると、 JTA や CMT トランザクションの場合、 after_statement でクローズし、 JDBC トランザクションの場合、 after_transaction でクローズします。

auto (デフォルト) | on_close | after_transaction | after_statement

This setting only affects Sessions returned from SessionFactory.openSession. For Sessions obtained through SessionFactory.getCurrentSession, the CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions. See 「コンテキスト上のセッション」

hibernate.connection.<propertyName> JDBC プロパティ <propertyName>DriverManager.getConnection() に渡します。
hibernate.jndi.<propertyName> プロパティ <propertyName> を JNDI InitialContextFactory に渡します。



表3.7 その他のプロパティ

プロパティ名意味
hibernate.current_session_context_class Supply a custom strategy for the scoping of the "current" Session. See 「コンテキスト上のセッション」 for more information about the built-in strategies.

jta | thread | managed | custom.Class

hibernate.query.factory_class HQL パーサーの実装を選択します。

org.hibernate.hql.ast.ASTQueryTranslatorFactory or org.hibernate.hql.classic.ClassicQueryTranslatorFactory

hibernate.query.substitutions HQL と SQL のトークンをマッピングします。 (例えば、トークンは関数やリテラル名です)。

hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.auto SessionFactory を生成したときに、自動的にスキーマ DDL を有効にしデータベースに出力します。 create-drop の場合、 SessionFactory をクローズしたときに、データベーススキーマをドロップします。

validate | update | create | create-drop

hibernate.bytecode.use_reflection_optimizer

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

true | false

hibernate.bytecode.provider

Both javassist or cglib can be used as byte manipulation engines; the default is javassist.

e.g. javassist | cglib


hibernate.dialect プロパティには、使用するデータベースの正しい org.hibernate.dialect.Dialect のサブクラスを、必ず指定すべきです。しかし方言を指定すれば、 Hibernate は上述したプロパティのいくつかについて、より適切なデフォルト値を使います。そうすれば、それらを手作業で設定する手間が省けます。


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

Hibernate のログメッセージに慣れることを強くおすすめします。 Hibernate のログは読みやすく、できる限り詳細になるように努力されています。これは必須のトラブルシューティングデバイスです。以下に重要なログのカテゴリを示します:


Hibernate でアプリケーションを作成するときは、 org.hibernate.SQL カテゴリの debug を常に有効にしておいたほうが良いでしょう。代替方法として、 hibernate.show_sql プロパティを有効にする方法があります。

もう1つの方法は hibernate.cfg.xml という名前のファイルで十分な設定を指定する方法です。このファイルは hibernate.properties ファイルの代わりとなります。もし両方のファイルがあれば、プロパティが置き換えられます。

XML 設定ファイルは初期設定で CLASSPATH の root に配置してください。これが例です:


<?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 の どちらかを使えることを覚えておいてください。2つは同じもので、違うところといえば XML 構文を使うことの利点だけです。

XML 設定を使うことで、 Hibernate は以下のようにシンプルになります。

SessionFactory sf = new Configuration().configure().buildSessionFactory();

違う XML 設定ファイルを使うこともできます。

SessionFactory sf = new Configuration()

    .configure("catdb.cfg.xml")
    .buildSessionFactory();

Hibernate は J2EE 構造と統合するポイントをサポートしています:

環境に依存しますが、もしアプリケーションサーバーが "connection containment" の例外を出す場合、設定のオプション hibernate.connection.aggressive_release を true にしてください。

Hibernate Session API は、アーキテクチャ内のシステムの管轄であるあらゆるトランザクションに依存しません。もしコネクションプールの JDBC を直接使いたい場合、 JDBC API から トランザクションを呼ぶことができます。もし、 J2EE アプリケーションサーバーで動作させるなら、 Bean 管理トランザクションを使い、必要に応じて UserTransaction を JTA API から呼ぶことになるでしょう。

2つ(それ以上)の環境で互換性のあるコードを維持するために、オプションとして根本的なシステムをラッピングする Hibernate Transaction API を推奨します。 Hibernate 設定プロパティの hibernate.transaction.factory_class を設定することで、ある特定の Transaction クラスのインスタンスを持つことができます。

3つの基本的な(既にある)選択を挙げます:

自分自身のトランザクション戦略(例えば、 CORBA トランザクションサービス)を定義することもできます。

Hibernate のいくつかの機能(例えば、二次キャッシュ、 JTA によるコンテキストセッション等)は管理された環境の中の JTA TransactionManager へのアクセスを要求します。 J2EE がひとつのメカニズムに規格化されていないので、アプリケーションサーバーにおいて、 Hibernateが TransactionManager のリファレンスを取得する方法を明確にする必要があります。


JNDI に登録した Hibernate SessionFactory はファクトリのルックアップと新しい Session の作成を簡易化します。これは JNDI に登録された Datasource には関連せず、両方とも単に同じ登録を使うことに注意してください。

もし SessionFactory を JNDI ネームスペースに登録したい場合、特別な名前(例えば、 java:hibernate/SessionFactory )を hibernate.session_factory_name プロパティに使ってください。もしこのプロパティを省略した場合、 SessionFactory は JNDI に登録されません。(これは Tomcat のようなデフォルト実装で JNDI が読み取り専用の環境の場合は特に便利です。)

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章を参照してください。

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

SessionFactory を JNDI から取得するためには cfg.buildSessionFactory() 行をどこかで実行していなければなりません。あなたはこれを、 static 初期化ブロック内( HibernateUtil のような)か managed service として 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 ディレクトリに配置され、 JAR ファイルを拡張した .sar (service archive) でパッケージ化されます。同様に Hibernate パッケージも必要です。また、 Hibernate はサードパーティのライブラリも要求します。コンパイルした永続化クラスとそのマッピングファイルも同様にアーカイブ(.sarファイル)に入れます。エンタープライズ Bean (通常はセッション Bean )は自身の JAR ファイルを保持しますが、1回で(ホット)デプロイ可能なユニットのためにメインサービスアーカイブとしてこの EJB JAR ファイルを含めることができます。 JBoss AS のドキュメントに JXM サービスと EJB デプロイメントのより多くの情報があります。

永続クラスはビジネス上の問題のエンティティ(例えば、 E コマースアプリケーションの顧客や注文) を実装するアプリケーションのクラスです。永続クラスのすべてのインスタンスが永続状態であると見なされるわけではありません。インスタンスは逆に一時的(transient)であったり、分離状態(detached)であったりするかもしれません。

Plain Old Java Object (POJO)プログラミングモデルとしても知られるいくつかの単純なルールに従うなら、 Hibernate は最もよく働きます。しかしこれらのルールは難しいものではありません。実際 Hibernate3 は永続オブジェクトの性質にほとんど何の前提も置いていません。ドメインモデルは他の方法で表現することもできます。例えば Map インスタンスのツリーを使う方法があります。

Most Java applications require a persistent class representing felines. For example:

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

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

以下の条件の場合、 equals()hashCode() メソッドをオーバーライドしなければなりません、

Hibernate は、永続 ID (データベースの行)と、特定のセッションスコープ内に限定ですが Java ID とが等価であることを保証します。ですから異なるセッションで検索したインスタンスを組み合わせる場合、 Set に意味のあるセマンティクスを持たせようと思っているならすぐに equals()hashCode() を実装しなければなりません。

最も明白な方法は、両方のオブジェクトの識別子の値の比較によって equals()hashCode() を実装する方法です。値が同じなら、両者はデータベースの同じ行でなければならないため等しくなります。 (両者が Set に追加されても、 Set には1個の要素しかないことになります) 残念なことに、生成された識別子にはこのアプローチを使うことができません。 Hibernate は永続化されたオブジェクトへ識別子の値を代入するだけであり、新しく作成されたインスタンスはどのような識別子の値も持っていません。さらに、インスタンスがセーブされておらず、現在 Set の中にあれば、セーブするとオブジェクトへ識別子の値を代入することになります。もし equals()hashCode() が識別子の値に基づいているなら、ハッシュコードが変更されると Set の規約が破られます。この問題についての完全な議論は、 Hibernate のウェブサイトを見てください。これは 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;
    }
}

A business key does not have to be as solid as a database primary key candidate (see 「オブジェクト識別子を考える」). Immutable or unique properties are usually good candidates for a business key.

永続エンティティは、必ずしも実行時に POJO クラスや JavaBean オブジェクトで表現する必要はありません。 Hibernate は(実行時に MapMap を使う)動的モデルと、 DOM4J ツリーとしてのエンティティの表現もサポートします。このアプローチを使うと永続クラスを書かず、マッピングファイルだけを書くことになります。

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular SessionFactory using the default_entity_mode configuration option (see 表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();

動的なマッピングの利点は、エンティティクラスの実装を必要としないため、プロトタイピングに要するターンアラウンドタイムが早いということです。しかしコンパイル時の型チェックがないので、実行時に非常に多くの例外処理を扱わなければならないでしょう。 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 コネクション、トランザクション、その他のコンテキスト情報を共有します。これは2番目の Session では flush()close() を呼ぶ必要がないということ、そのためトランザクションとコネクションの管理を1番目の作業単位(Unit of Work)に任せることができるということです。

More information about the XML representation capabilities can be found in 19章XML マッピング.

org.hibernate.tuple.Tuplizer とそのサブインターフェースは、表現の org.hibernate.EntityMode を利用して、データ断片のある表現の管理に責任を持ちます。与えられたデータ断片をデータ構造として考えるなら、 Tuplizer はそのようなデータ構造をどのように作成するかを知り、そのようなデータ構造からどのように値を抽出し、注入するかを知っています。例えば POJO エンティティモードでは、対応する Tuplizer はコンストラクタを通して、 POJO をどのように作成するか、定義されたプロパティアクセサを使い、 POJO プロパティにどのようにアクセスするかを知ります。

Tuplizer には二つのハイレベルの型があります。それらは、org.hibernate.tuple.entity.EntityTuplizerorg.hibernate.tuple.component.ComponentTuplizer インターフェースで表現されます。 EntityTuplizer は上で述べたようなエンティティに関する契約の管理に責任を持ちます。一方、 ComponentTuplizer はコンポーネントに関する契約の管理に責任を持ちます。

ユーザーは独自の Tuplizer に差し替えることも可能です。おそらく dynamic-map entity-mode の際に 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();
            }
    }
}

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

/**

 * 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;
    }
    ...
}
        

In order to register an org.hibernate.EntityNameResolver users must either:

  1. Implement a custom Tuplizer, implementing the getEntityNameResolvers method.

  2. Register it with the org.hibernate.impl.SessionFactoryImpl (which is the implementation class for org.hibernate.SessionFactory) using the registerEntityNameResolver method.

オブジェクト/リレーショナルマッピングは通常 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 属性)。それらはスキーマエクスポートツールが出力するデータベーススキーマに影響を与えるものです。

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

前述したように、 Hibernate はまずクラスパス内で DTD を解決しようとします。 org.xml.sax.EntityResolver のカスタム実装を XML ファイルを読み込むための SAXReader に登録することによって、 DTD を解決します。このカスタムの EntityResolver は2つの異なるシステム ID 名前空間を認識します。

下記は、ユーザー名前空間を使った例です:


<?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 version "3.5.6-Final">
<!ENTITY today "September 15, 2010">

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

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

この要素にはいくつかオプション属性があります。 schema 属性と catalog 属性は、このマッピングが参照するテーブルが、この属性によって指定されたスキーマと(または)カタログに属することを指定します。この属性が指定されると、テーブル名は与えられたスキーマ名とカタログ名で修飾されます。これらの属性が指定されていなければ、テーブル名は修飾されません。 default-cascade 属性は、 cascade 属性を指定していないプロパティやコレクションに、どのカスケードスタイルを割り当てるかを指定します。 auto-import 属性は、クエリ言語内で修飾されていないクラス名を、デフォルトで使えるようにします。

<hibernate-mapping
         schem(1)a="schemaName"
         catal(2)og="catalogName"
         defau(3)lt-cascade="cascade_style"
         defau(4)lt-access="field|property|ClassName"
         defau(5)lt-lazy="true|false"
         auto-(6)import="true|false"
         packa(7)ge="package.name"
 />

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

class 要素を使って、永続クラスを宣言できます:

<class
        name="(1)ClassName"
        table=(2)"tableName"
        discri(3)minator-value="discriminator_value"
        mutabl(4)e="true|false"
        schema(5)="owner"
        catalo(6)g="catalog"
        proxy=(7)"ProxyInterface"
        dynami(8)c-update="true|false"
        dynami(9)c-insert="true|false"
        select(10)-before-update="true|false"
        polymo(11)rphism="implicit|explicit"
        where=(12)"arbitrary sql where condition"
        persis(13)ter="PersisterClass"
        batch-(14)size="N"
        optimi(15)stic-lock="none|version|dirty|all"
        lazy="(16)true|false"
        entity(17)-name="EntityName"
        check=(18)"arbitrary sql check condition"
        rowid=(19)"rowid"
        subsel(20)ect="SQL expression"
        abstra(21)ct="true|false"
        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 (オプション):遅延初期化プロキシに使うインターフェースを指定します。永続化するクラス名そのものを指定することも可能です。

8

dynamic-update (オプション、 デフォルトは false ):値が変更されたカラムだけを含む SQL の UPDATE 文を、実行時に生成することを指定します。

9

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

10

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

11

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

12

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

13

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

14

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

15

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

(16)

lazy (オプション): lazy="false" と設定することで、遅延フェッチができなくなります。

(17)

entity-name (optional - defaults to the class name): Hibernate3 allows a class to be mapped multiple times, potentially to different tables. It also allows entity mappings that are represented by Maps or XML at the Java level. In these cases, you should provide an explicit arbitrary name for the entity. See 「動的モデル」 and 19章XML マッピング for more information.

(18)

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

(19)

rowid (オプション): Hibernate は、それをサポートしているデータベースで ROWID と 呼ばれるものを使うことができます。例えば Oracle を使っているとき、このオプションに rowid を設定すれば、 Hiberante は update を高速化するために rowid という特別なカラムを使うことができます。 ROWID は詳細な実装であり、保存されたタプルの物理的な位置を表しています。

(20)

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

(21)

abstract (オプション): <union-subclass> 階層内の抽象スーパークラスにマークするために使います。

永続クラスの名前にインターフェースを指定してもまったく問題ありません。そのときは <subclass> 要素を使って、そのインターフェースを実装するクラスを定義してください。 static な内部クラスでも永続化できます。そのときは標準形式、例えば eg.Foo$Bar を使ってクラス名を指定してください。

mutable="false" 指定をした不変クラスは、アプリケーションによる更新や削除が出来ないことがあります。これにより、 Hibernate がパフォーマンスを少し改善します。

オプションの proxy 属性により、クラスの永続インスタンスの遅延初期化が可能になります。 Hibernate は最初に、指定したインターフェースを実装した CGLIB プロキシを返します。実際の永続オブジェクトはプロキシのメソッドを呼び出すときにロードします。以下の「遅延初期化のためのプロキシ」を参照してください。

暗黙的 ポリモーフィズムとは、次の二つを意味しています。一つはクラスのインスタンスが、スーパークラスや実装したインターフェース、またそのクラスを指定するクエリによって返されることで、もう一つはそのクラスのサブクラスのインスタンスが、そのクラス自身を指定したクエリによって返されることです。また、 明示的 ポリモーフィズムとは、次の二つを意味しています。一つはクラスのインスタンスが、そのクラスを明示的に指定したクエリによってのみ返されることで、もう一つはクラスを指定したクエリが、 <class> 要素の中で <subclass><joined-subclass> とマッピングされているサブクラスのインスタンスだけを返すことです。ほとんどの用途ではデフォルトの polymorphism="implicit" が適切です。明示的なポリモーフィズムは、2つの違ったクラスが同じテーブルにマッピングされているときに有用です (これによってテーブルカラムのサブセットを含む、「軽量な」クラスが可能になります)。

persister 属性を指定することで、クラスの永続化戦略をカスタマイズできます。例えば org.hibernate.persister.EntityPersister 自身のサブクラスを指定したり、また例えばストアドプロシージャコール、フラットファイルへシリアライズ、 LDAP などを通した永続性を実装する org.hibernate.persister.ClassPersister インターフェースの完全に新しい実装を提供できます。簡単な例として org.hibernate.test.CustomPersister を参照してください(これは Hashtable の「永続化」です)。

dynamic-updatedynamic-insert の設定はサブクラスに継承されません。そのため <subclass><joined-subclass> 要素を指定することも出来ます。これらの設定はパフォーマンスを向上させる事もありますが、落とすこともありますので、慎重に使用してください。

select-before-update の使用は通常パフォーマンスを落とします。もし Session へ分離インスタンスのグラフを再追加するなら、データベース更新のトリガを不必要に呼び出すのを避けるという点で、非常に有用です。

dynamic-update を有効にすれば、楽観ロック戦略を選ぶことになります:

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> は属性とネストしたマッピング属性のどちらでも利用できます。

マップされたクラスはデータベーステーブルの主キーカラムを定義 しなければなりません 。ほとんどのクラスにはインスタンスのユニークな識別子を保持する JavaBeans スタイルのプロパティも持っています。 <id> 要素は、そのプロパティから主キーカラムへのマッピングを定義します。

<id
        name="(1)propertyName"
        type="(2)typename"
        column(3)="column_name"
        unsave(4)d-value="null|any|none|undefined|id_value"
        access(5)="field|property|ClassName">
        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> という代替のマッピング定義があります。しかし他の用途への使用は全くおすすめできません。

オプションの <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 のドライバのバグにより無効にされていることに注意してください。

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

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

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

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

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

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

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

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

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

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

  • optimizer (optional - defaults to ): See 「Identifier generator optimization」

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

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

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

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


<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 を実装しなくてはなりません。この方法には、明らかにコードが重複するという不都合があります。

次の属性はマッピングした複合識別子を指定するために使用します:

We will describe a third, even more convenient approach, where the composite identifier is implemented as a component class in 「複合識別子としてのコンポーネント」. The attributes described below apply only to this alternative approach:

  • name (オプション、このアプローチでは必須): 複合識別子を保持するコンポーネントタイプのプロパティ(9章を参照してください)。

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

  • class (オプション - デフォルトはリフレクションにより決定されるプロパティの型): 複合識別子として使われるコンポーネントのクラス(次の節を見てください)。

この3つ目の方法は 識別子コンポーネント と呼び、ほとんどすべてのアプリケーションに対して推奨する方法です。

<discriminator> 要素は、 table-per-class-hierarchy マッピング戦略を使うポリモーフィックな永続化に必要であり、テーブルの識別カラムを定義します。識別カラムは、ある行に対して永続層がどのサブクラスをインスタンス化するかを伝えるマーカー値を含んでいます。以下のような型に制限されます: string , character , integer, byte , short , boolean , yes_no , true_false.

<discriminator
        column(1)="discriminator_column"
        type="(2)discriminator_type"
        force=(3)"true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary sql expression"
/>

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"/>

<version> 要素はオプションであり、テーブルがバージョンデータを含むことを示します。これは ロングトランザクション を使うつもりなら、特に役立ちます(以下を参照してください)。

<version
        column(1)="version_column"
        name="(2)propertyName"
        type="(3)typename"
        access(4)="field|property|ClassName"
        unsave(5)d-value="null|negative|undefined"
        genera(6)ted="never|always"
        insert(7)="true|false"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

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

2

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

3

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

4

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

5

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

6

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

7

insert (オプション - デフォルトは true ): SQLの insert 文にバージョンカラムを含めるべきかどうかを指定します。もしデータベースカラムのデフォルト値が 0 と定義されるときには、 false に設定すると良いでしょう。

バージョン番号は Hibernate の longintegershorttimestampcalendar 型のいずれかです。

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

オプションの <timestamp> 要素は、テーブルがタイムスタンプデータを含むことを示します。これはバージョン付けの代わりの方法として用意されています。タイムスタンプはもともと楽観的ロックにおける安全性の低い実装です。しかしアプリケーションはタイムスタンプを異なる用途で使うこともあるかもしれません。

<timestamp
        column(1)="timestamp_column"
        name="(2)propertyName"
        access(3)="field|property|ClassName"
        unsave(4)d-value="null|undefined"
        source(5)="vm|db"
        genera(6)ted="never|always"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

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

2

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

3

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

4

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

5

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

6

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

<property> 要素は、クラスの永続的な JavaBean スタイルのプロパティを定義します。

<property
        name="(1)propertyName"
        column(2)="column_name"
        type="(3)typename"
        update(4)="true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary SQL expression"
        access(6)="field|property|ClassName"
        lazy="(7)true|false"
        unique(8)="true|false"
        not-nu(9)ll="true|false"
        optimi(10)stic-lock="true|false"
        genera(11)ted="never|insert|always"
        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 の UPDATEINSERT に含まれることを指定します。両方とも false に設定すると、同じカラムにマッピングされた他のプロパティやトリガや他のアプリケーションによって初期化された純粋な「導出」プロパティが可能になります。

5

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

6

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

7

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

8

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

9

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

10

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

11

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

typename には以下の値が可能です:

型を指定しなければ、 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> マッピング要素を使えることにも注意してください。

他の永続クラスへの通常の関連は many-to-one 要素を使って定義します。リレーショナルモデルは多対一関連です。つまりあるテーブルの外部キーは、ターゲットとなるテーブルの主キーカラムを参照しています。

<many-to-one
        name="(1)propertyName"
        column(2)="column_name"
        class=(3)"ClassName"
        cascad(4)e="cascade_style"
        fetch=(5)"join|select"
        update(6)="true|false"
        insert(6)="true|false"
        proper(7)ty-ref="propertyNameFromAssociatedClass"
        access(8)="field|property|ClassName"
        unique(9)="true|false"
        not-nu(10)ll="true|false"
        optimi(11)stic-lock="true|false"
        lazy="(12)proxy|no-proxy|false"
        not-fo(13)und="ignore|exception"
        entity(14)-name="EntityName"
        formul(15)a="arbitrary SQL expression"
        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 ): 外部結合フェッチと順次選択フェッチ(sequential select fetch)のどちらかを選択します。

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 式

Setting a value of the cascade attribute to any meaningful value other than none will propagate certain operations to the associated object. The meaningful values are divided into three categories. First, basic operations, which include: persist, merge, delete, save-update, evict, replicate, lock and refresh; second, special values: delete-orphan; and third, all comma-separated combinations of operation names: cascade="persist,merge,evict" or cascade="all,delete-orphan". See 「連鎖的な永続化」 for a full explanation. Note that single valued, many-to-one and one-to-one, associations do not support 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"/>

他の永続クラスへの一対一関連は、one-to-one 要素で定義します。

<one-to-one
        name="(1)propertyName"
        class=(2)"ClassName"
        cascad(3)e="cascade_style"
        constr(4)ained="true|false"
        fetch=(5)"join|select"
        proper(6)ty-ref="propertyNameFromAssociatedClass"
        access(7)="field|property|ClassName"
        formul(8)a="any SQL expression"
        lazy="(9)proxy|no-proxy|false"
        entity(10)-name="EntityName"
        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 ): 外部結合フェッチと順次選択フェッチ(sequential select fetch)のどちらかを選択します。

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" ならば、プロキシは使用不可能となり、関連を即時にフェッチすることに注意してください。

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
>

Employee インスタンスが、 Personemployee プロパティで参照されるように、新しくセーブされた Person のインスタンスには同じ主キーの値が代入されます。新しくセーブする 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"/>

<component> 要素は、子オブジェクトのプロパティを親クラスのテーブルのカラムへマッピングします。コンポーネントは自分のプロパティ、コンポーネント、コレクションの順に定義できます。以下の「コンポーネント」を見てください。

<component
        name="(1)propertyName"
        class=(2)"className"
        insert(3)="true|false"
        update(4)="true|false"
        access(5)="field|property|ClassName"
        lazy="(6)true|false"
        optimi(7)stic-lock="true|false"
        unique(8)="true|false"
        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> サブ要素を許可します。

The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map. See 「動的コンポーネント」 for more information.

<properties> 要素はクラスのプロパティの指定された、論理的なグルーピングを可能にします。この構造の最も重要な使用方法は、 property-ref のターゲットになるプロパティの結合を許可することです。それはまた、複数カラムのユニーク制約を定義する簡単な方法でもあります。

<properties
        name="(1)logicalName"
        insert(2)="true|false"
        update(3)="true|false"
        optimi(4)stic-lock="true|false"
        unique(5)="true|false"
>

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

しかし、このようなレガシーデータマッピングのコンテキスト外への使用は推奨しません。

もう1つの方法として、各サブクラスを自身のテーブルへマッピングすることができます (table-per-subclass mapping strategy)。継承した状態はスーパークラスのテーブルを使った結合で検索します。 <joined-subclass> 要素を使用します。

<joined-subclass
        name="(1)ClassName"
        table=(2)"tablename"
        proxy=(3)"ProxyInterface"
        lazy="(4)true|false"
        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
>

For information about inheritance mappings see 9章継承マッピング.

3つ目の選択肢は、継承階層の具象クラスのみをテーブルにマッピングすることです (the table-per-concrete-class 戦略)。それぞれのテーブルは継承の状態を含めすべてのクラスの永続状態を定義します。 Hibernate ではその様な継承階層が必ずしも必要ではありません。単純にそれぞれのクラスを、別々の <class> 宣言を使ってマッピングすることができます。しかしポリモーフィックな関連 (例えば階層のスーパークラスへの関連) を使いたいなら、 <union-subclass> マッピングを使う必要があります。

<union-subclass
        name="(1)ClassName"
        table=(2)"tablename"
        proxy=(3)"ProxyInterface"
        lazy="(4)true|false"
        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" とすると、遅延フェッチが使用できません。

このマッピング戦略では識別カラムやキーカラムは必要ありません。

For information about inheritance mappings see 9章継承マッピング.

テーブル間に一対一の関係があるとき、 <join> 要素を使うことで、1つのクラスのプロパティをいくつものテーブルにマッピングすることができます。

<join
        table=(1)"tablename"
        schema(2)="owner"
        catalo(3)g="catalog"
        fetch=(4)"join|select"
        invers(5)e="true|false"
        option(6)al="true|false">

        <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つのクラス階層で継承のマッピング戦略を切り替える時には有用です。

今まで何度か <key> 要素が出てきました。この要素は新しいテーブルへの結合を定義したり、結合テーブルで外部キーを定義したりする親要素のどこにでも現れ、オリジナルテーブルの主キーを参照します。

<key
        column(1)="columnname"
        on-del(2)ete="noaction|cascade"
        proper(3)ty-ref="propertyName"
        not-nu(4)ll="true|false"
        update(5)="true|false"
        unique(6)="true|false"
/>

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"> を使ってキーカラムを宣言 しなくてはなりません

プロパティマッピングにはさらにもう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="(1)propertyName"
        id-typ(2)e="idtypename"
        meta-t(3)ype="metatypename"
        cascad(4)e="cascade_style"
        access(5)="field|property|ClassName"
        optimi(6)stic-lock="true|false"
>
        <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 ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを定義します。

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

エンティティ はエンティティへの参照を保持する、他のすべてのオブジェクトから独立して存在します。参照されないオブジェクトがガベージコレクトされてしまう性質を持つ通常の Java モデルと、これを比べてみてください。(親エンティティから子へ、セーブと削除が カスケード されうることを除いて)エンティティは明示的にセーブまたは削除されなければなりません。これは到達可能性によるオブジェクト永続化の ODMG モデルとは異なっています。大規模なシステムでアプリケーションオブジェクトが普通どのように使われるかにより密接に対応します。エンティティは循環と参照の共有をサポートします。またそれらはバージョン付けすることもできます。

エンティティの永続状態は他のエンティティや 型のインスタンスへの参照から構成されます。値はプリミティブ、コレクション (コレクションの内部ではなく)、コンポーネント、不変オブジェクトです。エンティティとは違い、値は(特にコレクションとコンポーネントにおいて)、到達可能性による永続化や削除が 行われます 。値オブジェクト(とプリミティブ)は、包含するエンティティと一緒に永続化や削除が行われるので、それらを独立にバージョン付けすることはできません。値には独立したアイデンティティがないので、複数のエンティティやコレクションがこれを共有することはできません。

これまで「永続クラス」という言葉をエンティティの意味で使ってきました。これからもそうしていきます。厳密に言うと、永続状態を持つユーザー定義のクラスのすべてがエンティティというわけではありません。 コンポーネント は値のセマンティクスを持つユーザー定義クラスです。 java.lang.String 型のプロパティもまた値のセマンティクスを持ちます。定義するなら、 JDK で提供されているすべての Java の型 (クラス) が値のセマンティクスを持つといえます。一方ユーザー定義型は、エンティティや値型のセマンティクスとともにマッピングできます。この決定はアプリケーション開発者次第です。そのクラスの1つのインスタンスへの共有参照は、ドメインモデル内のエンティティクラスに対する良いヒントになります。一方合成集約や集約は、通常値型へ変換されます。

本ドキュメントを通して、何度もこの概念を取り上げます。

Java 型のシステム (もしくは開発者が定義したエンティティと値型) を SQL /データベース型のシステムにマッピングすることは難しいです。 Hibernate は2つのシステムの架け橋を提供します。エンティティに対しては <class><subclass> などを使用します。値型に対しては <property><component> などを、通常 type と共に使います。この属性の値は Hibernate の マッピング型 の名前です。 Hibernate は (標準 JDK の値型に対して) 多くの自由なマッピングを提供します。後で見るように、自身のマッピング型を記述し、同様にカスタムの変換戦略を実装することができます。

コレクションを除く組み込みの Hibernate の型はすべて、 null セマンティクスをサポートします。

組み込みの 基本的なマッピング型 は大まかに以下のように分けられます。

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 型を表現しています。

開発者が独自の値型を作成することは、比較的簡単です。例えば、 java.lang.BigInteger 型のプロパティを VARCHAR カラムに永続化したいかもしれません。 Hibernate はこのための組み込み型を用意していません。しかしカスタム型は、プロパティ(またはコレクションの要素)を1つのテーブルカラムにマッピングするのに制限はありません。そのため例えば、 java.lang.String 型の getName() / setName() Java プロパティを FIRST_NAMEINITIALSURNAME カラムに永続化できます。

カスタム型を実装するには、 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 で提供されたパラメータをその都度オーバーライドすることが可能です。

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

XML の記述以外に、 Hibernate では O/R マッピングのメタデータを定義する代替方法があります。

多くの Hibernate ユーザーは 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 に関するサンプルが多数あります。

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(access = AccessType.FIELD)

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
}

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

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">property</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;creditCardNumber&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">column</span><span class="xml_plain">&nbsp;</span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;credit_card_num&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">read</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;decrypt(credit_card_num)&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">write</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;encrypt(?)&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">property</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

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

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

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

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

Hibernate のスキーマエボリューションツールと連動することで、任意のデータベースオブジェクト(トリガーやストアドプロシージャなど)の CREATE と DROP により、 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
>

コレクション型のフィールドを永続化するには、そのコレクション型がインターフェース型である必要があります。例えば、

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 のコレクションと同じように、永続化コレクションを使ってください。双方向関連の意味を理解すればよいのです(これは後ほど説明します)。

コレクションをマッピングするためのマッピング要素は、インターフェースの型に依存します。例えば、 <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="prop(1)ertyName"
    table="tab(2)le_name"
    schema="sc(3)hema_name"
    lazy="true(4)|extra|false"
    inverse="t(5)rue|false"
    cascade="a(6)ll|none|save-update|delete|all-delete-orphan|delete-orphan"
    sort="unso(7)rted|natural|comparatorClass"
    order-by="(8)column_name asc|desc"
    where="arb(9)itrary sql where condition"
    fetch="joi(10)n|select|subselect"
    batch-size(11)="N"
    access="fi(12)eld|property|ClassName"
    optimistic(13)-lock="true|false"
    mutable="t(14)rue|false"
    node="element-name|."
    embed-xml="true|false"
>

    <key .... />
    <map-key .... />
    <element .... />
</map
>

1

name :コレクション型であるプロパティの名前

2

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

3

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

4

lazy (オプション - デフォルトは true): 遅延フェッチを無効にし、関連を常に即時にフェッチにするために使用します。または、「extra-lazy」フェッチを有効にするために使用します。「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):コレクション型プロパティの値にアクセスするために使用する戦略です。

13

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

14

mutable(オプション - デフォルトは truefalse 値は、コレクションの要素が変更されないことを表します (ある場合には、少しパフォーマンスを高めます)。

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

<list-index
        column(1)="column_name"
        base="(2)0|1|..."/>

1

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

1

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

<map-key
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)type_name"
        node="@attribute-name"
        length="N"/>

1

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

2

formula (optional): a SQL formula used to evaluate the key of the map.

3

type (required): the type of the map keys.

<map-key-many-to-many
        column(1)="column_name"
        formul(2)(3)a="any SQL expression"
        class="ClassName"
/>

1

column (optional): the name of the foreign key column for the collection index values.

2

formula (optional): a SQ formula used to evaluate the foreign key of the map key.

3

class (required): the entity class used as the map key.

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

値のコレクションや多対多関連は、専用の コレクションテーブル が必要です。このテーブルは、外部キーカラムと、 コレクション要素のカラム と、場合によってはインデックスカラムを持ちます。

値のコレクションのために、 <element> タグを使用します。

<element
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)typename"
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>

1

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

2

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

3

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

A many-to-many association is specified using the <many-to-many> element.

<many-to-many
        column(1)="column_name"
        formul(2)a="any SQL expression"
        class=(3)"ClassName"
        fetch=(4)"select|join"
        unique(5)="true|false"
        not-fo(6)und="ignore|exception"
        entity(7)-name="EntityName"
        proper(8)ty-ref="propertyNameFromAssociatedClass"
        node="element-name"
        embed-xml="true|false"
    />

1

column (optional): the name of the element foreign key column.

2

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

3

class (required): the name of the associated class.

4

fetch (optional - defaults to join): enables outer-join or sequential select fetching for this association. This is a special case; for full eager fetching in a single SELECT of an entity and its many-to-many relationships to other entities, you would enable join fetching,not only of the collection itself, but also with this attribute on the <many-to-many> nested element.

5

unique (optional): enables the DDL generation of a unique constraint for the foreign-key column. This makes the association multiplicity effectively one-to-many.

6

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

7

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

8

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

Here are some examples.

A set of strings:


<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set
>

整数値を含む bag (bagは order-by 属性によって反復順序が定義されています):


<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 (次の章で詳しく説明します)


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

一対多関連 は、コレクションテーブルを介さず、外部キーにより2つのクラスのテーブルを関連付けます。このマッピングは標準的な Java のコレクションのセマンティクスをいくつか失います:

Product から Part への関連は、 Part テーブルへの外部キーカラムと、場合によってはインデックスカラムが必要です。 <one-to-many> タグは、これが一対多関連であることを表しています。

<one-to-many
        class=(1)"ClassName"
        not-fo(2)und="ignore|exception"
        entity(3)-name="EntityName"
        node="element-name"
        embed-xml="true|false"
    />

1

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

2

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

3

entity-name (オプション): class の代替である関連クラスのエンティティ名。 class の代わりに指定する、関連クラスのエンティティ名。

<one-to-many> 要素はカラムを宣言する必要がないことに注意してください。同様に テーブル 名を指定する必要もありません。

次の例は、名称(Part の永続的なプロパティである partName) による Part エンティティの map を表しています。 formula によるインデックスを使っていることに注意してください。


<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map
>

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 のように振舞います。

もしデータベース自身にコレクションの要素を並べさせたいなら、 setbagmaporder-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
>

関連は、コレクションの filter() を使うことで、実行時に任意の criteria によってソートすることも可能です。

sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();

双方向関連 は関連のどちら「側」からでもナビゲーションできます。2種類の双方向関連がサポートされています:

2つの多対多関連で同じデータベーステーブルをマッピングし、片方を inverse として宣言することで、双方向の多対多関連を指定することが出来ます (どちらを 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 で双方向関係をどうやって作るかを考えれば、これは理解しやすいです。下記に、 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" を設定しても、カスケード操作に影響を与えません。これらは直交した概念です。

片側が <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
>

Note that in this mapping, the collection-valued end of the association is responsible for updates to the foreign key.

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

bag のセマンティックスを持った List(または Collection)を <idbag> 要素にマッピングできます。


<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> コレクションの識別子に対して使えません。

This section covers collection examples.

The following class has a collection of Child instances:

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; }
    ....
    ....
}

If each child has, at most, one parent, the most natural mapping is a one-to-many association:


<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

もし 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
>

一方で、もし child が複数の parent を持てるならば、多対多関連が妥当です:


<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

For more examples and a complete explanation of a parent/child relationship mapping, see 22章例: 親/子供 for more information.

Even more complex association mappings are covered in the next chapter.

双方向多対一関連 は最も一般的な関連です。 (標準的な親子関係です)


<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 に設定し、コレクション側が各要素のインデックスをメンテナンスするように、関連を扱う必要があります (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
>

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