第15章 ツールセット・ガイド

Hibernateを使ったラウンドトリップ・エンジニアリングはHibernateプロジェクトの一部として保守されているコマンドライン・ツールのセットを使うことで可能で、XDoclet、Middlegen、AndroMDAがHibernateサポートに組み込まれています。

Hibernateメインパッケージは最も重要なツールになっています(実行時にHibernateの「中」からも使われます)。:

Hibernateプロジェクトにより直接提供された他のツール群は、Hibernate Extensionsという別のパッケージになっています。このパッケージは以下のようなタスクのためのツールを含んでいます。:

実はHibernate Extentionsにはもうひとつ、実用的なツールddl2hbmがありますが、非推奨であり、もはや保守されていません。Middlegenの方が同じタスクに対してより良い仕事を行ないます。

以下にHibernateをサポートするサード・パーティ・ツールを挙げます。:

これらサード・パーティ・ツールはこのリファレンスには文書化されていません。最新の情報はHibernateの ウェブサイトを参照してください。(サイトのスナップショットはHibernateメイン・パッケージに含まれています。

15.1. スキーマ生成

DDLはコマンドライン・ユーティリティによりマッピング・ファイルから生成することができます。バッチファイルはHibernateのコア・パッケージのhibernate-x.x.x/binディレクトリにあります。

生成されるスキーマはエンティティとコレクション・テーブルへの参照完全性制約(主キーと外部キー)を含みます。また、マッピングする識別子ジェネレータに対しテーブルとシーケンスが作成されます。

このツールを使うときは、hibernate.dialectプロパティでSQLの方言を指定しなければなりません

15.1.1. スキーマのカスタマイズ

多くのHibernateのマッピング要素ではオプションのlengthという名の属性を定義しています。この属性でカラム長を設定することができます(または数値/小数型のデータの精度を設定できます)。

not-null属性(テーブルのカラムへのNOT NULL制約を生成する)とunique属性(テーブルのカラムへのUNIQUE制約を生成する)が設定できるタグもあります。

カラムのインデックスの名前を特定するためのindex属性を指定できるタグもあります。unique-key属性はカラムをシングル・ユニットのキー制約でグループ化するために使われます。現在、unique-key属性で指定された値は制約の命名には使われず、マッピング・ファイルでカラムをグループ化することにのみ使われます。

例:

<property name="foo" type="string" length="64" not-null="true"/>

<many-to-one name="bar" foreign-key="fk_foo_bar" not-null="true"/>

<element column="serial_number" type="long" not-null="true" unique="true"/>

もうひとつの方法として、これらの要素は子の<column>要素も持つことができます。これは特にマルチ・カラム型に対して有効です。

<property name="foo" type="string">
    <column name="foo" length="64" not-null="true" sql-type="text"/>
</property>

<property name="bar" type="my.customtypes.MultiColumnType"/>
    <column name="fee" not-null="true" index="bar_idx"/>
    <column name="fi" not-null="true" index="bar_idx"/>
    <column name="fo" not-null="true" index="bar_idx"/>
</property>

sql-type属性で、デフォルトのHibernate型のマッピングをSQLのデータ型にすることができます。

check属性でチェック制約を指定することができます。

<property name="foo" type="integer">
    <column name="foo" check="foo > 10"/>
</property>

<class name="Foo" table="foos" check="bar < 100.0">
    ...
    <property name="bar" type="float"/>
</class>

表 15.1. まとめ

まとめ説明
lengthnumberカラム長/小数の精度
not-nulltrue|falseカラムがnull値を取らないことを指定す
uniquetrue|falseカラムがユニーク制約を持つことを指定する
indexindex_name(マルチ・カラム)インデックスの名前を指定する
unique-keyunique_key_nameマルチ・カラムのユニーク制約の名前を指定する
foreign-keyforeign_key_name <one-to-one>、<many-to-one>、<many-to-many>マッピング要素を使って、関連に対し生成された外部キー制約の名前を指定する。inverse="true"側はSchemaExportにより考慮されないことに注意してください。
sql-typecolumn_type デフォルトのカラム型をオーバーライドする(<column>要素の属性のみ)
checkSQL expression カラムやテーブルにSQLのチェック制約を作成する

15.1.2. ツールの実行

SchemaExportは標準出力に対してDDLスクリプトを書き出し、またはDDL文を実行します。

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2ddl.SchemaExport options mapping_files

表 15.2. SchemaExportのコマンドライン・オプション

オプション説明
--quietスクリプトを標準出力に出力しません
--dropテーブルを削除するだけです
--textデータベースにエクスポートしません
--output=my_schema.ddlDDLスクリプトをファイルに出力します
--config=hibernate.cfg.xmlXMLファイルからHibernateの定義フィファイルを読み込みます
--properties=hibernate.propertiesファイルからデータベースプロパティを読み込みます
--formatスクリプト用に生成されたSQLをフォーマットします
--delimiter=xスクリプトの行区切り文字を設定します

アプリケーションにSchemaExportを組み込むこともできます:

Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);

15.1.3. プロパティ

データベースのプロパティを指定することができます。

  • システム・プロパティとして-D<property>

  • hibernate.properties内で指定する

  • --propertiesで指定されたファイル内で指定する

必要なプロパティは以下のようになります。:

表 15.3. SchemaExportのコネクション・プロパティ

プロパティ名説明
hibernate.connection.driver_classJDBCドライバーのクラス
hibernate.connection.urlJDBCのURL
hibernate.connection.usernameデータベースのユーザ
hibernate.connection.passwordユーザのパスワード
hibernate.dialect方言

15.1.4. Antの使用

Antのビルド・スクリプトからSchemaExportを呼ぶことができます。:

<target name="schemaexport">
    <taskdef name="schemaexport"
        classname="net.sf.hibernate.tool.hbm2ddl.SchemaExportTask"
        classpathref="class.path"/>
    
    <schemaexport
        properties="hibernate.properties"
        quiet="no"
        text="no"
        drop="no"
        delimiter=";"
        output="schema-export.sql">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaexport>
</target>

もしプロパティファイルやコンフィグファイルを指定しなければ、SchemaExportTaskは通常のなAntプロジェクトのプロパティを代わりに使用します。言いかえれば、外部の設定ファイルやプロパティ・ファイルを望まないし必要としなければ、build.xmlあるいはbuild.propertiesの設定プロパティをhibernate.*としてもよい。

15.1.5. インクリメンタルなスキーマ更新

SchemaUpdateツールは既存のスキーマをインクリメンタルに更新します。SchemaUpdateはJDBCメタデータAPIに強く依存します。そのためすべての、JDBCドライバでうまくいくとは限らないことに注意してください。

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files

表 15.4. SchemaUpdateのコマンドライン・オプション

オプション説明
--quiet標準出力にスクリプトを出力しません
--properties=hibernate.propertiesファイルからデータベース・プロパティを読み込みます

アプリケーションにSchemaUpdateを組み込むことができます。:

Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);

15.1.6. インクリメンタルなスキーマ更新に対するAntの使用

AntスクリプトからSchemaUpdateをコールすることができます:

<target name="schemaupdate">
    <taskdef name="schemaupdate"
        classname="net.sf.hibernate.tool.hbm2ddl.SchemaUpdateTask"
        classpathref="class.path"/>
    
    <schemaupdate
        properties="hibernate.properties"
        quiet="no">
        <fileset dir="src">
            <include name="**/*.hbm.xml"/>
        </fileset>
    </schemaupdate>
</target>

15.2. コード生成

Hibernateのコードジェネレータを使い、HibernateのマッピングファイルからJavaでの実装クラスのスケルトンを生成することができます。このツールはHibernate Extensionパッケージに含まれています。(別途ダウンロード)

hbm2javaはマッピング・ファイルを構文解析し、十分に機能するJavaソースファイルを生成します。このように hbm2javaを使い、単に.hbmファイルを作成するだけで、Javaファイルをハンドコードする煩わしさから解放されます。

java -cp hibernate_classpaths net.sf.hibernate.tool.hbm2java.CodeGenerator options mapping_files

表 15.5. コードジェネレータのコマンドライン・オプション

オプション説明
--output=output_dir生成されるコードのルートディレクトリ
--config=config_filehbm2javaを設定するオプションのファイル

15.2.1. 設定ファイル(オプション)

設定ファイルはソースコードの複数の「レンダラ」を指定する方法と、「グローバル」スコープの<meta>属性を宣言する方法を提供します。これについての詳細は<meta>属性の節を見てください。

<codegen>
    <meta attribute="implements">codegen.test.IAuditable</meta>
    <generate renderer="net.sf.hibernate.tool.hbm2java.BasicRenderer"/>
    <generate
        package="autofinders.only"
        suffix="Finder"
        renderer="net.sf.hibernate.tool.hbm2java.FinderRenderer"/>
</codegen>

この構成ファイルはグローバル・メタ属性の"implements"を宣言し、デフォルトのレンダラ(BasicRenderer)と ファインダを生成するレンダラの二つを指定しています(詳しくは次の「BasicFinder生成」をご覧ください)。

2番目のレンダラはパッケージ属性とサフィックス属性とともに提供されます。

パッケージ属性では、.hbmファイル内で指定されたパッケージスコープの代わりに、このレンダラから生成されたソースファイルの配置場所を指定します。

サフィックス属性では、生成されるファイルのサフィックスを指定します。例えばFoo.javaというファイルを、代わりにFooFinder.javaとすることができます。

<generate>要素に<param>属性を付け加えることで、任意のパラメータを(注:)投げることも可能です。

hbm2javaは現在generate-concrete-empty-classesパラメータをサポートします。これはBasicRendererに対し、ベースクラスを拡張する、空の具象クラスだけを生成するという情報を与えます。以下のonfig.xmlの例はこの特徴を示します。

            <codegen>
              <generate prefix="Base" renderer="net.sf.hibernate.tool.hbm2java.BasicRenderer"/> 
              <generate renderer="net.sf.hibernate.tool.hbm2java.BasicRenderer">
                <param name="generate-concrete-empty-classes">true</param>
                <param name="baseclass-prefix">Base</param>
              </generate>
            </codegen>

このconfig.xmlファイルは2つのレンダラを設定することに注意してください。一つは基底クラスを生成するもので、もう一つは空の具象クラスを生成するものです。

15.2.2. メタ属性

<meta>タグはhbm.xmlに情報を付加する簡単な方法です。これによりツールがHibernateのコアに直接関係しない情報を保存し、読みこむための自然な場所を保持します。

"protected"なセッタだけを生成する、あるインタフェースの集合を常に実装する、またはある基底クラスを常に拡張するといった事をhbm2javaに知らせるために<meta>タグを使用することができます。:

下の例は以下のようなコードを生成します(わかりやすいようコードは短くしてあります)。

<class name="Person">
    <meta attribute="class-description">
        Javadoc for the Person class
        @author Frodo
    </meta>
    <meta attribute="implements">IAuditable</meta>
    <id name="id" type="long">
        <meta attribute="scope-set">protected</meta>
        <generator class="increment"/>
    </id>
    <property name="name" type="string">
        <meta attribute="field-description">The name of the person</meta>
    </property>
</class>

Javadocコメントとprotectedなセット・メソッドに注目してください。:

// default package

import java.io.Serializable;
import org.apache.commons.lang.builder.EqualsBuilder;
import org.apache.commons.lang.builder.HashCodeBuilder;
import org.apache.commons.lang.builder.ToStringBuilder;

/** 
 *         Javadoc for the Person class
 *         @author Frodo
 *     
 */
public class Person implements Serializable, IAuditable {

    /** identifier field */
    public Long id;

    /** nullable persistent field */
    public String name;

    /** full constructor */
    public Person(java.lang.String name) {
        this.name = name;
    }

    /** default constructor */
    public Person() {
    }

    public java.lang.Long getId() {
        return this.id;
    }

    protected void setId(java.lang.Long id) {
        this.id = id;
    }

    /** 
     * The name of the person
     */
    public java.lang.String getName() {
        return this.name;
    }

    public void setName(java.lang.String name) {
        this.name = name;
    }

}

表 15.6. サポートしているメタ・タグ

属性説明
class-descriptionクラスのJavadocとして挿入されます
field-descriptionフィールド・プロパティのJavadocとして挿入されます
interfacetrueなら、クラスの代わりにインターフェイスが生成されます
implementsクラスが実装すべきインターフェイス
extendsクラスが拡張すべきクラス(サブクラスには無視されます)
generated-class生成される実際のクラスの名前を上書きします
scope-classクラスのスコープ
scope-setセッタメソッドのスコープ
scope-getゲッタメソッドのスコープ
scope-field実際のフィールドのスコープ
use-in-tostringtoString()にこのプロパティを含めます
implement-equalsこのクラスにequals()hashCode()メソッドを含めます
use-in-equalsequals()hashCode()メソッド内にこのプロパティを含めます
boundプロパティにpropertyChangeListenerサポートを追加します
constrainedプロパティへのbound + vetoChangeListenerサポート
gen-propertyfalseならプロパティが生成されません(注意して使いましょう)
property-typeプロパティのデフォルトの型をオーバーライドします。単なるObjectクラスの代わりに 具体的な型を指定するタグとともに使ってください。
class-codeクラスの最後に挿入する特別なコード
extra-importすべてのimportの後に挿入する特別なimport
finder-method以下の「基本ファインダ・ジェネレータ」を見てください
session-method以下の「基本ファインダ・ジェネレータ」を見てください

<meta>を通して定義された属性はhbm.xmlファイル内のデフォルトの"inherited"ごとにあります。

これはどういうことでしょうか?これは例えば、もしすべてのクラスでIAuditableを実装したいならばhbm.xmlファイルの先頭で、<hibernate-mapping>のすぐ後に、<meta attribute="imp lements">IAuditable</meta>を追加するだけでいいということです。これで、そのhbm.xmlファイルで定義されているすべてのクラスはIAuditableを実装することになります!(ただし、そのクラスが"implements"メタ属性を持っているときは除きます。というのはローカルで指定されたメタタグは継承されたメタタグを無効にし、置き換えるからです。)

注意:これはすべての <meta>タグに当てはまります。そのため例えば、デフォルトであるprivateの代わりにすべてのフィールドをprotectedと指定するなどに使うことができます。このことは、たとえば<class>タグのすぐ後に<meta attribute="scope-field">protected</meta>を追加することで、クラスのすべてのフィールドがプロテクティドになります。

継承された<meta>タグを無効にするには、単に属性をinherit="false"と指定するればよく、例えば<meta attribute="scope-class" inherit="false">public abstract</meta>は"クラススコープ"を現在のクラスに制限し、サブクラスには適用されません。

15.2.3. BasicFinderジェネレータ

今ではHibernateプロパティに対しhbm2javaを使って、BasicFinderを生成させることが可能になりました。これによりhbm.xmlファイルに二つのことが必要になります。

一つめは、どのフィールドに対してファインダを生成したいのか指定する必要があります。以下のようにプロパティ・タグ中のメタ・ブロックを使って指定します。:

<property name="name" column="name" type="string">
     <meta attribute="finder-method">findByName</meta>
</property>

ファインダ・メソッドの名前はメタ・タグで囲まれたテキストになります。

二つめは、以下のフォーマットのようなhbm2java用の構成ファイルを作成する必要があります。

<codegen>
    <generate renderer="net.sf.hibernate.tool.hbm2java.BasicRenderer"/>
    <generate suffix="Finder" renderer="net.sf.hibernate.tool.hbm2java.FinderRenderer"/>
</codegen>

そしてhbm2java --config=xxx.xmlパラメータを使います。ただしxxx.xmlは作成した構成ファイルです。

オプションのパラメータはクラスレベルにおいてのメタタグで、以下のようなフォーマットです:

<meta attribute="session-method">
    com.whatever.SessionTable.getSessionTable().getSession();
</meta>

もしThread Local Sessionパターンを使うなら、Sessionを得る方法を指定します。(Hibernateのウェブサイトのデザインパターン・エリアに文書化されています)。

15.2.4. Velocityベースのレンダラ/ジェネレータ

今では、代替のレンダリング・メカニズムとしてvelocityが利用可能になりました。以下のconfig.xmlは、velocityレンダラを使うためにはhbm2javaをどのように設定すればよいかを示しています。

    <codegen>
     <generate renderer="net.sf.hibernate.tool.hbm2java.VelocityRenderer">
      <param name="template">pojo.vm</param>
     </generate>
    </codegen>

templateという名前のパラメータは、使いたいvelocityのマクロ・ファイルへのリソース・パスです。このファイルはhbm2javaのクラスパス上に配置することで利用可能になります。このようにpojo.vmがあるディレクトリをantのタスクやシェルスクリプトに追加するのを忘れないようにしてください(デフォルトのロケーションは./tools/src/velocityです)。

カレントのpojo.vmがJavaBeansの最も基本的な部分しか生成しないことに注意してください。Velocityベースのレンダラ/ジェネレータはデフォルトのレンダラほど完全でも特徴豊かではありません。基本的に多くのメタタグはサポートされていません。

15.3. マッピング・ファイルの生成

マッピング・ファイルのスケルトンはMapGeneratorというコマンドライン・ユーティリティを使ってコンパイルされた永続クラスから生成できます。このユーティリティはHibernate Extensionパッケージの一部です。

Hibernateのマッピング・ジェネレータはコンパイルされたクラスからマッピングを生成するメカニズムを提供します。これにはプロパティを見つけるのにJavaのリフレクションを使い、プロパティの型から適切なマッピングを推測するために経験則を用いています。生成されたマッピングは開始点としてのみ意図されています。ユーザからの追加入力なしでは、完全なHibernateマッピングを生成することはできません。しかしながら、このツールはマッピングを生成する"退屈な"繰り返しをいくらか減らします。

クラスは一度に1つのマッピングに追加されます。このツールはHibernate persistableではないと判断したクラスを無視します。

クラスをHibernate persistableにするには、以下のようにします。

  • プリミティブ型ではいけません

  • 配列であってはいけません

  • インターフェイスであってはいけません

  • 入れ子クラスではいけません

  • デフォルトコンストラクタ(引数なし)を持たなければなりません。

実際にはインタフェースと入れ子クラスはHibernateで永続化できることに注意してください。しかしこれは普通ユーザが永続化したいとは思わないものです。

MapGeneratorは、同じデータベースのテーブルにできるだけ多くのHiberante Persistableなスーパークラスを追加するよう意図された、すべてのクラス階層をたどっていきます。検索はプロパティがcandidate UID namesのリストに名前が見つかるとすぐに終了します。

デフォルトのcandidate UID プロパティ名のリストは: uid, UID, id, ID, key, KEY, pk, PKです。

クラス内の2つのメソッド、セッタとゲッタが、セッタの第一引数が引数なしのゲッタの戻り値と同じであり、セッタの戻り値がvoidである場合、プロパティは発見されます。さらには、セッタの名前はsetで始まらなければならず、ゲッタの名前はgetか、プロパティの型がbooleanのときはisで始まらなければなりません。どちらの場合も、名前の残りの部分は一致しなければなりません。もし二文字めが小文字なら、プロパティ名の頭文字が小文字になることを除けば、この一致する部分はプロパティ名になります。

それぞれのプロパティのデータベースの型を決定する規則はこのようになります:

  1. もしJavaの型がHibernate.basic()ならば、プロパティはその型のカラムです。

  2. hibernate.type.Type カスタム型と PersistentEnum型についても同様に、単純なカラムが使われます。

  3. プロパティの型が配列なら、Hibernateの配列が使われMapGeneratorは配列の要素の型をリフレクトするよう試みます。

  4. もしプロパティがjava.util.List, java.util.Map, or java.util.Setの型を持つならば、対応するHibernate型が使われますが、MapGeneratorは決してこれらの型の内部は処理しません。

  5. もしプロパティの型が他のクラスなら、MapGeneratorはすべてのクラスが実行されるまでデータベースの表現の決定保留します。この時点で、もし上述のようなスーパークラスの検索を通してクラスが発見されるとすれば、プロパティはmany-to-one関連です。もしクラスがどれかプロパティを持つなら、それはcomponentとしてマッピングします。さもなければ、それはシリアライズ可能でも永続化可能でもありません。

15.3.1. ツールの実行

ツールはXMLマッピングを標準出力と/またはファイルに書き込みます。

ツールを起動するとき、コンパイルされたクラスをクラスパスに通しておかなければなりません。

java -cp hibernate_and_your_class_classpaths net.sf.hibernate.tool.class2hbm.MapGenerator options and classnames

コマンドラインまたはインタラクティブの二つの操作モードがあります。

インタラクティブモードはコマンドラインの引数--interactを一つ指定することで選択されます。このモードはプロンプトの応答をコンソールに出力します。それを使って、XXXがUIDプロパティのときuid=XXXコマンドを使ってそれぞれのクラスにUIDのプロパティ名を設定することができます。他の代替コマンドは単に完全限定クラス名で、XMLを生成するコマンドや終了するコマンドがあります。

コマンドライン・モードにおいて、引き数は処理されるクラスの完全限定クラス名が組み込まれているオプションです。オプションのほとんどは複数回使われるものと意図されていて、どの使い方も続くクラスに影響を及ぼします。

表 15.7. MapGeneratorのコマンドライン・オプション

オプション説明
--quiet標準出力にO-Rマッピングを出力しません
--setUID=uidUIDの候補とするリストをひとつのUIDに設定します
--addUID=uid候補のUIDのリストの先頭にUIDを追加します
--select=mode続いて追加されたクラスに対して、選択モードmode(例えば, distinct または all)を使うモード
--depth=<small-int>続いて追加されたクラス対して、コンポーネント・データの再帰の深さを制限します
--output=my_mapping.xmlO-R Mappingをファイルに出力します
full.class.Nameクラスをマッピングに追加します
--abstract=full.class.Name以下を見てください

抽象スイッチはマップ・ジェネレータツールが特定のスーパークラスを無視するようにします。 それは共通の継承を持つクラスが一つの大きなテーブルにマッピングされないようにするためです。 例えば、これらのクラスの階層構造を考えてみてください:

Animal-->Mammal-->Human

Animal-->Mammal-->Marsupial-->Kangaroo

もし--abstractスイッチが使われなければ、すべてのクラスはAnimalのサブクラスとしてマッピングされます。 その結果、どのサブクラスが実際に格納されたのかを示すディスクリミネータ・カラムと、すべてのクラスのすべてのプロパティを含んだ一つの大きなテーブルが付け加えることになります。もし MammalabstractとマークされるならHumanMarsupialは別の<class>定義にマッピングされ、別のテーブルに格納されます。Marsupialがaabstracttとしてマークされなければ、KangarooMarsupialのサブクラスになってしまいます。