Mavenによるセットアップ

こちらは、DBFlute-1.1.x (Java8) のためのドキュメントになっています。

前提条件 ※Java8

前提となる環境

Java8
DBFlute は Apache Ant を利用するため、Java8 以上の実行環境が必要
Maven
コマンドラインで mvn -version が打てる必要あり
pom.xml
アプリ用の pom.xml が既に用意されている必要あり
インターネット
Maven経由でDBFluteモジュールをダウンロードするため

もし、複数DB対応をする場合、事前にポイントを抑えておきましょう。

セットアップ手順

1. DBFluteランタイムの設定 (JDBCドライバも)

まずは pom.xml の dependencies に "DBFluteランタイム" の dependency を入れます。

propertiesタグに dbflute.version プロパティを定義しておくと、dbflute-maven-plugin がダウンロードするDBFluteエンジンのバージョンが同じになります。 (もし、propertiesがない場合、プラグインはruntimeの定義に関わらず最新バージョンをダウンロードします)

e.g. DBFluteランタイム-1.1.x の dependency を定義 @pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
...
    <properties>
        ...
        <dbflute.version>1.1.0-sp8</dbflute.version>
        ...
    </properties>
    
    ...

    <dependencies>
        ...
        <dependency>
            <groupId>org.dbflute</groupId>
            <artifactId>dbflute-runtime</artifactId>
            <version>${dbflute.version}</version>
        </dependency>
        ...
    </dependencies>
...
</project>

まだ、利用する DBMS に対応する "JDBCドライバ" の dependency を設定していないのであれば、この時点で入れておきましょう。以下は MySQL の例。

e.g. MySQL のJDBCドライバのdependencyを定義 @pom.xml
    <dependencies>
        ...
        <dependency>
            (いまさっき設定したDBFluteランタイムのdependency)
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>5.1.33</version>
            <scope>runtime</scope>
        </dependency>
        ...
    </dependencies>

2. DBFlute Maven Plugin のインストール

そして、pom.xml の plugins に、"DBFlute Maven Plugin" を入れます。

clientProject
そのデータベース(スキーマ)を表現する名前 ※"スキーマ名そのまま" がオススメ
packageBase
自動生成クラスのパッケージ ※"アプリのパッケージ.dbflute" がオススメ
e.g. プラグイン情報の追加 (実行のための基本的な設定) @pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project>
...
    <build>
        <plugins>
            ...
            <plugin>
                <groupId>org.dbflute</groupId>
                <artifactId>dbflute-maven-plugin</artifactId>
                <version>1.1.0</version>
                <configuration>
                    <clientProject>xxxdb</clientProject>
                    <packageBase>com.xxx.dbflute</packageBase>
                </configuration>
            </plugin>
            ...
        </plugins>
    </build>
...
</project>

Github に pom.xml の example がありますので参考に。

3. DBFluteエンジンのダウンロード

コマンドラインで dbflute:download ゴールを叩きます。

e.g. dbflute:download ゴールを叩く! @Command
...$ mvn -e dbflute:download

すると、mydbflute配下に、DBFluteエンジンがダウンロードされます。 こちらは、この後に作成するDBFluteクライアントから参照されるだけで、基本的にさわることはありません。 (mydbflute配下を見るのは、DBFluteエンジンのバージョンを確認するときくらい)

e.g. mydbfluteにDBFluteエンジン(1.1.0)がダウンロードされる @Directory
[PROJECT_ROOT]
 |-src/main/java
 |-src/main/resources
 |-...
 |-mydbflute
    |-dbflute-1.1.0-sp8 // これをDBFluteエンジンと呼ぶ
       |-ant
       |-...
       |-templates
       |-build-torque.xml
       |-product-is-dbflute-1.1.0-sp8

4. DBFluteクライアントの作成

コマンドラインで dbflute:create-client ゴールを叩きます。

e.g. dbflute:create-client ゴールを叩く! @Command
...$ mvn -e dbflute:create-client

すると、dbflute_xxxdb というディレクトリが作成されます。これを "DBFluteクライアント" と呼び、DBFluteをアプリに合わせるための設定や、DBFlute実行するためのスクリプトがあり、何かと見たりさわったりする機会の多いところです。

e.g. DBFluteクライアントが作成される @Directory
[PROJECT_ROOT]
 |-src/main/java
 |-...
 |-dbflute_xxxdb // ここをDBFluteクライアントと呼ぶ
    |-dfprop     // DBFluteプロパティ(dfprop)がたくさん置いてあるディレクトリ
    |-...
 |-mydbflute
    |-dbflute-1.1.0-sp8 // こちらはDBFluteエンジンと呼ぶ

5. DBFluteプロパティの基本設定 (DB接続情報やDIコンテナなど)

まずは、DBFluteクライアント (dbflute_xxxdb) の dfprop 配下にある、ふたつの dfprop ファイルを修正しましょう。 (dfpropファイルの設定を "DBFluteプロパティ" と呼びます)

basicInfoMap.dfprop
databasetargetContainer をアプリに合わせる
databaseInfoMap.dfprop
driverurl などのDB接続情報をアプリに合わせる

basicInfoMap.dfprop にて、データベース(DBMS)とDIコンテナをアプリで利用するものに修正します。以下は MySQL と Spring の例。

e.g. basicInfoMap.dfprop で、MySQL と Spring を指定 @basicInfoMap.dfprop
    ...
    # /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # o database: (Required)
    #  This is the target database, only considered when generating
    #  the SQL for your DBFlute project.
    #  Your possible choices are:
    #
    #    mysql, postgresql, oracle, db2, sqlserver,
    #    h2, derby, (sqlite, firebird, msaccess)
    #
    ; database = mysql
    # - - - - - - - - - -/
    ...

    # /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # o targetContainer: (Required)
    #  The target DI container.
    #  If your target language is 'csharp', you can specify 'seasar' only.
    #  Your possible choices are:
    #
    #       spring, guice, seasar, cdi
    #
    ; targetContainer = spring
    # - - - - - - - - - -/
    ...

databaseInfoMap.dfprop は、DBFluteクライアント作成直後はデフォルト設定なので、 アプリで利用するDMBSのJDBCの設定に修正します。以下は MySQL の例。

e.g. databaseInfoMap.dfprop で、MySQLのJDBC設定 @basicInfoMap.dfprop
...
map:{
    ; driver   = com.mysql.jdbc.Driver
    ; url      = jdbc:mysql://localhost:3306/xxxdb?characterEncoding=UTF-8
    ; schema   =  
    ; user     = xxxdb
    ; password = xxxdb
    ...
}

DBMSごとのDB接続情報は、"DBMSごとの取扱い" のページを参考に。

dfpropは、テキストエディタで開くことができます。もし、Eclipse環境が整っているなら、DBFlute の Eclipse プラグインである "EMecha" で dfprop を開けば、dfpropの色付けや重複キーや閉じ括弧チェックがされて編集しやすくなります。

6. 特定環境適用プロパティ (必要であれば)

ここからは、DBFlute Maven Plugin に関係なく、どのセットアップ方法でも必要な手順です。

dfpropは、実際に使い始めてからつどつど微調整していく形でOKですが、 さすがに自動生成前にやっておいたほうがいいだろう "特定環境適用プロパティ" もあるので、そちらのページをサッと目を通して必要であれば直しておきましょう。 (ほとんどのケースで不要であると想定され、特殊な環境でなければ、もしくは、よくわからなければとりあえずスキップでもOK)

7. JDBCドライバの準備 (Oracle や DB2 などであれば)

DBFluteエンジンに同梱されていない DBMS (Oracle や DB2 など) であれば、JDBCドライバをダウンロードしてDBFluteクライアントの extlib に配置する必要があります。

H2, MySQL, PostgreSQL は同梱されているので、この手順はスキップしてOKです。

8. クラスの自動生成 (ReplaceSchema & Generate)

それでは、自動生成をしてみましょう。

DBFluteタスク実行時に、 java.lang.UnsupportedClassVersionError, Unsupported major.minor version 52.0 のエラーが発生したときは、JAVA_HOME の設定を確認してみましょう。

9. DI設定の調整

アプリケーションで利用しているDIコンテナの環境にDBFluteのクラスを認識させて下さい。

x. その後の設定

ひとまず、アプリケーション上でDBFluteのクラスを利用することができるようになりました。 しかし、ディベロッパーに横展開するまでには、まだあともうちょい頑張りが必要です。 より良い環境で実装してもらうために、現場フィットな機能を整えましょう!

UnsupportedClassVersionErrorが発生したら

ReplaceSchema や Regenerate などのDBFluteタスク実行時に、UnsupportedClassVersionError, Unsupported major.minor version 52.0 のエラーが発生した場合は、環境変数の JAVA_HOME の設定が、Java8 ではなく Java6,7 になっている可能性があります。 (もしかしたら、JAVA_HOMEが設定されていないときでも発生するかもしれません)

JAVA_HOME を JDK8 に合わせて試してみましょう。

とりあえず、そのセッションだけ JAVA_HOME を設定して動かすのであれば、その場で export JAVA_HOME を実行するだけです。

e.g. Macで一時的に JAVA_HOME を設定 @.bash_profile
...$ export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

固定的に JAVA_HOME を設定するのであれば、.bash_profileに設定するとよいでしょう。

e.g. Macで .bash_profile に JAVA_HOME を設定 @.bash_profile
#!/bin/bash

export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
...

ちょっとずつこういった問題はなくなっていくと思いますが、Java6,7,8 と環境が混じる時期では、まだ少し注意が必要です。

DBFluteの方で、JAVA_HOMEが設定されるようにしてもいいかもしれません。DBFluteクライアントの _project.sh にて、Macだったときにだけ JAVA_HOME が設定されるように。 (ただ、すべての人の環境でちゃんと動くかどうかは不明です...でも、DBFluteの幾つかのExampleでは入れてしまっています)

e.g. _project.sh Macで .bash_profile に JAVA_HOME を設定 @.bash_profile
#!/bin/bash

export ANT_OPTS=-Xmx512m

export DBFLUTE_HOME=../mydbflute/dbflute-1.x

export MY_PROPERTIES_PATH=build.properties

if [ `uname` = "Darwin" ]; then
  export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
fi