The Seasar Project

概要

データベースのメタデータを読み取りエンティティクラスのコードを生成します。エンティティクラスとは、データベースのテーブルに対応するクラスです。

例えば、次のようなコードを生成できます。

/**
 * Departmentエンティティクラスです。
 * 
 * @author S2JDBC-Gen
 */
@Entity
public class Department {

    /** departmentIdプロパティ */
    @Id
    @Column(nullable = false, unique = true)
    public Integer departmentId;

    /** departmentNameプロパティ */
    @Column(length = 20, nullable = true, unique = false)
    public String departmentName;

    /** employees関連プロパティ */
    @OneToMany(mappedBy = "department")
    public List<Employee> employeeList;
}

これは、次のDDLで表されるDEPARATMENTテーブルに対応します。

create table DEPARTMENT (
    DEPARTMENT_ID integer not null primary key, 
    DEPARTMENT_NAME varchar(20)
);

エンティティクラスは、自由に修正して利用できます。

メタデータの利用

Gen-Entiyタスクは、データベースのメタデータを参照し、次の情報からコードを生成します。

• テーブル
  • カタログ名
  • スキーマ名
  • テーブル名
  • コメント
• カラム
  • カラム名
  • データ型
  • NOT NULL制約
  • コメント
• 外部キー（主キーを参照するもののみ）
• 一意キー

コメントの情報は、データベースによっては提供されない場合があります。 また、Javaコードに反映するにはapplyDbCommentToJava属性に"true"を指定する必要があります。

Oracle Databaseでは、日本語を含むテーブル名については、一意キー制約の情報をデータベースのメタデータから取得できません。 そのため、3つの点でコードが正しく生成されないという制限があります。コード生成後、手動で修正してください。

1. 該当のテーブルに単一の一意キー制約が存在しても、@Columnのunique要素がtrueになりません。
2. 該当のテーブルに複合一意キー制約が存在しても、@TableのuniqueConstraints要素にキーとなるカラム名が指定されません。
3. 該当のテーブルの外部キーのカラムに一意キー制約が存在しても、@OneToOneが指定されません。代わりに@ManyToOneが指定されます。

データベースのデータ型とJavaの型の対応表

生成されるエンティティのプロパティの型は、対応するカラムのデータ型により決まります。

以下の表では、代表的なデータベースについて、データベースのデータ型がJavaのどの型に対応するかを示しています。 例えば、SQL Server 2005のbigint型はJavaのLong型に対応します。 ハイフン（-）は対応するデータ型がないことを示します。

トップレベルのパラメータ

ネストした要素として指定されるパラメータ

jvmArg

このタスクの大部分の処理は別VMで行われます。VMに引数を渡す場合は<jvmarg>要素を使用します。 これはAntのJavaタスクで使用できる<jvmarg>と同じです。 使用可能な属性やネストした要素についてはAntのドキュメントを参照してください。

エンティティクラスに共通のスーパークラスを指定する

entitySuperclassName属性に、エンティティクラスに共通のスーパークラスの名前を指定できます。 たとえば、エンティティに対応するすべてのテーブルにCREATE_TIMESTAMPとUPDATE_TIMESTAMPというカラムが定義されている場合、 次のようなクラスを作成し、すべてのエンティティのスーパークラスに指定できます。

@MappedSuperclass
public abstract class AbstractEntity {
    @Temporal(TemporalType.TIMESTAMP)
    public Date createTimestamp;
    @Temporal(TemporalType.TIMESTAMP)
    public Date updateTimestamp;
}

スーパークラス名をGen-EntityタスクのentitySuperclassName属性に指定します。

<gen-entity
    rootPackageName="examples"
    entitySuperclassName="examples.AbstractEntity"
    classpathRef="classpath"
/>

タスクを実行するとexamples.AbstractEntityを継承した次のようなクラスが生成されます。

@Entity
public class Employee extends AbstractEntity {
    @Id
    public Integer id;
    public String name;
}

@Entity
public class Department extends AbstractEntity {
    @Id
    public Integer id;
    public String name;
}

一対多の関連プロパティ名を英単語の複数形にする

一対多の関連プロパティ名は、デフォルトでは、関連先のエンティティ名を小文字にした文字列とListというサフィックスの結合文字列として表されます。

@Entity
public class Department {
    @Id
    public Identity id;
    @OneToManay(mappedBy = "department")
    public List<Employee> employeeList;
}

辞書ファイルを用意することで、英単語の複数形変換のルールに則ることができます。 たとえば、ごく基本的な変換ルールを記述した辞書ファイルは次のようになります。

(.*)(f|fe)$=$1ves
(.*[^aiueo])y$=$1ies
(.*(s|x|sh|ch|o))$=$1es
(.*)$=$1s

辞書ファイルはプロパティファイルの形式で記述します。 行の先頭が「#」や「!」で始まる場合は、コメント行とみなされます。 「=」の左側には関連先エンティティ名の先頭を小文字にした文字列にマッチさせる正規表現を記述します。 「=」の右側には、マッチした場合の置換文字列を記述します。置換文字列には\1や\2などのようにグループの参照を含められます。 辞書ファイルを使った評価は正規表現にマッチするまで上から1行ずつ順に行われます。 どの行にもマッチしない場合、関連プロパティ名は、デフォルトと同様、関連先のエンティティ名を小文字にした文字列とListというサフィックスの結合文字列になります。

辞書ファイルはpluralFormFile属性に指定できます。（ここでは辞書ファイルの名前をplural.propertiesとします。）

<gen-entity
    rootPackageName="examples"
    pluralFormFile="plural.properties"
    classpathRef="classpath"
/>

上記の置換ルールを持つ辞書ファイルを利用した場合、一対多の関連プロパティ名はemployeeListではなくemployeesになります。

@Entity
public class Department {
    @Id
    public Identity id;
    @OneToManay(mappedBy = "department")
    public List<Employee> employees;
}

識別子の生成方法を指定する

識別子の生成方法を指定するには、idGeneration属性に値を指定します。 idGeneration属性に"sequence"や"table"を指定してシーケンスやテーブルでの生成を選択する場合や、 "auto"を指定してシーケンスやテーブルでの生成が自動で選択される場合は、 initialValueやallocationSizeの指定も可能です。 使用するRDBMSがサポートしていない場合、"identity"や"sequence"を指定するとエラーが発生します。

たとえば、テーブルを利用した生成を行う場合、次のように指定できます。

<gen-entity
    rootPackageName="examples"
    idGeneration="table"
    initialValue="1000"
    allocationSize="10"
    classpathRef="classpath"
/>

生成されるクラスは次のようになります。

@Entity
public class Department {
    @Id
    @GeneratedValue(strategy = GenerationType.TABLE, generator = "generator")
    @TableGenerator(name = "generator", initialValue = 1000, allocationSize = 10)
    public Identity id;
    public String name;
}

独自のテンプレートファイルを使用する

任意のディレクトリに独自のテンプレートファイルを置き、templateFilePrimaryDir属性にそのディレクトリを指定することで、 独自のテンプレートファイルを使用できます。

S2JDBC-Genのテンプレートは、配布ファイルのresources/tempaltesディレクトリ以下にあります。 エンティティクラスのテンプレートはjava/entity.ftlになります。 これをコピーして、修正を加えるのが良いでしょう。 テンプレートの記述方法についてはFreeMarker のドキュメントを参照してください。

テンプレートファイルを格納するディレクトリをmytempletesとする場合、 修正した独自テンプレートを使用するにはテンプレートをmytempletes/java/entity.ftlと配置し、templateFilePrimaryDir属性にmytempletesを指定します。

<gen-entity
    rootPackageName="examples"
    templateFilePrimaryDir="mytempletes"
    classpathRef="classpath"
/>

mytempletes/my-entity.ftlのように、テンプレートファイルを任意の名前で配置したい場合は、 templateFilePrimaryDir属性に加え、entityTemplateFileName属性も指定します。

<gen-entity
    rootPackageName="examples"
    templateFilePrimaryDir="mytempletes"
    entityTemplateFileName="my-entity.ftl"
    classpathRef="classpath"
/>

生成するJavaファイルに共通のヘッダーとしてコピーライトを含める

lib.ftlというファイルを作成し、これをtemplateFilePrimaryDir属性に指定するディレクトリに配置します。 lib.ftlには次のようにcopyrightの定義をします。

<#assign copyright>
/*
 * Copyright 2008-2009 ...
 * All rights reserved.
 */
</#assign>

<gen-entity
    rootPackageName="examples"
    templateFilePrimaryDir="mytempletes"
    classpathRef="classpath"
/>

copyright.ftlにコピーライトを記述することもできます（過去バージョンとの互換機能として残されています）。 copyright.ftlを使う場合は、#assignタグを使わずコピーライトのみを指定してください。 lib.ftlと同様、copyright.ftlはtemplateFilePrimaryDir属性に指定するディレクトリに配置する必要があります。

生成するJavaファイルにauthorを指定する

lib.ftlというファイルを作成し、これをtemplateFilePrimaryDir属性に指定するディレクトリに配置します。 lib.ftlには次のようにauthorの定義をします。

<#assign author="Nakamura">

<gen-entity
    rootPackageName="examples"
    templateFilePrimaryDir="mytempletes"
    classpathRef="classpath"
/>

データベース上のテーブルやカラムへのコメントをエンティティのJavaDocコメントに反映させる

テーブルやカラムへのコメントをエンティティのJavaDocコメントに反映させるには、applyDbCommentToJava属性に"true"を指定します。

<gen-entity
    rootPackageName="examples"
    applyDbCommentToJava="true"
    classpathRef="classpath"
/>

テーブルやカラムへのコメントをサポートしていないRDBMSの場合、JavaDocコメントへの反映は行われません。 また、MySQLでは、テーブルに対するコメントはJavaDocコメントへ反映されません。