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


<?xml version="1.0"?>

<!DOCTYPE hibernate-mapping PUBLIC

      "-//Hibernate/Hibernate Mapping DTD 3.0//EN"

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



<hibernate-mapping package="eg">



        <class name="Cat"

            table="cats"

            discriminator-value="C">



                <id name="id">

                        <generator class="native"/>

                </id>



                <discriminator column="subclass"

                     type="character"/>



                <property name="weight"/>



                <property name="birthdate"

                    type="date"

                    not-null="true"

                    update="false"/>



                <property name="color"

                    type="eg.types.ColorUserType"

                    not-null="true"

                    update="false"/>



                <property name="sex"

                    not-null="true"

                    update="false"/>



                <property name="litterId"

                    column="litterId"

                    update="false"/>



                <many-to-one name="mother"

                    column="mother_id"

                    update="false"/>



                <set name="kittens"

                    inverse="true"

                    order-by="litter_id">

                        <key column="mother_id"/>

                        <one-to-many class="Cat"/>

                </set>



                <subclass name="DomesticCat"

                    discriminator-value="D">



                        <property name="name"

                            type="string"/>



                </subclass>



        </class>



        <class name="Dog">

                <!-- mapping for Dog could go here -->

        </class>



</hibernate-mapping

>

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

5.1.1. Doctype

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

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

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

hibernate namespace は、リゾルバが http://hibernate.sourceforge.net/ で始まるシステム ID に到達したときに認識されます。そしてリゾルバは、 Hibernate のクラスをロードしたクラスローダを用いて、これらのエンティティを解決しようとします。
user namespace は、リゾルバが URL プロトコルの classpath:// を使ったシステム ID に到達したときに、認識されます。そしてリゾルバは、 (1) カレントスレッドのコンテキストクラスローダー、または (2) Hibernate のクラスをロードしたクラスローダを使って、これらのエンティティを解決しようとします。

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


<?xml version="1.0"?>

<!DOCTYPE hibernate-mapping PUBLIC '-//Hibernate/Hibernate Mapping DTD 3.0//EN' 'http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd' [

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

5.1.2. Hibernate-mapping

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

<hibernate-mapping
         schema="schemaName"
         catalog="catalogName"
         default-cascade="cascade_style"
         default-access="field|property|ClassName"
         default-lazy="true|false"
         auto-import="true|false"
         package="package.name"
 />

	`schema`（オプション）：データベーススキーマの名前。
	`catalog` （オプション）：データベースカタログの名前。
	`default-cascade` （オプション - デフォルトは `none`）：デフォルトのカスケードスタイル。
	`default-access` (オプション - デフォルトは `property` ）： Hibernate がプロパティにアクセスする際に取るべき戦略。 `PropertyAccessor` を実装することでカスタマイズ可能。
	`default-lazy` (オプション - デフォルトは `true` )： `lazy` 属性が指定されていないクラスやコレクションマッピングに対するデフォルト値。
	`auto-import` （オプション - デフォルトは `true`）：クエリ言語内で、（このマッピング内のクラスの）修飾されていないクラス名を使えるかどうかを指定します。
	`package` (オプション): マッピングドキュメント内で修飾されていないクラス名に対して割り当てる、パッケージの接頭辞 (prefix) を指定します。

（修飾されていない）同じ名前の永続クラスが2つあるなら、 auto-import="false" を設定すべきです。2つのクラスに"インポートされた"同じ名前を割り当てようとすると、 Hibernate は例外を送出します。

hibernate-mapping 要素は、最初の例で示したようにいくつかの永続 <class> マッピングをネストできます。しかし、１つのマッピングファイルではただひとつの永続クラス(またはひとつのクラス階層)にマッピングするようにし、さらに永続スーパークラスの後で指定するべきでしょう(いくつかのツールはこのようなマッピングファイルを想定しています)。例えば次のようになります。： Cat.hbm.xml , Dog.hbm.xml , または継承を使うなら Animal.hbm.xml 。

5.1.3. Class

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

<class
        name="ClassName"
        table="tableName"
        discriminator-value="discriminator_value"
        mutable="true|false"
        schema="owner"
        catalog="catalog"
        proxy="ProxyInterface"
        dynamic-update="true|false"
        dynamic-insert="true|false"
        select-before-update="true|false"
        polymorphism="implicit|explicit"
        where="arbitrary sql where condition"
        persister="PersisterClass"
        batch-size="N"
        optimistic-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"
/>

	`name` (オプション)：永続クラス（またはインターフェース）の完全修飾 Java クラス名。もしこの属性が欠落している場合、 POJO ではないエンティティに対するマッピングとして扱われます。
	`table` (オプション - デフォルトは修飾されていないクラス名)：データベーステーブルの名前。
	`discriminator-value` (オプション - デフォルトはクラス名)：ポリモーフィックな振る舞いに使われる個々のサブクラスを識別するための値。値は `null` か `not null` のいずれかを取ります。
	`mutable` (オプション、デフォルトは `true` )：そのクラスのインスタンスが更新可能（または不可能）であることを指定します。
	`schema` (オプション): ルートの `<hibernate-mapping>` 要素で指定したスキーマ名をオーバーライドします。
	`catalog` (オプション): ルートの `<hibernate-mapping>` 要素で指定したカタログ名をオーバーライドします。
	`proxy` （オプション）：遅延初期化プロキシに使うインターフェースを指定します。永続化するクラス名そのものを指定することも可能です。
	`dynamic-update` （オプション、デフォルトは `false` ）：値が変更されたカラムだけを含む SQL の `UPDATE` 文を、実行時に生成することを指定します。
	`dynamic-insert` （オプション, デフォルトは `false` ）：値が null ではないカラムだけを含む SQL の `INSERT` 文を、実行時に生成することを指定します。
	`select-before-update` (オプション、デフォルトは `false`): オブジェクトが変更されたのが確実でないならば、 Hibernate が SQL の `UPDATE` を決して実行しないことを指定します。ある特定の場合(実際的には、一時オブジェクトが `update()` を使い、新しいセッションと関連付けられた時だけ)、 `UPDATE` が実際に必要かどうかを決定するために、 Hibernate が余分な SQL の `SELECT` 文を実行することを意味します。
	`polymorphism` (オプション、デフォルトでは `implicit` ): implicit（暗黙）かexplicit（明示）の、どちらのクエリポリモーフィズムを使うか決定します。
	`where` （オプション）：このクラスのオブジェクトを検索するときに使用する、任意の SQL の `WHERE` 条件を指定します。
	`persister` （オプション）：カスタム `ClassPersister` を指定します。
	`batch-size` （オプション、デフォルトは `1` ）：識別子でこのクラスのインスタンスを復元するときの「バッチサイズ」を指定します。
	`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-update と dynamic-insert の設定はサブクラスに継承されません。そのため <subclass> や <joined-subclass> 要素を指定することも出来ます。これらの設定はパフォーマンスを向上させる事もありますが、落とすこともありますので、慎重に使用してください。

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

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

version バージョン/タイムスタンプカラムをチェックします。
all すべてのカラムをチェックします。
dirty 変更したカラムをチェックし、同時更新できるようにします。
none 楽観ロックを使用しません。

Hibernate で楽観的ロック戦略を使うなら、バージョン/タイムスタンプカラムを使うことを 非常に 強くお勧めします。楽観的ロックはパフォーマンスの観点からも最適であり、さらに分離インスタンスへの修正（つまり Session.marge() が使われるとき）を正確に扱うことのできる唯一の戦略でもあります。

Hibernate のマッピングにとってビューと普通のテーブルの間に違いはなく、データベースレベルでは透過的です（ただしビューを完全にはサポートしていない DBMS もあります。特に、更新のあるビューに対してはそうです）。ビューを使いたくても、データベースで作成できないことがあります（例えば、レガシースキーマの場合）。この場合には、不変かつ読み取り専用のエンティティに与えられた SQL の副問合せ文をマップできます：


<class name="Summary">

    <subselect>

        select item.name, max(bid.amount), count(*)

        from item

        join bid on bid.item_id = item.id

        group by item.name

    </subselect>

    <synchronize table="item"/>

    <synchronize table="bid"/>

    <id name="name"/>

    ...

</class

>

テーブルをこのエンティティと同期するように定義してください。オートフラッシュが確実に起こるように、また導出エンティティに対するクエリが古いデータを返さないようにするためです。 <subselect> は属性とネストしたマッピング属性のどちらでも利用できます。

5.1.4. id

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

<id
        name="propertyName"
        type="typename"
        column="column_name"
        unsaved-value="null|any|none|undefined|id_value"
        access="field|property|ClassName">
        node="element-name|@attribute-name|element/@attribute|."

        <generator class="generatorClass"/>
</id
>

	`name`（オプション）：識別子プロパティの名前。
	`type`（オプション）： Hibernate の型を示す名前。
	`column`（オプション - デフォルトはプロパティ名）：主キーカラムの名前。
	`unsaved-value`（オプション - デフォルトの値は sensible ）：インスタンスが新しくインスタンス化された（セーブされていない）ことを示す、識別子プロパティの値。以前の Session でセーブまたはロードされた分離インスタンスと区別するために使います。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。

name 属性がなければ、クラスには識別子プロパティがないものとみなされます。

unsaved-value 属性は Hibernate3 ではほとんどの場合、必要ではありません。

複合キーを持つレガシーデータにアクセスできるように、 <composite-id> という代替のマッピング定義があります。しかし他の用途への使用は全くおすすめできません。

5.1.4.1. ジェネレータ

オプションの <generator> 子要素は、永続クラスのインスタンスのユニークな識別子を生成するために使う、 Java クラスを指定します。ジェネレータインスタンスの設定、もしくは初期化にパラメータが必要であれば、 <param> 要素を使って渡すことができます。


<id name="id" type="long" column="cat_id">

        <generator class="org.hibernate.id.TableHiLoGenerator">

                <param name="table"

>uid_table</param>

                <param name="column"

>next_hi_value_column</param>

        </generator>

</id

>

すべてのジェネレータは、 org.hibernate.id.IdentifierGenerator インターフェースを実装します。これはとても単純なインターフェースなので、特別な実装を独自に用意するアプリケーションもあるかもしれません。しかし Hibernate は組み込みの実装をいくつも用意しています。組み込みのジェネレータには以下のショートカット名があります：

increment: long , short , int 型の識別子を生成します。これらは他のプロセスが同じテーブルにデータを挿入しないときだけユニークです。 クラスタ内では使わないでください 。
identity: DB2, MySQL, MS SQL Server, Sybase, HypersonicSQL の識別子カラムをサポートします。返される識別子の型は long , short , int のいずれかです。
sequence: DB2, PostgreSQL, Oracle, SAP DB, McKoi のシーケンスや、 Interbase のジェネレータを使用します。返される識別子の型は long , short , int のいずれかです。
hilo: long , short , int 型の識別子を効率的に生成する hi/lo アルゴリズムを使います。 hi 値のソースとして、テーブルとカラムを与えます(デフォルトではそれぞれ hibernate_unique_key と next_hi )。 hi/lo アルゴリズムは特定のデータベースに対してのみユニークな識別子を生成します。
seqhilo: long , short , int 型の識別子を効率的に生成する hi/lo アルゴリズムを使います。指定されたデータベースシーケンスを与えます。
uuid: ( IP アドレスが使用される)ネットワーク内でユニークな文字列型の識別子を生成するために、 128 ビットの UUID アルゴリズムを使用します。 UUID は長さ 32 の 16 進数字の文字列としてエンコードされます。
guid: MS SQL サーバーと MySQL でデータベースが生成する GUID 文字列を使用します。
native: 使用するデータベースの性能により identity 、 sequence 、 hilo のいずれかが選ばれます。
assigned: save() が呼ばれる前に、アプリケーションがオブジェクトに識別子を代入できるようにします。 <generator> 要素が指定されていなければ、これがデフォルトの戦略になります。
select: あるユニークキーによる行の選択と主キーの値の復元により、データベーストリガが割り当てた主キーを取得します。
foreign: 他の関連オブジェクトの識別子を使います。普通は、 <one-to-one> 主キー関連と組み合わせて使います。
sequence-identity: 実際の値の生成のためにデータベースシーケンスを使用する特別なシーケンス生成戦略ですが、 JDBC3 getGeneratedKeys と結びついて、 INSERT 文の実行の一部として生成された識別子の値を実際に返します。この戦略は JDK 1.4 を対象とする Oracle 10g のドライバでサポートされていることが知られています。これらの INSERT 文でのコメントは Oracle のドライバのバグにより無効にされていることに注意してください。

5.1.4.2. Hi/lo アルゴリズム

hilo と seqhilo ジェネレータは、識別子生成の代表的なアプローチである hi/lo アルゴリズムの2つの代替実装を提供します。1番目の実装は、次回に利用される "hi" 値を保持する「特別な」データベーステーブルを必要とします。2番目の実装は、 Oracle スタイルのシーケンスを使います（サポートされている場合）。


<id name="id" type="long" column="cat_id">

        <generator class="hilo">

                <param name="table"

>hi_value</param>

                <param name="column"

>next_value</param>

                <param name="max_lo"

>100</param>

        </generator>

</id

>


<id name="id" type="long" column="cat_id">

        <generator class="seqhilo">

                <param name="sequence"

>hi_value</param>

                <param name="max_lo"

>100</param>

        </generator>

</id

>

残念ながら Hibernate への独自の Connection を提供するときには、 hilo を使えません。 Hibernate が JTA でリストされている接続を取得するためにアプリケーションサーバーのデータソースを使用しているときには、 hibernate.transaction.manager_lookup_class を適切に設定しなければなりません。

5.1.4.3. UUID アルゴリズム

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

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

識別子カラムをサポートしているデータベース（DB2, MySQL, Sybase, MS SQL）では、 identity キー生成が使えます。シーケンスをサポートするデータベース（DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB）では、 sequence スタイルのキー生成が使えます。どちらの戦略も、新しいオブジェクトを挿入するために、 SQL クエリを2つ必要とします。


<id name="id" type="long" column="person_id">

        <generator class="sequence">

                <param name="sequence"

>person_id_sequence</param>

        </generator>

</id

>


<id name="id" type="long" column="person_id" unsaved-value="0">

        <generator class="identity"/>

</id

>

クロスプラットフォームの開発では、native 戦略は identity 、 sequence 、 hilo 戦略の中から1つを選択しますが、これは使用しているデータベースの能力に依存します。

5.1.4.5. 識別子の割り当て

アプリケーションに識別子を割り当てさせたいのであれば( Hibernate が生成するものではなく）、 assigned ジェネレータを使うことができます。この特別なジェネレータは、すでにオブジェクトの識別子プロパティに代入された値を識別子に使います。このジェネレータは主キーが代理キーの代わりに自然キーである場合に使用します。 <generator> 要素を指定しない場合のデフォルトの動作になります。

assigned ジェネレータを選択すると、 Hibernate は unsaved-value="undefined" を使います。そして、バージョンやタイムスタンプのプロパティがない場合や Interceptor.isUnsaved() を定義しなかった場合には、インスタンスが一時的(transient)なものであるのか、またはセッションから分離(detached)したものかどうかを決めるために、データベースを調べます。

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

レガシースキーマのためにのみ指定します( Hibernate はトリガを使って DDL を生成しません)。


<id name="id" type="long" column="person_id">

        <generator class="select">

                <param name="key"

>socialSecurityNumber</param>

        </generator>

</id

>

上記の例の中で、クラスで自然キーとして定義された socialSecurityNumber という名前のユニークな値のプロパティと、値がトリガにより生成される person_id という名前の代理キーがあります。

5.1.5. Enhanced identifier generators

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:

sequence_name (optional, defaults to hibernate_sequence): the name of the sequence or table to be used.
initial_value (optional, defaults to 1): the initial value to be retrieved from the sequence/table. In sequence creation terms, this is analogous to the clause typically named "STARTS WITH".
increment_size (optional - defaults to 1): the value by which subsequent calls to the sequence/table should differ. In sequence creation terms, this is analogous to the clause typically named "INCREMENT BY".
force_table_use (optional - defaults to false): should we force the use of a table as the backing structure even though the dialect might support sequence?
value_column (optional - defaults to next_val): only relevant for table structures, it is the name of the column on the table which is used to hold the value.
optimizer (optional - defaults to none): See 「Identifier generator optimization」

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」

`5.1.6. 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.

`5.1.7. composite-id`


<composite-id

        name="propertyName"

        class="ClassName"

        mapped="true|false"

        access="field|property|ClassName">

        node="element-name|."



        <key-property name="propertyName" type="typename" column="column_name"/>

        <key-many-to-one name="propertyName" class="ClassName" column="column_name"/>

        ......

</composite-id

>

複合キーのあるテーブルに対し、識別子プロパティとしてクラスの複数のプロパティをマッピングすることができます。 <composite-id> 要素は、子要素として <key-property> プロパティマッピングと <key-many-to-one> マッピングを受け入れます。


<composite-id>

        <key-property name="medicareNumber"/>

        <key-property name="dependent"/>

</composite-id

>

複合識別子の等価性を実装するためには、永続クラスが equals() と hashCode() をオーバーライドしなければなりません。また Serializable も実装しなければいけません。

残念ながら複合識別子のためのこの方法は、永続オブジェクトが自身の識別子であることを意味しています。オブジェクト自身を識別子とする以外に便利な「扱い方」はありません。複合キーに関連した永続状態を load() 出来るようになる前に、永続クラス自身をインスタンス化し、識別子プロパティを設定しなければなりません。組み込みの複合識別子と呼ばれるこのアプローチは、本格的なアプリケーションには向いていません。

2つ目の方法はマップされた複合識別子と呼ばれるもので、 <composite-id>エレメント内で指定した識別プロパティが永続クラスと分離した識別子クラスの両方に重複して存在します。


<composite-id class="MedicareId" mapped="true">

        <key-property name="medicareNumber"/>

        <key-property name="dependent"/>

</composite-id

>

この例では、複合識別子クラス（ MedicareId ）とエンティティクラス自身の両方が、 medicareNumber と dependent という名前のプロパティを持ちます。識別子クラスは、 equals() と hashCode() をオーバライドし、 Serializable を実装しなくてはなりません。この方法には、明らかにコードが重複するという不都合があります。

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

mapped (オプション、デフォルトは false ): マッピングした複合識別子が使用されることと、包含されたプロパティのマッピングが、エンティティクラスと複合識別子クラスの両方を参照することを示します。
class (オプション、ただしマッピングした複合識別子には必須): 複合識別子として使用するクラス。

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つ目の方法は識別子コンポーネントと呼び、ほとんどすべてのアプリケーションに対して推奨する方法です。

`5.1.8. discriminator`

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

<discriminator
        column="discriminator_column"
        type="discriminator_type"
        force="true|false"
        insert="true|false"
        formula="arbitrary sql expression"
/>

	`column`（オプション - デフォルトは `class` ）：識別カラムの名前。
	`type` （オプション - デフォルトは `string` ）： Hibernate の型を示す名前。
	`force` （オプション - デフォルトは `false` ）：ルートクラスのすべてのインスタンスを検索する場合であっても、 Hibernate が使用できる識別カラムの指定を「強制」します。
	`insert` （オプション - デフォルトは `true` ）：もし識別カラムがマッピングする複合識別子の一部ならば、 `false` と設定してください。 (Hibernate に SQL の `INSERT` 内のカラムを含ませないよう伝えます。)
	`formula` (オプション) 型が評価されるときに実行される任意の SQL 式。コンテンツベースの識別を可能にします。

識別カラムの実際の値は、 <class> と <subclass> 要素の discriminator-value 属性で指定されます。

永続クラスへマッピングされない｢余分な」識別値を持つ行がテーブルにあれば、（そのときに限り） force 属性は有効です。ただし、普通はそういうことはありません。

formula 属性を使うと、行の型を評価するために任意の SQL 式を宣言できます:


<discriminator

    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"

    type="integer"/>

`5.1.9. version（オプション）`

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

<version
        column="version_column"
        name="propertyName"
        type="typename"
        access="field|property|ClassName"
        unsaved-value="null|negative|undefined"
        generated="never|always"
        insert="true|false"
        node="element-name|@attribute-name|element/@attribute|."
/>

	`column` （オプション - デフォルトはプロパティ名）: バージョン番号を保持するカラムの名前。
	`name` ：永続クラスのプロパティの名前。
	`type` （オプション - デフォルトは `integer` ）：バージョン番号の型。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`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.
	`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.
	`insert` (オプション - デフォルトは `true` ): SQLの insert 文にバージョンカラムを含めるべきかどうかを指定します。もしデータベースカラムのデフォルト値が `0` と定義されるときには、 `false` に設定すると良いでしょう。

バージョン番号は Hibernate の long 、 integer 、 short 、 timestamp 、 calendar 型のいずれかです。

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.

`5.1.10. timestamp（オプション）`

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

<timestamp
        column="timestamp_column"
        name="propertyName"
        access="field|property|ClassName"
        unsaved-value="null|undefined"
        source="vm|db"
        generated="never|always"
        node="element-name|@attribute-name|element/@attribute|."
/>

	`column`（オプション - デフォルトはプロパティ名）：タイムスタンプを保持するカラムの名前。
	`name` ：永続クラスである Java の `Date`型または `Timestamp` 型の、 JavaBeans スタイルプロパティの名前。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`unsaved-value` （オプション - デフォルトは `null` ）：インスタンスが新しくインスタンス化された（セーブされていない）ことを示すバージョンプロパティの値。以前の Session でセーブまたはロードされた分離されたインスタンスと区別するために使われます。（ `undefined` と指定すると、識別子プロパティの値が使われます。）
	`source` (オプション - デフォルトは `vm` ): Hibernate はどこからタイムスタンプの値を取得するべきでしょうか？データベースからでしょうか、現在の JVM からでしょうか？データベースによるタイムスタンプは、 Hibernate が "次の値" を決定するためにデータベースをヒットしなければならないため、オーバヘッドを招きます。しかしクラスタ環境では JVM から取得するより安全です。データベースの現在のタイムスタンプの取得をサポートするすべての `Dialect` が知られているわけではないことに注意してください。また一方で、精密さを欠くために、ロックで使用するには安全でないものもあります (例えば Oracle 8 )。
	`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.

`注記`

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

`5.1.11. property`

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

<property
        name="propertyName"
        column="column_name"
        type="typename"
        update="true|false"
        insert="true|false"
        formula="arbitrary SQL expression"
        access="field|property|ClassName"
        lazy="true|false"
        unique="true|false"
        not-null="true|false"
        optimistic-lock="true|false"
        generated="never|insert|always"
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

	`name`：小文字で始まるプロパティ名。
	`column`（オプション - デフォルトはプロパティ名）：マッピングされたデータベーステーブルのカラムの名前。ネストした `<column>` 要素でも指定できます。
	`type`（オプション）： Hibernate の型を示す名前。
	`update, insert` （オプション - デフォルトは `true` ）：マッピングされたカラムが SQL の `UPDATE` や `INSERT` に含まれることを指定します。両方とも `false` に設定すると、同じカラムにマッピングされた他のプロパティやトリガや他のアプリケーションによって初期化された純粋な「導出」プロパティが可能になります。
	`formula`（オプション）：計算プロパティのための値を定義する SQL 式。計算されたプロパティは自身のカラムへのマッピングがありません。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`lazy` (オプション - デフォルトは `false` ): インスタンス変数に最初にアクセスしたときに、プロパティを遅延して取得するよう指定します。 (バイトコード実装を作成する時間が必要になります)。
	`unique` (オプション):カラムにユニーク制約をつける DDL の生成を可能にします。また、 `property-ref` のターゲットとすることもできます。
	`not-null` (optional): enables the DDL generation of a nullability constraint for the columns.
	`optimistic-lock` (オプション - デフォルトは `true` ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。
	`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 の基本型の名前（例 integer, string, character, date, timestamp, float, binary, serializable, object, blob ）。
デフォルトの基本型の Java クラス名（例 int, float, char, java.lang.String, java.util.Date, java.lang.Integer, java.sql.Clob ）。
シリアライズ可能な Java クラスの名前。
カスタム型のクラス名（例 com.illflow.type.MyCustomType ）。

型を指定しなければ、 Hibernate は正しい Hibernate の型を推測するために、指定されたプロパティに対してリフレクションを使います。 Hibernate はルール2, 3, 4をその順序に使い、 getter プロパティの返り値のクラスの名前を解釈しようとします。しかしこれで常に十分であるとは限りません。場合によっては、 type 属性が必要な場合があります。（例えば Hibernate.DATE と Hibernate.TIMESTAMP を区別するため、またはカスタム型を指定するためなどです。）

access 属性で、実行時に Hibernate がどのようにプロパティにアクセスするかを制御できます。デフォルトでは Hibernate はプロパティの get/set のペアをコールします。 access="field" と指定すれば、 Hibernate はリフレクションを使い get/set のペアを介さずに、直接フィールドにアクセスします。インターフェース org.hibernate.property.PropertyAccessor を実装するクラスを指定することで、プロパティへのアクセスに独自の戦略を指定することができます。

特に強力な特徴は生成プロパティです。これらのプロパティは当然読み取り専用であり、プロパティの値はロード時に計算されます。計算を SQL 式として宣言すると、このプロパティはインスタンスをロードする SQL クエリの SELECT 句のサブクエリに変換されます:




<property name="totalPrice"

    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p

                WHERE li.productId = p.productId

                AND li.customerId = customerId

                AND li.orderNumber = orderNumber )"/>

特定のカラム(例では customerId がそれにあたります)のエイリアスを宣言することなく、エンティティ自身のテーブルを参照できることに注意してください。もし属性を使用したくなければ、ネストした <formula> マッピング要素を使えることにも注意してください。

`5.1.12. many-to-one`

<many-to-one
        name="propertyName"
        column="column_name"
        class="ClassName"
        cascade="cascade_style"
        fetch="join|select"
        update="true|false"
        insert="true|false"
        property-ref="propertyNameFromAssociatedClass"
        access="field|property|ClassName"
        unique="true|false"
        not-null="true|false"
        optimistic-lock="true|false"
        lazy="proxy|no-proxy|false"
        not-found="ignore|exception"
        entity-name="EntityName"
        formula="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"
/>

	`name`：プロパティ名。
	`column` (オプション):外部キーカラムの名前。ネストした `<column>` カラムによっても指定されます。
	`class`（オプション - デフォルトはリフレクションにより決定されるプロパティの型）：関連クラスの名前。
	`cascade`（オプション）：親オブジェクトから関連オブジェクトへ、どの操作をカスケードするかを指定します。
	`fetch`（オプション - デフォルトは `select` ）：外部結合フェッチと順次選択フェッチ（sequential select fetch）のどちらかを選択します。
	`update, insert`（オプション - デフォルトは `true` ）：マッピングされたカラムが SQL の `UPDATE` または `INSERT` 文に含まれることを指定します。両方とも `false` に設定すると、その値が同じカラムにマッピングされた他のプロパティやトリガや他のアプリケーションによって初期化された純粋な「導出」プロパティが可能になります。
	`property-ref`: (オプション) この外部キーに加わる、関連クラスのプロパティの名前。指定されていない場合は、関連クラスの主キーが使用されます。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`unique`（オプション）：外部キーカラムに対してユニーク制約をつけた DDL の生成を可能にします。また、 `property-ref` のターゲットにすることもできます。これにより関連の多重度を効果的に一対一にします。
	`not-null` (オプション): 外部キーカラムに対して、 null 値を許可する DDL の生成を可能にします。
	`optimistic-lock` (オプション - デフォルトは `true` ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。
	`lazy` (オプション - デフォルトは `proxy` ): デフォルトでは、多重度１の関連がプロキシとなります。 `lazy="no-proxy"` は、インスタンス変数に最初にアクセスしたときに、プロパティを遅延フェッチするよう指定します (ビルド時にバイトコード実装が必要になります)。 `lazy="false"` は関連を常に即時にフェッチするよう指定します。
	`not-found` （オプション - デフォルトは `exception`）: 参照先の行がない外部キーをどのように扱うかを指定します: `ignore` を指定すると、行がないことを関連がないものとして扱います。
	`entity-name` (オプション):関連したクラスのエンティティ名。
	`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"/>

`5.1.13. one-to-one`

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

<one-to-one
        name="propertyName"
        class="ClassName"
        cascade="cascade_style"
        constrained="true|false"
        fetch="join|select"
        property-ref="propertyNameFromAssociatedClass"
        access="field|property|ClassName"
        formula="any SQL expression"
        lazy="proxy|no-proxy|false"
        entity-name="EntityName"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

	`name`：プロパティ名。
	`class`（オプション - デフォルトはリフレクションにより決定されるプロパティの型）：関連クラスの名前。
	`cascade`（オプション）：親オブジェクトから関連オブジェクトへ、どの操作をカスケードするかを指定します。
	`constrained`（オプション）：マッピングされたテーブルの主キーに対する外部キー制約が、関連クラスのテーブルを参照することを指定します。このオプションは `save()` と `delete()` がカスケードされる順序に影響し、そして関連がプロキシされるかどうかにも影響します（そしてスキーマエクスポートツールにも使われます）。
	`fetch`（オプション - デフォルトは `select` ）：外部結合フェッチと順次選択フェッチ（sequential select fetch）のどちらかを選択します。
	`property-ref`（オプション）：このクラスの主キーに結合された関連クラスのプロパティ名。指定されなければ、関連クラスの主キーが使われます。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`formula` (オプション): ほとんどすべての一対一関連はオーナーのエンティティの主キーへとマッピングされます。これ以外の稀な場合は、他のカラムや、複数のカラム、 SQL 構文を使った結合するための式を指定できます。（例は `org.hibernate.test.onetooneformula` を参照してください。）
	`lazy` (オプション - デフォルトは `proxy` ): デフォルトでは、多重度１の関連がプロキシとなります。 `lazy="no-proxy"` は、インスタンス変数に最初にアクセスしたときに、プロパティを遅延フェッチするよう指定します (ビルド時にバイトコード実装が必要になります)。 `lazy="false"` は関連を常に即時にフェッチするよう指定します。もし `constrained="false"` ならば、プロキシは使用不可能となり、関連を即時にフェッチすることに注意してください。
	`entity-name` (オプション):関連したクラスのエンティティ名。

一対一関連には2種類あります：

主キー関連
ユニーク外部キー関連


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

もう1つの方法として、 Employee から Person へのユニーク制約を使った外部キー関連は以下のように表現されます：


<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>


<one-to-one name="employee" class="Employee" property-ref="person"/>

`5.1.14. natural-id`


<natural-id mutable="true|false"/>

        <property ... />

        <many-to-one ... />

        ......

</natural-id

>

主キーとして代理キーの使用を推奨しますが、すべてのエンティティに対して自然キーを識別するようにすべきです。自然キーはユニークかつ非 null な一つのプロパティ、またはプロパティの連結です。不変であればさらに良いです。 <natural-id> 要素内で自然キーのプロパティをマッピングします。 Hibernate は必然的にユニークかつ null 値を許可する制約を生成し、こうしてマッピングはより自己記述的になります。

エンティティの自然キープロパティの比較には、 equals() と hashCode() の実装を強くお勧めします。

このマッピングは自然主キーを使ったエンティティでの使用を意図していません。

mutable (オプション、デフォルトは false ): デフォルトでは、自然識別子プロパティは不変(定数)と想定されています。

`5.1.15. Component and dynamic-component`

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

<component
        name="propertyName"
        class="className"
        insert="true|false"
        update="true|false"
        access="field|property|ClassName"
        lazy="true|false"
        optimistic-lock="true|false"
        unique="true|false"
        node="element-name|."
>

        <property ...../>
        <many-to-one .... />
        ........
</component
>

	`name`：プロパティ名。
	`class` （オプション - デフォルトはリフレクションにより決定されるプロパティの型）：コンポーネント（子）クラスの名前。
	`insert`：マッピングされたカラムが SQL の `INSERT` に現れるようにするかどうかを指定します。
	`update`：マッピングされたカラムが SQL の `UPDATE` に現れるようにするかどうかを指定します。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`lazy` (オプション - デフォルトは `false` ): インスタンス変数に最初にアクセスしたときに、コンポーネントを遅延してフェッチするよう指定します。 (バイトコード実装を作成する時間が必要になります)
	`optimistic-lock` (オプション - デフォルトは `true` ): このプロパティの更新に、楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。
	`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.

`5.1.16. プロパティ`

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

<properties
        name="logicalName"
        insert="true|false"
        update="true|false"
        optimistic-lock="true|false"
        unique="true|false"
>

        <property ...../>
        <many-to-one .... />
        ........
</properties
>

	`name` : グルーピングの論理名。実際のプロパティ名ではありません。
	`insert`：マッピングされたカラムが SQL の `INSERT` に現れるようにするかどうかを指定します。
	`update`：マッピングされたカラムが SQL の `UPDATE` に現れるようにするかどうかを指定します。
	`optimistic-lock` (オプション - デフォルトは `true` ): これらのプロパティの更新に楽観的ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを決定します。
	`unique` (オプション - デフォルトは `false` ): コンポーネントのすべてのマッピングするカラムに、ユニーク制約が存在するかを指定します。

例えば、もし以下のような <properties> マッピングがあった場合：


<class name="Person">

    <id name="personNumber"/>



    ...

    <properties name="name"

            unique="true" update="false">

        <property name="firstName"/>

        <property name="initial"/>

        <property name="lastName"/>

    </properties>

</class

>

主キーの代わりに Person テーブルのユニークキーへの参照を持つ、レガシーデータの関連を持つかもしれません。：


<many-to-one name="person"

         class="Person" property-ref="name">

    <column name="firstName"/>

    <column name="initial"/>

    <column name="lastName"/>

</many-to-one

>

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

`5.1.17. subclass`

最後にポリモーフィックな永続化には、ルートの永続クラスの各サブクラスの定義が必要です。 table-per-class-hierarchy マッピング戦略では、 <subclass> 定義が使われます。

<subclass
        name="ClassName"
        discriminator-value="discriminator_value"
        proxy="ProxyInterface"
        lazy="true|false"
        dynamic-update="true|false"
        dynamic-insert="true|false"
        entity-name="EntityName"
        node="element-name"
        extends="SuperclassName">

        <property .... />
        .....
</subclass
>

	`name`：サブクラスの完全修飾されたクラス名。
	`discriminator-value`（オプション - デフォルトはクラス名）：個々のサブクラスを区別するための値。
	`proxy` (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。
	`lazy` (オプション、デフォルトは `true` ): `lazy="false"` とすると、遅延フェッチが使用できません。

各サブクラスでは、永続プロパティとサブクラスを定義します。 <version> と <id> プロパティは、ルートクラスから継承されると仮定されます。階層構造におけるサブクラスは、ユニークな discriminator-value を定義しなければなりません。 none が指定されると、完全修飾された Java クラス名が使われます。

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

`5.1.18. joined-subclass`

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

<joined-subclass
        name="ClassName"
        table="tablename"
        proxy="ProxyInterface"
        lazy="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
>

	`name`：サブクラスの完全修飾されたクラス名。
	`table` :サブクラステーブルの名前。
	`proxy` (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。
	`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章継承マッピング.

`5.1.19. union-subclass`

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

<union-subclass
        name="ClassName"
        table="tablename"
        proxy="ProxyInterface"
        lazy="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
>

	`name`：サブクラスの完全修飾されたクラス名。
	`table` :サブクラステーブルの名前。
	`proxy` (オプション): 遅延初期化プロキシに使用するクラスやインターフェースを指定します。
	`lazy` (オプション、デフォルトは `true` ): `lazy="false"` とすると、遅延フェッチが使用できません。

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

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

`5.1.20. join`

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

<join
        table="tablename"
        schema="owner"
        catalog="catalog"
        fetch="join|select"
        inverse="true|false"
        optional="true|false">

        <key ... />

        <property ... />
        ...
</join
>

	`table` :結合したテーブルの名前
	`schema` (オプション): ルートの `<hibernate-mapping>` 要素で指定したスキーマ名をオーバーライドします。
	`catalog` (オプション): ルートの `<hibernate-mapping>` 要素で指定したカタログ名をオーバーライドします。
	`fetch` (オプション - デフォルトは `join` ): `join` を設定した場合、 Hibernate はデフォルトで、クラスやスーパークラスで定義された `<join>` を検索するのに内部結合を使い、サブクラスで定義された `<join>` を検索するのに外部結合を使います。 `select` を設定した場合には、 Hibernate はサブクラスで定義された `<join>` の選択に順次選択を使います。この場合、行がサブクラスのインスタンスを代表することがわかった場合にのみ発行されます。内部結合はクラスやそのスーパークラスで定義された `<join>` を検索するために使用します。
	`inverse` (オプション - デフォルトは `false` ): もし可能であれば、 Hibernate はこの結合で定義されているプロパティに対し挿入や更新を行いません。
	`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>

    ...

この特徴はしばしばレガシーデータモデルに対してのみ有用ですが、クラスよりも少ないテーブルと、きめの細かいドメインモデルを推奨します。しかし後で説明するように、１つのクラス階層で継承のマッピング戦略を切り替える時には有用です。

`5.1.21. Key`

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

<key
        column="columnname"
        on-delete="noaction|cascade"
        property-ref="propertyName"
        not-null="true|false"
        update="true|false"
        unique="true|false"
/>

	`column` (オプション):外部キーカラムの名前。ネストした `<column>` カラムによっても指定されます。
	`on-delete` (オプション, デフォルトは `noaction`): 外部キー制約がデータベースレベルでカスケード削除が可能かどうかを指定します。
	`property-ref` (オプション): オリジナルテーブルの主キーではないカラムを参照する外部キーを指定します (レガシーデータに対して提供されます)。
	`not-null` (オプション): 外部キーカラムが null 値を許容しないことを指定します (このことは外部キーが主キーの一部であることを暗黙的に示します)。
	`update` (オプション): 外部キーを決して更新してはならないことを指定します (このことは外部キーが主キーの一部であることを暗黙的に示します)。
	`unique` (オプション): 外部キーがユニーク制約を持つべきであることを指定します (このことは外部キーが主キーの一部であることを暗黙的に示します)。

削除のパフォーマンスが重要であるシステムには、すべてのキーを on-delete="cascade" と定義することを推奨します。そうすることで Hibernate は、 DELETE 文を毎回発行する代わりに、データベースレベルの ON CASCADE DELETE 制約を使用します。この特徴はバージョン付けられたデータに対する Hibernate の通常の楽観的ロック戦略を無視するということに注意してください。

not-null と update 属性は、単方向一対多関連の時には有用です。単方向一対多関連を null を許容しない外部キーにマッピングするときは、 <key not-null="true"> を使ってキーカラムを宣言しなくてはなりません。

`5.1.22. column と formula 要素`

column 属性を記述できる任意のマッピング要素はまた、 <column> サブ要素も記述できます。同様に <formula> も formula 属性の代替手段です。


<column

        name="column_name"

        length="N"

        precision="N"

        scale="N"

        not-null="true|false"

        unique="true|false"

        unique-key="multicolumn_unique_key_name"

        index="index_name"

        sql-type="sql_type_name"

        check="SQL expression"

        default="SQL expression"

        read="SQL expression"

        write="SQL expression"/>


<formula

>SQL expression</formula

>

Most of the attributes on column provide a means of tailoring the DDL during automatic schema generation. The read and write attributes allow you to specify custom SQL that Hibernate will use to access the column's value. For more on this, see the discussion of column read and write expressions.

The column and formula elements can even be combined within the same property or association mapping to express, for example, exotic join conditions.


<many-to-one name="homeAddress" class="Address"

        insert="false" update="false">

    <column name="person_id" not-null="true" length="10"/>

    <formula

>'MAILING'</formula>

</many-to-one

>

`5.1.23. Import`

アプリケーションに同じ名前の2つの永続クラスがあり、 Hibernate クエリで完全修飾された（パッケージの）名前を指定したくないと仮定します。そのような場合は auto-import="true" に頼らず、クラスが「インポート」されたものであると明示できます。明示的にマッピングされていないクラスやインターフェースでさえもインポートできます。


<import class="java.lang.Object" rename="Universe"/>

<import
        class="ClassName"
        rename="ShortName"
/>

	`class`： Java クラスの完全修飾されたクラス名。
	`rename` （オプション - デフォルトは修飾されていないクラス名）：クエリ言語で使われる名前。

`5.1.24. Any`

プロパティマッピングにはさらにもう1つの型があります。 <any> マッピング要素は、複数のテーブルからクラスへのポリモーフィックな関連を定義します。この型のマッピングには必ず複数のカラムが必要です。1番目のカラムは関連エンティティの型を保持します。残りのカラムは識別子を保持します。この種類の関連には外部キー制約を指定することはできません。そのためこれは最も使われることのない（ポリモーフィックな）関連のマッピング方法です。非常に特別な場合（例えば、検査ログやユーザーセッションデータなど)に限って、これを使うべきです。

meta-type により、アプリケーションはカスタム型を指定できます。このカスタム型はデータベースカラムの値を、 id-type で指定した型の識別子プロパティを持った永続クラスへマッピングします。 meta-type の値からクラス名へのマッピングを指定しなければなりません。


<any name="being" id-type="long" meta-type="string">

    <meta-value value="TBL_ANIMAL" class="Animal"/>

    <meta-value value="TBL_HUMAN" class="Human"/>

    <meta-value value="TBL_ALIEN" class="Alien"/>

    <column name="table_name"/>

    <column name="id"/>

</any

>

<any
        name="propertyName"
        id-type="idtypename"
        meta-type="metatypename"
        cascade="cascade_style"
        access="field|property|ClassName"
        optimistic-lock="true|false"
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any
>

	`name`：プロパティ名。
	`id-type`：識別子の型。
	`meta-type`（オプション - デフォルトは `string` ）：ディスクリミネータマッピングで許された型。
	`cascade`（オプション - デフォルトは `none` ）：カスケードのスタイル。
	`access` (オプション - デフォルトは `property` ): Hibernate がプロパティの値にアクセスするために使用すべき戦略。
	`optimistic-lock` (オプション - デフォルトは `true` ): このプロパティの更新に楽観ロックの取得を要求するかどうかを指定します。言い換えれば、このプロパティがダーティであるときにバージョンを増やすべきかを定義します。

`5.2. Hibernate の型`


<property name="twoStrings" type="org.hibernate.test.DoubleStringType">

    <column name="first_string"/>

    <column name="second_string"/>

</property

>

<column> タグで、プロパティを複数のカラムへマッピングできることに注目してください。

CompositeUserType 、 EnhancedUserType 、 UserCollectionType 、 UserVersionType インターフェースは、より特殊な使用法に対してのサポートを提供します。

マッピングファイル内で UserType へパラメータを提供できます。このためには、 UserType は org.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.

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

ある永続クラスに、一つ以上のマッピングを提供することが出来ます。この場合、マッピングする２つのエンティティのインスタンスを明確にするために、エンティティ名を指定しなければなりません (デフォルトではエンティティ名はクラス名と同じです。)。 Hibernate では、永続オブジェクトを扱うとき、クエリを書き込むとき、指定されたエンティティへの関連をマッピングするときに、エンティティ名を指定しなければなりません。

<class name="Contract" table="Contracts"
        entity-name="CurrentContract">
    ...
    <set name="history" inverse="true"
            order-by="effectiveEndDate desc">
        <key column="currentContractId"/>
        <one-to-many entity-name="HistoricalContract"/>
    </set>
</class>

<class name="Contract" table="ContractHistory"
        entity-name="HistoricalContract">
    ...
    <many-to-one name="currentContract"
            column="currentContractId"
            entity-name="CurrentContract"/>
</class
>

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

マッピングドキュメントでテーブルやカラムの名前をバッククォートで囲むことで、 Hibernate で生成された SQL 中の識別子を引用させることができます。 Hibernate は SQL の Dialect に対応する、正しい引用スタイルを使います（普通はダブルクォートですが、 SQL Server ではかぎ括弧、 MySQL ではバッククォートです）。


<class name="LineItem" table="`Line Item`">

    <id name="id" column="`Item Id`"/><generator class="assigned"/></id>

    <property name="itemNumber" column="`Item #`"/>

    ...

</class

>

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

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

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

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

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

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

以下は EJB のエンティティ Bean として注釈された POJO クラスの例です:

@Entity(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

}

`注記`

JDK5.0 のアノテーション (と JSR-220) のサポートは進行中の作業であり、完全ではないことに注意してください。さらに詳しい情報は Hibernate のアノテーションモジュールを参照してください。

`5.6. 生成プロパティ`

生成プロパティとは、データベースによって生成された値を持つプロパティです。通常、 Hibernate アプリケーションは、データベースが値を生成したプロパティを含むオブジェクトをリフレッシュする必要がありました。しかし、プロパティが生成されたということをマークすることで、アプリケーションはリフレッシュの責任を Hibernate に委譲します。基本的に、生成プロパティを持つと定義したエンティティに対して Hibernate が INSERT や UPDATE の SQL を発行した後すぐに、生成された値を読み込むための SELECT SQL が発行されます。

Properties marked as generated must additionally be non-insertable and non-updateable. Only versions, timestamps, and simple properties, can be marked as generated.

never (デフォルト) - 与えられたプロパティの値は、データベースから生成されないことを意味します。

insert: the given property value is generated on insert, but is not regenerated on subsequent updates. Properties like created-date fall into this category. Even though version and timestamp properties can be marked as generated, this option is not available.

always - 挿入時も更新時もプロパティの値が生成されることを示します。

`5.7. Column read and write expressions`

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.

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

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

>