hibernate-orm/doc/reference/ja/modules/toolset_guide.xml

635 lines
27 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="Shift_JIS"?>
<chapter id="toolsetguide" revision="2">
<title>Toolset Guide
ツールセットガイド
</title>
<para>
Hibernateを使ったラウンドトリップエンジニアリングは、
Eclipseプラグインやコマンドラインツール、もちろんAntタスクを使うことで可能です。
</para>
<para>
<emphasis>Hibernate Tools</emphasis> は現在、既存データベースのリバースエンジニアリングのAntタスクに加えて、EclipseIDEのプラグインを含みます。
</para>
<itemizedlist>
<listitem><para>
<emphasis>マッピングエディタ:</emphasis>
HibernateのXMLマッピングファイル用のエディタで、
自動補完と構文強調表示をサポートしています。クラス名やプロパティ/フィールド名に対する自動補完もサポートし、
通常のXMLエディタよりも強力です。
</para></listitem>
<listitem><para>
<emphasis>Console:</emphasis>
コンソールはエクリプスの新しいビューです。
コンソールコンフィギュレーションのツリーオーバービューに加えて、永続クラスとその関連の相互作用ビューも得られます。
データベースにHQLを実行し、結果を直接エクリプス上で見ることができます。
</para></listitem>
<listitem><para>
<emphasis>開発ウィザード</emphasis>
HibernateのEclipseツールはいくつかのウィザードを提供します。
ウィザードを使ってHibernateの設定ファイル(cfg.xml)をすばやく生成したり、
既存のデータベーススキーマをPOJOのソースファイルとHibernateのマッピングファイルへと、
完全にリバースエンジニアリングすることができます。
リバースエンジニアリングウィザードはカスタマイズ可能なテンプレートをサポートします。
</para></listitem>
<listitem><para>
<emphasis>Ant Tasks:</emphasis>
</para></listitem>
</itemizedlist>
<para>
より詳しい情報は <emphasis>Hibernate Tools</emphasis> パッケージとそのドキュメントを参照してください。
</para>
<para>
しかし、Hibernateのメインパッケージは <emphasis>SchemaExport</emphasis>
別名 <literal>hbm2ddl</literal> も含みます(Hibernate内でオンザフライで使用できます)。
</para>
<sect1 id="toolsetguide-s1" revision="2">
<title>スキーマの自動生成</title>
<para>
DDLはHibernateユーティリティによりマッピングファイルから生成することができます。
生成されたスキーマはエンティティやコレクションのテーブルに対する参照整合性制約(主キーと外部キー)を含みます。
テーブルとシーケンスはマッピングする識別子ジェネレータに対して生成されます。
</para>
<para>
DDLはベンダー依存なので、このツールを使うときは、<literal>hibernate.dialect</literal>
プロパティでSQLの <literal>方言</literal> を指定 <emphasis>しなければなりません</emphasis>
</para>
<para>
まず、生成されるスキーマを改善するように、マッピングファイルをカスタマイズしてください。
</para>
<sect2 id="toolsetguide-s1-2" revision="3">
<title>スキーマのカスタマイズ</title>
<para>
多くのHibernateのマッピング要素では、オプションの <literal>length</literal> という名の属性を定義しています。
この属性でカラム長を設定することができます(またはNUMERIC/DECIMAL型のデータの精度を設定できます)。
</para>
<para>
<literal>not-null</literal> 属性(テーブルのカラムへ <literal>NOT NULL</literal> 制約を生成する)と
<literal>unique</literal> 属性(テーブルのカラムへ <literal>UNIQUE</literal> 制約を生成する)が設定できるタグもあります。
</para>
<programlisting><![CDATA[<many-to-one name="bar" column="barId" not-null="true"/>]]></programlisting>
<programlisting><![CDATA[<element column="serialNumber" type="long" not-null="true" unique="true"/>]]></programlisting>
<para>
<literal>unique-key</literal> 属性はカラムをグループ化して一つのキー制約にするために使われます。
現在、<literal>unique-key</literal> 属性で指定された値は制約の指定には <emphasis>使われず</emphasis>
マッピングファイルでカラムをグループ化することにのみ使われます。
</para>
<programlisting><![CDATA[<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
<property name="employeeId" unique-key="OrgEmployee"/>]]></programlisting>
<para>
<literal>index</literal> 属性はマッピングするカラムを使って生成したインデックスの名前を指定します。
複数カラムを1つのインデックスにグループ化できます。単に、同じインデックス名を指定するだけです。
</para>
<programlisting><![CDATA[<property name="lastName" index="CustName"/>
<property name="firstName" index="CustName"/>]]></programlisting>
<para>
<literal>foreign-key</literal> 属性は、生成された外部キー制約の名前をオーバーライドするために使用できます。
</para>
<programlisting><![CDATA[<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>]]></programlisting>
<para>
多くのマッピング要素は、子 <literal>&lt;column&gt;</literal> 要素を記述できます。これは複数カラム型のマッピングには特に有用です。
</para>
<programlisting><![CDATA[<property name="name" type="my.customtypes.Name"/>
<column name="last" not-null="true" index="bar_idx" length="30"/>
<column name="first" not-null="true" index="bar_idx" length="20"/>
<column name="initial"/>
</property>]]></programlisting>
<para>
<literal>default</literal> 属性はカラムのデフォルト値を指定します
(マッピングしたクラスの新しいインスタンスを保存する前に、
マッピングしたプロパティへ同じ値を代入すべきです)。
</para>
<programlisting><![CDATA[<property name="credits" type="integer" insert="false">
<column name="credits" default="10"/>
</property>]]></programlisting>
<programlisting><![CDATA[<version name="version" type="integer" insert="false">
<column name="version" default="0"/>
</property>]]></programlisting>
<para>
<literal>sql-type</literal> 属性で、デフォルトのHibernate型からSQLのデータ型へのマッピングをオーバーライドできます。
</para>
<programlisting><![CDATA[<property name="balance" type="float">
<column name="balance" sql-type="decimal(13,3)"/>
</property>]]></programlisting>
<para>
<literal>check</literal> 属性でチェック制約を指定することができます。
</para>
<programlisting><![CDATA[<property name="foo" type="integer">
<column name="foo" check="foo > 10"/>
</property>]]></programlisting>
<programlisting><![CDATA[<class name="Foo" table="foos" check="bar < 100.0">
...
<property name="bar" type="float"/>
</class>]]></programlisting>
<table frame="topbot" id="schemattributes-summary" revision="2">
<title>まとめ</title>
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<colspec colwidth="2.5*"/>
<thead>
<row>
<entry>属性</entry>
<entry></entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>length</literal></entry>
<entry>数値</entry>
<entry>カラムの長さ</entry>
</row>
<row>
<entry><literal>precision</literal></entry>
<entry>数値</entry>
<entry>カラムのDECIMAL型の精度precision</entry>
</row>
<row>
<entry><literal>scale</literal></entry>
<entry>数値</entry>
<entry>カラムのDECIMAL型のスケールscale</entry>
</row>
<row>
<entry><literal>not-null</literal></entry>
<entry><literal>true|false</literal></entry>
<entry>カラムがnull値を取らないことを指定します
</entry>
</row>
<row>
<entry><literal>unique</literal></entry>
<entry><literal>true|false</literal></entry>
<entry>カラムがユニーク制約を持つことを指定します
</entry>
</row>
<row>
<entry><literal>index</literal></entry>
<entry><literal>インデックス名</literal> </entry>
<entry>(複数カラムの)インデックスの名前を指定します
</entry>
</row>
<row>
<entry><literal>unique-key</literal></entry>
<entry><literal>ユニークキー名</literal></entry>
<entry>複数カラムのユニーク制約の名前を指定します
</entry>
</row>
<row>
<entry><literal>foreign-key</literal></entry>
<entry><literal>外部キー名</literal></entry>
<entry>
&lt;one-to-one&gt;&lt;many-to-one&gt;&lt;many-to-many&gt;マッピング要素を使って、
関連に対し生成された外部キー制約の名前を指定します。
<literal>SchemaExport</literal><literal>inverse="true"</literal> 側を考慮しないことに注意してください。
</entry>
</row>
<row>
<entry><literal>sql-type</literal></entry>
<entry><literal>SQLのカラム型</literal></entry>
<entry>
デフォルトのカラム型をオーバーライドします( <literal>&lt;column&gt;</literal> 要素の属性のみ)
</entry>
</row>
<row>
<entry><literal>default</literal></entry>
<entry>SQL式</entry>
<entry>
カラムのデフォルト値を指定します
</entry>
</row>
<row>
<entry><literal>check</literal></entry>
<entry>SQL式</entry>
<entry>
カラムかテーブルにSQLのチェック制約を作成します
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<literal>&lt;comment&gt;</literal> 要素で生成するスキーマにコメントを指定することができます。
</para>
<programlisting><![CDATA[<class name="Customer" table="CurCust">
<comment>Current customers only</comment>
...
</class>]]></programlisting>
<programlisting><![CDATA[<property name="balance">
<column name="bal">
<comment>Balance in USD</comment>
</column>
</property>]]></programlisting>
<para>
これにより、生成したDDLに <literal>comment on table</literal><literal>comment on column</literal> 文が書かれます。
</para>
</sect2>
<sect2 id="toolsetguide-s1-3" revision="2">
<title>ツールの実行</title>
<para>
<literal>SchemaExport</literal> は標準出力に対してDDLスクリプトを書き出し、DDL文を実行したりもします。
</para>
<para>
<literal>java -cp </literal> <emphasis>hibernate_classpaths</emphasis>
<literal>org.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>options mapping_files</emphasis>
</para>
<table frame="topbot">
<title> <literal>SchemaExport</literal> Command Line Options
<literal>SchemaExport</literal> のコマンドラインオプション
</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>オプション</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>--quiet</literal> </entry>
<entry>スクリプトを標準出力に出力しません</entry>
</row>
<row>
<entry> <literal>--drop</literal> </entry>
<entry>テーブルの削除だけを行います</entry>
</row>
<row>
<entry> <literal>--create</literal> </entry>
<entry>テーブルの生成のみを行います。
</entry>
</row>
<row>
<entry> <literal>--text</literal> </entry>
<entry>データベースにエクスポートしません</entry>
</row>
<row>
<entry> <literal>--output=my_schema.ddl</literal> </entry>
<entry> DDLスクリプトをファイルに出力します</entry>
</row>
<row>
<entry> <literal>--naming=eg.MyNamingStrategy</literal> </entry>
<entry> <literal>NamingStrategy</literal> を選択します
</entry>
</row>
<row>
<entry><literal>--config=hibernate.cfg.xml</literal> </entry>
<entry>XMLファイルからHibernateの定義情報を読み込みます</entry>
</row>
<row>
<entry> <literal>--properties=hibernate.properties</literal> </entry>
<entry>ファイルからデータベースプロパティを読み込みます</entry>
</row>
<row>
<entry> <literal>--format</literal> </entry>
<entry>スクリプト内に生成するSQLを読みやすいようにフォーマットします</entry>
</row>
<row>
<entry> <literal>--delimiter=x</literal> </entry>
<entry>スクリプトの行区切り文字を設定します</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
アプリケーションに <literal>SchemaExport</literal> を組み込むこともできます:
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-4">
<title>プロパティ</title>
<para>
次のように、データベースのプロパティを指定することができます。
</para>
<itemizedlist spacing="compact">
<listitem>
<para><literal>-D</literal> <emphasis>&lt;property&gt;</emphasis> を使って、システムプロパティとして
</para>
</listitem>
<listitem>
<para><literal>hibernate.properties</literal> ファイル内で
</para>
</listitem>
<listitem>
<para> <literal>--properties</literal> を使って指定したプロパティファイル内で
</para>
</listitem>
</itemizedlist>
<para>
必要なプロパティは以下のものです:
</para>
<table frame="topbot">
<title>SchemaExportコネクションプロパティ</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>プロパティ名
</entry>
<entry>説明
</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>hibernate.connection.driver_class</literal> </entry>
<entry>jdbcのドライバークラス
</entry>
</row>
<row>
<entry> <literal>hibernate.connection.url</literal> </entry>
<entry>jdbcのurl
</entry>
</row>
<row>
<entry> <literal>hibernate.connection.username</literal> </entry>
<entry>データベースのユーザ
</entry>
</row>
<row>
<entry> <literal>hibernate.connection.password</literal> </entry>
<entry>ユーザパスワード
</entry>
</row>
<row>
<entry> <literal>hibernate.dialect</literal> </entry>
<entry>データベース方言
</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="toolsetguide-s1-5">
<title>Antを使用する</title>
<para>
Antのビルドスクリプトから <literal>SchemaExport</literal> を呼び出すことができます。:
</para>
<programlisting><![CDATA[<target name="schemaexport">
<taskdef name="schemaexport"
classname="org.hibernate.tool.hbm2ddl.SchemaExportTask"
classpathref="class.path"/>
<schemaexport
properties="hibernate.properties"
quiet="no"
text="no"
drop="no"
delimiter=";"
output="schema-export.sql">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaexport>
</target>]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-6" revision="2">
<title>インクリメンタルなスキーマ更新
</title>
<para>
<literal>SchemaUpdate</literal> ツールは既存のスキーマをインクリメンタルに更新します。
<literal>SchemaUpdate</literal> はJDBCのメタデータAPIに強く依存します。
そのため、すべてのJDBCドライバでうまくいくとは限らないことに注意してください。
</para>
<para>
<literal>java -cp </literal> <emphasis>hibernate_classpaths</emphasis>
<literal>org.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options mapping_files</emphasis>
</para>
<table frame="topbot">
<title> <literal>SchemaUpdate</literal> のコマンドライン・オプション</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>オプション</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>--quiet</literal> </entry>
<entry>標準出力にスクリプトを出力しません</entry>
</row>
<row>
<entry> <literal>--text</literal> </entry>
<entry>データベースにスクリプトをエクスポートしません
</entry>
</row>
<row>
<entry> <literal>--naming=eg.MyNamingStrategy</literal> </entry>
<entry><literal>NamingStrategy</literal> を選択します。
</entry>
</row>
<row>
<entry> <literal>--properties=hibernate.properties</literal> </entry>
<entry>ファイルからデータベースプロパティを読み込みます
</entry>
</row>
<row>
<entry> <literal>--config=hibernate.cfg.xml</literal> </entry>
<entry><literal>.cfg.xml</literal> ファイルを指定します
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
アプリケーションに <literal>SchemaUpdate</literal> を組み込むことができます。:
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-7">
<title>インクリメンタルなスキーマ更新に対するAntの使用</title>
<para>
Antスクリプトから <literal>SchemaUpdate</literal> を呼び出すことができます:
</para>
<programlisting><![CDATA[<target name="schemaupdate">
<taskdef name="schemaupdate"
classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask"
classpathref="class.path"/>
<schemaupdate
properties="hibernate.properties"
quiet="no">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaupdate>
</target>]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-8" revision="1">
<title>Schema validation</title>
<para>
<literal>SchemaValidator</literal> ツールは、既存のデータベーススキーマと作成したマッピングドキュメントが"一致する"ことを検証します。 <literal>SchemaValidator</literal> はJDBCのメタデータAPIに強く依存することに注意してください。そのため、すべてのJDBCドライバーで作動するものではありません。このツールはテスト時に非常に有用です。
</para>
<para>
<literal>java -cp </literal> <emphasis>hibernate_classpaths</emphasis>
<literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> <emphasis>options mapping_files</emphasis>
</para>
<table frame="topbot">
<title> <literal>SchemaValidator</literal> のコマンドライン・オプション
</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>オプション</entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry> <literal>--naming=eg.MyNamingStrategy</literal> </entry>
<entry><literal>NamingStrategy</literal> を選択します
</entry>
</row>
<row>
<entry> <literal>--properties=hibernate.properties</literal> </entry>
<entry>ファイルからデータベースのプロパティを読み込みます
</entry>
</row>
<row>
<entry> <literal>--config=hibernate.cfg.xml</literal> </entry>
<entry><literal>.cfg.xml</literal> ファイルを指定します
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
<literal>SchemaValidator</literal> をアプリケーションに組み込むことが出来ます:
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaValidator(cfg).validate();]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-9">
<title>スキーマのバリデーションにAntを使用します</title>
<para>
Antスクリプトから <literal>SchemaValidator</literal> を呼び出せます:
</para>
<programlisting><![CDATA[<target name="schemavalidate">
<taskdef name="schemavalidator"
classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask"
classpathref="class.path"/>
<schemavalidator
properties="hibernate.properties">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaupdate>
</target>]]></programlisting>
</sect2>
</sect1>
</chapter>