ハンズオンセクション 1

概要

まずは環境構築、そして、"DBFluteのセットアップから自動生成まで" を体験してみましょう。

まず読みましょう

DBFluteのことをざっくり押さえておきましょう。

DBFluteの紹介 | DBFlute
DBFluteオフィシャルの紹介ページ
架け橋DBFlute | SpeakerDeck
講演会でのスライド資料

前提環境

JDKのインストール

(Java8以上の) JDKがインストールされていること。

※インストール先は任意ですが、特にこだわりなければ C:\java\jdk8 などに

Mavenのインストール

Maven がインストールされていること。(コマンドラインで mvn コマンドが利用できること)

※インストール先は任意ですが、特にこだわりなければ C:\java\maven などに

Eclipseの準備

Eclipse-4.4 以上が利用できること。

※幾つかの Eclipse プラグインをインストールするため、ハンズオン専用の Eclipse を用意することが推奨

環境準備

ワークスペースの作成

新規でハンズオン専用のワークスペースを任意の場所に作成してください。

e.g. DBFluteハンズオン用のワークスペース @Directory
// Windowsなら
C:\projects
    |-dbflute
       |-eclipse-dbflute
       |-workspace  // 例えばここ (場所は任意)

// MacOSXなら
~/works
    |-dbflute
       |-eclipse-dbflute
       |-workspace  // 例えばここ (場所は任意)

あらかじめディレクトリを作成し、Eclipse を起動してそのディレクトリ (workspace) を選んでください。起動直後に既に別の workspace が開いてしまう場合は、メニューの "File" - "Switch Workspace" からワークスペースを切り替えてください。 (workspaceの設定もハンズオン内で変更するので、独立した workspace が推奨されます)

この時点ではプロジェクトは一つもなく空っぽのワークスペースとなっています。

※Eclipseのworkspaceで利用するJavaは、JREではなくJDK。Preferences の Installed JREs で調整できます。

プロジェクトのclone

GITリポジトリ
https://github.com/dbflute-session/dbflute-hands-on.git
プロジェクト
dbflute-hands-on

※社内でひな形が用意されている場合は、そちらを利用してください。

(ひな形が用意されているかどうかわからない場合は、近くの人に聞いてみてください)

もし、EGit (GitクライアントのEclipseプラグイン) を使う場合は、以下のような手順になります。

  1. Preferences の Team - Git - Configuration にて autocrlf が "もし" true になら false に
  2. Gitリポジトリエクスプローラーにてリポジトリのクローン (ユーザー・パスワードなし)
  3. Working Directory を選択して右クリック Import Projects...
  4. Import as general project を選択して Next, そして次も Finish でおしまい

(dbflute-hands-on を選択して右クリック、ってのが大事...あとその後、general project ってのがポイント。一方で、もし社内のひな形で .project が含まれている場合は、general ではなく Import existing project を選択)

もし、社内でひな形が用意されてる場合は...

すでに社内でひな形が用意されてる場合は、そちらを clone してください。

チームでハンズオンを行っていく場合は、社内のGitに hands-on なるリポジトリを用意して、master ブランチにプロジェクトのひな形をコミットしておいて、各人masterをもとにそれぞれのブランチを作ってハンズオンを進めていくという形がオススメです。

したら、コミットも自由にできてバックアップになりますし、フォローワーがレビューもしやすくなります。 各人が、別のPCでハンズオンの続きをやるってこともやりやすくなります。

実際に jflute は、コミットされたハンズオンのコードをレビューして、 todo形式でレビューコメントを入れてコミットして、実装者に修正してもらってまたこっちで確認して、というような運用でハンズオンを通してプログラミングのフォローを行っています。

MySQLのセットアップ

ハンズオンでは、3306ポートのMySQLではなく、専用のMySQLインスタンスを起動して利用します。

MySQLのオフィシャルサイトからローカル環境に対応する MySQL のインストーラー無し版(ZIPアーカイブ版など)をダウンロードし、localdb/mysql に配置します。 (以下の配置であれば、MySQL本体は Git のコミット対象になりません。gitignore に登録されています。間違っても MySQL 本体を Git にコミットすることないように)

e.g. MySQLの配置場所 @Directory
PROJECT_ROOT
 |-...
 |-localdb
 |  |-mysql
 |     |-bin
 |     |-data
 |     |-docs
 |     |-...
 |-script
 |-tutorial

ちなみに Mac の人は、起動する前に MySQL を初期化してあげる必要があります。

MySQL-5.6
./script/mysql_install_db を叩く
MySQL-5.7
mysqld で初期化コマンド叩く

MySQL-5.7 での初期化コマンドは、mysqlディレクトリにて以下を叩きます。 (rootのパスワードが空っぽで作成されます)

e.g. Macのときの MySQL-5.7 での初期化コマンド @Command
./bin/mysqld --no-defaults --datadir=./data --basedir=./ --initialize-insecure

そして、localdb/boot-mysql.bat|sh を実行し、MySQL を起動してください。

さらに、login-mysql-root.bat|sh を実行し、MySQLのコマンドコンソールにて "show databases;" と打って enter して、作成されているデータベースは特にないこと(デフォルトのデータベースだけが存在)を確認してください。

今後、ハンズオンを中断する場合は、localdb/close-mysql.bat|sh を実行し、MySQLをシャットダウンし、そして、またハンズオンを再開するときは、boot-mysql.bat|sh を実行してください。 (Windowsであれば、Eclipse上からbatファイルをダブルクリックで実行できます: ctrl+shift+Rで実行でもOKです)

プラグインのセットアップ

以下のプラグインをそれぞれインストールしてください。 (既に入っているのであれば、スキップしてしまってOKです)

EMecha
DBFluteライフを支援するプラグイン
Java8 なら、DBFlute-EMecha.zip を解凍し、Eclipse の dropinsディレクトリ配下に配置: https://github.com/dbflute-emecha/dbflute-emecha-eclipse/releases
Java6,7 なら、更新サイトからインストール: http://eclipse.seasar.org/updates/3.3
Quick JUnit
JUnitを使う際のちょっとした便利プラグイン
更新サイトURL: http://quick-junit.sourceforge.jp/updates/current
Help - Install New Software から更新サイトURLを指定してインストール。

プロジェクトのセットアップ

Eclipseプロジェクトの作成

tutorial/material/eclipse/prototype-pom.xml をプロジェクト直下に pom.xml という名前でコピーしましょう。ちなみに、pom.xml やその他幾つかのリソースは gitignore 設定となっています。

script 配下の maven-eclipse.bat|sh を実行し、コンソールのログを見て正常終了が確認できたらリフレッシュ(F5)し、その後 Eclipse を再起動してしてください。ただし、M2_REPO が既に登録されている環境ではリフレッシュするだけでOKです。すると、そのプロジェクトが Maven 管理された Java プロジェクトになり、既に存在している UnitContainerTestCase がコンパイルされます。 (ただし、この時点ではコンパイルエラーになっているはずです)

(ちなみに、この時点では、maven-eclipse.bat|sh の "call dbflute_maihamadb/manage.bat refresh" において、そんなコマンドはないとエラーが発生しますが、Mavenのコマンドさえ成功していればOKです)

IntelliJの場合は、pom.xmlを配置してMavenプロジェクトとして更新してください。

workspaceの設定とプロジェクトの設定

workspace は、そのローカルPCの workspace ディレクトリのEclipse設定と考えてよいでしょう。 これらは Git 管理にはなりません(しません)ので、他の人と共有されません。 個人設定と捉えることもできますが、他の人と共有したくなるようなものもあるのがジレンマです。

一方で、プロジェクトの設定は、プロジェクト直下の.settingsディレクトリに保存されます。 Git管理にすることができるので、他の人と共有できます。つまり、最初のひとりがやっておけば、他の人はやる必要がありません。 強制力があるのはこちらです。

さて、#workspace であれば workspace の設定、#project であればプロジェクトの設定、 いずれにせよハンズオンの環境としては最初ですから、どちらも必要です。ですが、その違いを意識しながら設定していきましょう。 他の人がこのプロジェクトを参照するとき、共有されるものとされないものがあるわけです。

IntelliJの場合は、workspaceとプロジェクトの区別がないので、すべてgitignoreになります。 (厳密に見ていけば、共有していいものだめなものあるとは思いますが...)

エンコーディングの調整 #workspace #project

(Eclipseのみ)

プロジェクトのエンコーディングを UTF-8 にしてください。プロジェクトを選択して、"alt + enter" すると、プロジェクトの設定画面が開きますので、Resource の "Text file encoding" で UTF-8 を指定。また、改行コードをLFに統一したいので、"line delimiter" で Unix を指定。

また、参照ライブラリのJavaDocコメントなどが UTF-8 であることが多いため、ワークスペースのエンコーディングも UTF-8 にします。メニューの Window - Preferences の General - Workspace にて同じ要領で設定できます。(Mac なら メニューの Eclipse - 環境設定...)

Windows なら流れるように alt -> W -> P を押せば、Macなら command + , (カンマ) を押せば Preferences を開けます。(この後、何度も開きますので...)

行番号の表示、背景色の設定 #workspace

(Eclipseのみ)

メニューの Window - Preferences の General - Editors - Text Editors を選択。 ここでは、テキストエディターに関する様々な調整ができます。

行番号は必ず表示しておきましょう。スタックトレースやログなどからソースコードを追うために行番号は頻繁に利用します。"Show line numbers" にチェックを入れます。また、Background color で好きな背景色を設定するととても落ち着くでしょう。

Type Filters を設定 #workspace

メニューの Window - Preferences の Java - Appearance - Type Filters を選択。ここでは、クラス型の補完で "表示させたくない" パッケージやクラスを定義することができます。

例えば java.util.List は、毎度毎度 "java.awt.Listとどっちを選ぶ?" と聞かれてしまいます。Type Filters にて "java.awt.*" と設定すれば、そんなことはもう聞かれません。 もう、絶対に使わないのにも関わらず、わりとよく出てくる紛らわしいものを設定しておくと良いでしょう。

java.awt.*
awtパッケージを使うことは今の開発ではまずない
com.sun.*
sunパッケージのクラスを使うことはほとんどない
sun.*
sunパッケージが意外と紛らわしい!?
java.sql.Date
業務のプログラムでjava.sql.Dateを使うことはまずない

また、ハンズオンでは MySQL を利用しますが、MySQLのJDBCドライバのLogクラスが、commons-logging のLogクラス補完時に紛れるので、com.mysql.jdbc.log.* も除外しておくと良いでしょう。

com.mysql.jdbc.log.*
MySQLのJDBCドライバのLogクラスを使うことはまずない

さらにアドリブで、こちらも外しちゃってもいいかと思います。

java.lang.StringBuffer
文字列連結を同期化する必要性はほぼない、StringBuilder でOK
java.util.Calendar
少なくともハンズオンでは HandyDate を使ってください

キリがないのでこの辺にしておきますが、つどつど気付いたときに登録していくと良いでしょう。

IntelliJでやられている方でも、似たような機能があると思われるので試してみてください。

Maven の Download Artifact Sources を #workspace

(Eclipseのみ)

Maven で管理されたライブラリのソースコードは、デフォルトではダウンロードされず関連付けもない状態である可能性があります。 すると、ソースコードが見られないだけでなく、パラメーターの補完などで変数名が arg0 とかになってしまうことがあります。

もし、ctrl + shift + T (Open Type) で HandyDate クラスを開いて、ソースが表示されないか、ソースが表示されても JavaDoc が表示されていなければ、ソースコードがダウンロードされていません。

メニューの Window - Preferences の Maven にて、Download Artifact Sources のチェックが外れていたらチェックを付けます。 そして、maven-eclipse.bat(sh) をもう一度叩いて、プロジェクトをF5してみましょう。 (M2Eであれば、プロジェクトを右クリックして Maven の Download Sources となる)

Package Presentation を Hierarchical に #workspace

(Eclipseのみ)

これは好みによるので任意ですが、特にFlat形式にこだわりがなければやってみましょう。

Eclipse のデフォルトは、Package Presentation が Flat で、パッケージがたくさんあるプロジェクトだと、ずらーっと並んで見づらいと感じることがあります。 特にDBFluteで自動生成されるクラスは、パッケージをたくさん持っているので Hierarchical の方が扱いやすくなります。

Hierarchical に変更する場合は、(Java パースペクティブの)パッケージエクスプローラの右上の下矢印っぽいマークの部分 (View Menu) から、Package Presentation の Hierarchical を選択します。

この時点では、"わからない人はまだよくわからない" と思われるので、この後DBFluteのクラスを自動生成した後に試してみると良いでしょう。

エディターテンプレートを設定 #workspace

メニューの Window - Preferences の Java - Editor - Templates を選択。 ここでは、コード補完のテンプレートを独自に定義することができます。

まず、既存のテンプレートをすべて選択して、Remove してください(これをやらないと二重に登録される可能性あり)。 そして、"Import..." にて tutorial/material/eclipse/java-editor-templates.xml を取り込んでください。 あとでちょっとだけ良いことがあります。(まあ、セクション2にて)

IntelliJ用のテンプレートも用意しています。(足りない補完もありますが...)

その他いろいろとワークスペース設定 #workspace

(Eclipseのみ)

好みもありますが、その他やっておくと良いだろうという設定を記しておきます。

ドット "." 始まりのファイルが見えるように
デフォルトではドット "." で始まるファイルは見えないようになっているので、パッケージエクスプローラのフィルタの設定で一時的に見えるようにします。 (Java パースペクティブの)パッケージエクスプローラの右上の下矢印っぽいマークの部分 (View Menu) から Filters を選択すると、フィルタ対象の設定が調整できます。".* resource" のチェックを外すと "." で始まるファイルが見るようになります。
ctrl + H のカスタマイズ
File Search だけにする。ほぼ File Search しか使わないのに、Java Search がデフォルトになるため。
プロジェクトを選択して、ctrl+Hを押すと、検索ダイアログが表示されます。左下の "Customize..." で File Search だけチェック。
ctrl + F のカスタマイズ
インクリメンタルサーチを有効に。便利なので。(普段、ctrl+Jを使っている人はあまり気にしないかもですが)
何かしらテキストファイルを開いて、ctrl+Fを押すと検索ダイアログが表示されます。 そこで Incremental にチェックを付ける。(その後、キャンセルしても、記憶されます)
ツールバーの整理
ツールバーの不要な要素を除去。多いと二行になってコード領域が狭くなるため。ツールバーで右クリック "Customize Perspective..." の Tool Bar Visibility にて、Launch と Resource Synchronizer 以外はチェックを外す(but ここは好みで)。
コンソールのバッファサイズ
大きな処理だとログがあっという間に最初の方のログが切れてしまうので、Preferences の Run/Debug - Console の "Console buffer size" を 800000 (八十万) に。
ビューの配置
利用しているPCの画面の大きさに合わせて、いい感じに調整。Problems を Fast View (Minimize) にしたりなど。通常は横長で縦が短いディスプレイが多いので、コードができるだけ縦に見通せるようにするといいでしょう。
ショートカットキーの設定
EGitを使っている場合は、あらかじめ設定しとくと楽。
また、"Rerun JUnit Test" を ctrl + R (好み) とかに設定しておくと良い(Quick JUnit の F11 が別のキーに奪われている可能性があるため)。 ショートカットキーは、Preferences の Keys で設定できます。

フォーマッタのインポート #project

Eclipseには、コードをフォーマットする機能があります。

ただ、Eclipseのデフォルトのフォーマット定義は かなり 使いづらいため、プロジェクトのプロパティの "Java Code Style" の Formatter にて、"Enable project specific settings" にチェックを入れ、import にて tutorial/material/eclipse/code-formatter-profile.xml を指定して適用してください。

このフォーマット定義は、横幅を 140 に、コメント内のフォーマットを OFF にしています。

IntelliJでも、Eclipseのフォーマッター設定をインポートできるようなので、やってみてください。

フォーマッタ・インポート調整の自動化 #project

(Eclipseのみ)

フォーマッタ設定やショートカットを実践したばかりでなんですが、保管時(保存: ctrl + S)に自動でフォーマッタが動くように設定することができます。わざわざショートカットを打つ必要もありません。

プロジェクトのプロパティの "Java Editor" の "Save Actions" にて、"Enable project specific settings" にチェックを入れ、さらに "Perform the selected actions on save"、および、"Format source code" にチェックを入れましょう。

さらに "Organize imports" にもチェックを入れましょう。これは import 文を整理してくれるアクション(ctrl + shift + O)です。

DBFluteのセットアップ

DBFluteクライアントの作成 ※Java6, 7

EMechaの機能を利用して、DBFluteエンジンをダウンロード、DBFluteクライアントを作成します。 (講師によるDBFlute環境のお話あり)

プロジェクトを右クリックして、"New" - "Other" で "DBFlute Wizards" の "DBFlute New Client" を選択してウィザード画面を起動し、以下の内容を入力してください。

Client Project
maihamadb
Database
mysql
DI Container
seasar
Package Base
org.docksidestage.handson.dbflute
Driver
com.mysql.jdbc.Driver
Url
jdbc:mysql://localhost:43376/maihamadb
Schema
※空っぽ
User
maihamadb
Password
maihamadb
DBFlute Version
※"Latest Version" ボタンを押すと値が入る

そして、"Download DBFlute" ボタンを押し、最新版のDBFluteがダウンロードしてください(若干待ちます)。そして、Finish すると、プロジェクト直下に dbflute_example(DBFluteクライアント) と mydbflute(DBFluteエンジン) が配置されています。 (もし、mydbflute配下にDBFluteのzipファイルが残っていたら削除してOKです。プラグインが削除し切れてないだけです)

DBFluteクライアントの作成 ※Java8

DBFlute Maven Plugin を使って、インストールします。

pom.xml に Plugin の設定はすでにされているはずですが、もし実行してみてプラグインが存在しないというようなエラーが発生した場合は、"Mavenによるセットアップ" ドキュメントを参考にpom.xmlを修正してみてください。

まずは、コマンドラインで dbflute:download ゴールを叩きます。(プロジェクト直下にて)

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

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

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

basicInfoMap.dfprop のプロパティ値を修正します。(忘れずに)

database
mysql
targetContainer
lasta_di

databaseInfoMap.dfprop のプロパティ値を修正します。(忘れずに)

driver
com.mysql.jdbc.Driver
url
jdbc:mysql://localhost:43376/maihamadb
schema
※空っぽ
user
maihamadb
password
maihamadb

ReplaceSchemaの実行

アプリユーザとスキーマ(テーブル構造を含む)を作成するために、ReplaceSchemaを利用します。

DBユーザ自動作成のための設定

DBFluteクライアント/dfprop配下の replaceSchemaMap.dfprop (旧replaceSchemaDefinitionMap.dfprop) の additionalUserMap プロパティを以下のように設定してください(コメントアウトされた雛形があるので、そのコメントアウトを外して修正)。 これは、システムユーザによるアプリユーザ、スキーマの作成を自動化するための準備です。

e.g. additionalUserMap の設定 @replaceSchemaDefinitionMap.dfprop
    ...

    ; additionalUserMap = map:{
        ; system = map:{
            ; url = jdbc:mysql://localhost:43376
            ; user = root
            ; password = df:dfprop/system-password.txt|
        }
    }

    ...

password に "df:dfprop/system-password.txt" と "|" を加えることで、 rootのパスワードは以下のようなルールで決定されます。

パスワードファイルがあれば
パスワードファイルの中のパスワードが有効
パスワードファイルがなければ
「|」より右側の文字列がパスワード (この場合は「空パスワード」)

ダウンロードしたての MySQL は、パスワードが空であることが想定され、ここでは特にパスワードファイルを作成する必要はないはずですが、 もし違う場合は、パスワードファイルを作成してください。

DBユーザ、テーブル作成DDLの配置

tutorial/material/dbflute/playsql-createschema-ddl-1st.zip の playsql/replace-schema-00-system.sql と replace-schema-10-basic.sql、この二つのファイルをDBFluteクライアントの playsql 配下に配置してください。 (デフォルトで配置されている空っぽのreplace-schema.sqlは削除しちゃってOKです)

e.g. CreateSchema用のDDLの配置場所 @Directory
PROJECT_ROOT
 |-...
 |-dbflute_maihamadb
 |  |-dfprop
 |  |-...
 |  |-playsql
 |  |  |-replace-schema-00-system.sql
 |  |  |-replace-schema-10-basic.sql
 ...

これにて、システムユーザの権限を利用してアプリユーザと ExampleDB のテーブル作成の準備が整いました。 (後の演習のために、この時点では明らかにおかしいカラム名などERDと若干の違いがあります)

ReplaceSchemaを叩く!

DBFluteタスクである、ReplaceSchemaタスクを実行してください。

Windows であれば、リソースの検索 (ctrl + shift + R) で "manage.bat" を検索してそのまま実行、メニューが出ますので 0 番 (replace-schema) を押して Enter すればOKです。 (Macの人はターミナルから manage.sh を...)

コンソールのログを見て、正常終了していることを確認してください。 DBFluteタスクのログファイルである、DBFluteクライアント/log/dbflute.log でも確認することができます。 (ハンズオンをどこかの Git で管理する場合は、logファイルを .gitignore に登録しておきましょう)

もし、Mac OS X の Java8 環境にて UnsupportedClassVersionError が発生した場合は、JAVA_HOME を Java8 に設定してください。(これどうにかならないかなぁ...)

e.g. Macにて、JAVA_HOME を Java8 に設定 @Shell
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

再度、MySQLにログインし、maihamadb データベースが作られていることを確認してください。

JDBCタスクの実行

まず、DBFluteクライアントの schema 配下には、readme しかないことを確認してください。

DBFluteタスクである、JDBCタスク (manage.bat|sh で21番) を実行してください。実行の仕方は、ReplaceSchemaを実行したときと同じ要領で、 リソースの検索から実行すると良いでしょう。今後、DBFluteタスクの実行をする時はこの方法を使っていきましょう。

DBFluteクライアントの schema 配下に、テーブル構造の情報(スキーマのメタデータ)が XML 形式で出力されているはずです(Eclipse上でリフレッシュ必要)。

Docタスクの実行

まず、DBFluteクライアントの output/doc 配下には、readme しかないことを確認してください。

Docタスク (manage.bat|sh で22番) を実行してください。DBFluteクライアントの output/doc 配下に、テーブル構造の情報(スキーマのメタデータ)が HTML 形式で出力されているはずです(Eclipse上でリフレッシュ必要)。

Generateタスクの実行

まず、src/main/java 配下には、何もクラスがないことを確認してください。

そして、Generateタスク (manage.bat|sh で23番) を実行してください。src/main/java 配下にテーブル対応のクラスが自動生成されているはずです。 Eclipse の EmSynchronizer が有効であれば自動でリフレッシュされます。コンパイルが正常に通っていることを確認してください。

(...コンパイル確認中)

自動生成されたクラスがコンパイルエラーになったでしょうか?

もし、コンパイルエラーであれば、DBFluteエンジンとDBFluteランタイムのバージョンを確認してみてください。 自動生成されたクラスとDBFluteランタイムのjarファイルのバージョンは一致していなければなりません。 食い違っていれば、DBFluteランタイムのバージョンを修正して合わせましょう。

これで本当にコンパイルエラーなくなれば、セクション1はおしまいです!

そういえば、Package Presentation がよくわからなかった人は、ここで Hierarchical に変更してみましょう。 src/main/java配下の表現の仕方がガラリと変わるはずです。

ディベロッパーのためのチュートリアル

さあ、ディベロッパーのためのチュートリアルをブックマークしましょう!

今後、何かとこのページを見ることになるかと思います。 DBFluteのさまざまなページを辿ることができるエントリページになっています。 まずは一度さらっと読んでみて、"ここにこういうことが書いてあるんだ" となんとなく理解してみて、そして、このあと困ったことがあったら、このページを開いて情報を探していくとよいでしょう。

ちなみに、Java8のページ (DBFlute on Java8) もこちらから辿れるようになっています。

次のセクション

さて、次のセクションへ