ハンズオンセクション 1
概要
まずは 環境構築、そして、DBFluteのセットアップから自動生成まで を体験してみましょう。
※環境構築やセットアップも、ハンズオンの一部です。くれぐれも油断なきよう...
まず読みましょう
DBFluteのこと
DBFluteのことをざっくり押さえておきましょう。
- DBFluteの紹介 | DBFlute
- DBFluteオフィシャルの紹介ページ
- 架け橋DBFlute | SpeakerDeck
- 講演会でのスライド資料
jfluteによるレビューのこと
jfluteにレビューしてもらう方は、こちらを必ず読んでおいてください。
前提環境
JDKのインストール (もし、なければ)
Java8以上の JDK をインストールしてください。 Javaの開発をするには、JRE (実行環境) ではなく JDK (開発環境) が必要です。
Mavenのインストール (もし、なければ)
Maven をインストールしてください。コマンドラインで mvn が利用できる状態にしましょう。
DBFluteハンズオンでは、Eclipseを使う場合に maven-eclipse-plugin を使って連携することを想定してます。 勉強のためにあえてシンプルなやり方を採用しています。IntelliJなら...不要かもしれません。
IDE, Eclipse/IntelliJの用意
Eclipseの場合、エディションは Eclipse IDE for Java Developers がオススメです。
IntelliJの場合、特にオススメのエディションはありません。
環境準備
workspaceの作成
新規でworkspaceディレクトリを任意の場所に作成してください。 (後にgit cloneする場所です)
場所は任意ではありますが、「どこにcloneしたか忘れてしまった」にならないようにしましょう。
e.g. DBFluteハンズオン用のworkspaceディレクトリ @Directory
~/works
|-dbflute
|-eclipse-dbflute
|-workspace // 例えばここ
(Eclipseの方は) Eclipseを起動するときにそのworkspaceディレクトリを選んでください。 起動直後に別のワークスペースが開いてしまう場合は、メニューの "File" - "Switch Workspace" からワークスペースを切り替えてください。
プロジェクトのcloneとimport
workspace に git clone
先ほど作った workspaceディレクトリ配下に git clone しましょう。
- GITリポジトリ
- https://github.com/dbflute-session/dbflute-hands-on.git
- プロジェクト
- dbflute-hands-on
【注意】もし社内でDBFluteハンズオン用の "gitリポジトリ" が用意されている場合は、そちらを利用してください。 (用意されているかどうかわからない場合は、近くの人に聞いてみてください)
もしGit操作がよくわからない方で、Eclipseを使っている方は、参考になるドキュメントがあります。
IDE にて import
そして、EclipseやIntelliJなどで、プロジェクトとしてimport (open) しましょう。
(Eclipseの方は) メニューの File - Import... から Existing Projects into Workspace で clone したディレクトリを指定すればOKです。 (.projectがすでにgitにコミットされている状態なので)
(IntelliJの方は) ImportよりもOpenの方が良いかと思います。IntelliJのバージョンにも寄るかもですが、Importだとハンズオンで用意している.ideaディレクトリが上書きされてしまうかもしれません。 (でも、Importでやってしまった場合は、.ideaディレクトリの上書きされたファイルをgitから復元すれば大丈夫です)
MySQLのセットアップ
ハンズオンでは、3306ポートのMySQLではなく、専用のMySQLインスタンスを起動して利用します。 なので、すでに (3306ポートの) MySQL をインストールされている方も、セットアップが必要です。
ダウンロードと配置
MySQLのオフィシャルサイトからローカル環境に対応する MySQL のインストーラー無し版(ZIPアーカイブ版など)をダウンロードし、localdb/mysql に配置します。 (以下の配置であれば、MySQL本体は Git のコミット対象になりません。gitignore に登録されています。間違っても MySQL 本体を Git にコミットしないように)
※注意: MySQL-8.2 ではなく MySQL-8.0 でお願いします。ハンズオンのMySQLの設定ファイルが 8.2 だと動かないと報告がありました。
e.g. MySQLの配置場所 @Directory
PROJECT_ROOT
|-...
|-localdb
| |-mysql
| |-bin
| |-data
| |-docs
| |-...
|-script
|-tutorial
Mac でも Windows でも、初期化の手続きを
起動する前に MySQL を初期化してあげる必要があります。
- MySQL-8.0
- mysqld で初期化コマンド叩く ※Mac/Windows両方で必要
MySQL-8.0 での初期化コマンドは、mysqlディレクトリにて以下を叩きます。 (dataディレクトリが作成され、rootのパスワードが空っぽになります)
Macのときの MySQL-8.0 での初期化コマンド @Command
./bin/mysqld --defaults-file=../my.cnf --datadir=./data --basedir=./ --initialize-insecure
もし、Macにて “mysqld”は、開発元を検証できないため開けません。 というようなエラーダイアログが出た場合は、いったんダイアログをキャンセルしてから、mysqlディレクトリにて xattr -rc * と実行してから、もう一度 mysqld を再実行してみてください。(MacOSに問題ない開発元であることを教えてあげるということです)
MySQLを起動してみましょう
そして、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です)
Eclipseプラグインのセットアップ (if Eclipse)
(Eclipseの方は) 以下のEclipseプラグインをそれぞれインストールしてください。
- EMecha
- DBFluteライフを支援するプラグイン
- 以下から DBFlute-EMecha.zip を解凍し、Eclipse の dropinsディレクトリ配下に配置します。 https://github.com/dbflute-emecha/dbflute-emecha-eclipse/releases
- Quick JUnit
- JUnitを使う際のちょっとした便利プラグイン
- Help - Eclipse Marketplace...から Quick JUnit を検索してインストールします。
プロジェクトのセットアップ
pom.xmlの作成
Maven の設定ファイルである pom.xml を作成します。
さすがに0から作るのは大変なので、ハンズオンでひな形を用意しています。 tutorial/material/eclipse/prototype-pom.xml をコピーして、dbflute-hands-onプロジェクト直下に pom.xml という名前で配置しましょう。
pom.xmlを中身を軽く覗いてみましょう。ハンズオンに限らず自分が開発するプロジェクトにどのような依存ライブラリがあるのか把握しておくのは大切です。
プロジェクトの作成
Eclipse なら
(Eclipseの方は) scriptディレクトリ配下の maven-eclipse.bat|sh を実行し、コンソールのログを見て正常終了が確認できたらEclipse上でプロジェクトをリフレッシュ(F5)してください。
※ちなみに、この時点では maven-eclipse.bat|sh の "call dbflute_maihamadb/manage.bat refresh" において、そんなコマンドはないとエラーが発生しますが、Mavenのコマンドさえ成功していればOKです。
すると、MavenとEclipseを連携させるためのファイル(.project, .classpath)が自動生成され、Eclipseがコンパイルし始めます。 そのプロジェクトが Maven 管理された Java プロジェクトになり、既に存在している UnitContainerTestCase がコンパイルエラーになるはずです。(コンパイルエラーで正常です)
IntelliJ なら
(IntelliJの方は) pom.xmlを指定してMavenプロジェクトとしてimportしてください。
ワークスペース設定とプロジェクト設定 (if Eclipse)
(Eclipseの方は) ワークスペース設定とプロジェクト設定の違いを理解しておいてください。
- 読み物エクササイズ
- Eclipseのワークスペースとプロジェクト
DBFluteハンズオンでは、IDE設定もエクササイズのひとつです。自分で別の環境を作るときには必要ですから、内容を把握しながら設定していきましょう。
ハンズオンのワークスペース設定 (if Eclipse)
(Eclipseの方は) 以下のページのおすすめワークスペース設定を反映していってください。
- 設定エクササイズ
- Eclipseのおすすめワークスペース設定
少々手間がありますが、Eclipseの環境構築の勉強と思いながら設定してましょう。 特にDBFluteの補完テンプレートとパッケージの見た目表現は、DBFluteを使うときの重要な設定となります。
これを設定することで、DBFluteの補完テンプレートが入ります。後の実装で使っていきましょう。
ハンズオンのプロジェクト設定 (if Eclipse)
(Eclipseの方は) 以下のページのおすすめプロジェクト設定を反映していってください。
- 設定エクササイズ
- Eclipseのおすすめプロジェクト設定
DBFluteハンズオンをgitにコミットして共有される方は、レビューワーの環境でも同じ挙動になるようにするために、.settingsディレクトリも忘れずにコミットしましょう
IntelliJでも補完テンプレート (if IntelliJ)
IntelliJでもDBFluteの補完テンプレートが用意されています。これを設定しておいてください。
.ideaディレクトリでの設定共有は？ (if IntelliJ)
(IntelliJの方は) DBFluteハンズオンで用意されている .ideaディレクトリを把握しておいてください。
- 読み物エクササイズ
- Friends - IntelliJ
.idea ディレクトリの中にワークスペースの設定とプロジェクトの設定が混在しています。 ハンズオンでは、DBFluteを使う際に設定されておいたほうが良い IntelliJ のオプションがすでにコミットされていて有効になっています。 (なので読むだけですが、知っておくことは大事です)
DBFluteのセットアップ
DBFluteクライアントの作成 ※Java6, 7
Java6,7の方は、別ページにて
DBFluteクライアントの作成 ※Java8
DBFlute Maven Plugin (ハンズオンの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
DBFluteプロパティ(dfprop)の調整
basicInfoMap.dfprop のプロパティ値を修正します。(忘れずに)
- database
- mysql
- targetContainer
- lasta_di
databaseInfoMap.dfprop のプロパティ値を修正します。(忘れずに)
- driver
- com.mysql.jdbc.driver
- url
- jdbc:mysql://localhost:43376/maihamadb?allowPublicKeyRetrieval=true&sslMode=DISABLED
- schema
- ※空っぽ
- user
- maihamadb
- password
- maihamadb
urlプロパティが長いですが、"jdbc:" から "sslMode=DISABLED" まで、改行空白の無いひとつの値です。 ここでは、localhostの43376ポートのmaihamadbデータベース(スキーマ)にSSL接続OFFで接続しようとしています。
MySQL-8.0.17以降の予約語対応
MySQL-8.0.17より MEMBER が予約語となりましたので、(該当バージョンであれば)その対応を入れます。 littleAdjustmentMap.dfprop のプロパティ値を修正します。(忘れずに)
e.g. quoteTableNameList の設定 @littleAdjustmentMap.dfprop
...
# /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# o quoteTableNameList: (NotRequired - Default list:{})
# The list of table DB names that need to be quoted. Specified tables is quoted on auto-generated SQL.
#
; quoteTableNameList = list:{ MEMBER }
# - - - - - - - - - -/
...
これにより、DBFluteが管理しているSQLにて、MEMBERがエスケープされるようになります。
ReplaceSchemaの実行
アプリユーザとスキーマ(テーブル構造を含む)を作成するために、ReplaceSchemaを利用します。
DBユーザ自動作成のための設定
[DBFluteクライアント]/dfprop配下の replaceSchemaMap.dfprop の additionalUserMap プロパティを以下のように設定してください。コメントアウトされた雛形があるので、そのコメントアウトを外して修正しましょう。 これは、システムユーザによるアプリユーザ、スキーマの作成を自動化するための準備です。
e.g. additionalUserMap の設定 @replaceSchemaMap.dfprop
...
# /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# o additionalUserMap: (NotRequired - Default map:{})
# You can set additional users.
# Elements of this map are as below:
# o key of map: User Definition Name (userDefName)
# o url: (NotRequired - Default same as one of main schema)
# o schema: (NotRequired - Default treated as no schema setting)
# o user: (Required)
# o password: password plainly or path to password file (with default password)
# e.g. foo or df:dfprop/system-password.txt|foo
# (NotRequired - Default '')
# o isSkipIfNotFoundPasswordFileAndDefault: Does it skip the user SQL statement
# when using password file but not found it and also default password?
# (NotRequired - Default false)
#
; additionalUserMap = map:{
; system = map:{
; url = jdbc:mysql://localhost:43376?allowPublicKeyRetrieval=true&sslMode=DISABLED
; user = root
; password = df:dfprop/system-password.txt|
}
}
# - - - - - - - - - -/
...
password に "df:dfprop/system-password.txt" と "|" を加えることで、 rootのパスワードは以下のようなルールで決定されます。
- パスワードファイルがあれば
- パスワードファイルの中のパスワードが有効
- パスワードファイルがなければ
- 「|」より右側の文字列がパスワード (この場合は「空パスワード」)
ハンズオンの MySQL は、rootのパスワードが "空" であることを想定しているので、特にパスワードファイルを作成する必要はありません。 もし違う場合は、パスワードファイルを作成してください。(パスワードファイルは必ずgitignoreにしましょう)
DBユーザ、テーブル作成DDLの配置
tutorial/material/dbflute/playsql-createschema-ddl-1st.zip を解凍して、replace-schema-00-system.sql と replace-schema-10-basic.sql を、以下のようにDBFluteクライアントの playsql 配下に配置してください。 デフォルトで配置されている空っぽのreplace-schema.sqlは削除してください。
e.g. CreateSchema用のDDLの配置場所 @Directory
PROJECT_ROOT
|-...
|-dbflute_maihamadb
| |-dfprop
| |-...
| |-playsql
| | |-replace-schema-00-system.sql
| | |-replace-schema-10-basic.sql
...
これにて、システムユーザの権限を利用してアプリユーザと Example の DB (MaihamaDBと呼ばれる) のテーブル作成の準備が整いました。 (後の演習のために、この時点では明らかにおかしいカラム名などERDと若干の違いがあります)
ReplaceSchemaを叩く！
DBFluteタスクである、ReplaceSchemaタスクを実行してください。
Windows の Eclipse であれば、"リソースの検索" (ctrl + shift + R) で "manage.bat" を検索してそのまま実行、メニューが出ますので 0 番 (replace-schema) を押して Enter すればOKです。 (Macの人はターミナルから manage.sh を...)
コンソールのログを見て、正常終了していることを確認してください。 DBFluteタスクのログファイルである、DBFluteクライアント/log/dbflute.log でも確認することができます。
ハンズオンをどこかの Git で管理する場合は、logファイルを .gitignore に登録しておきましょう。 (logディレクトリに.gitignoreファイルを作成し、*.logと指定しておくでOKです)
再度、MySQLにログインし、maihamadb データベースが作られていることを確認してください。
JDBCタスクの実行
まず、DBFluteクライアントの schema 配下には、readme しかないことを確認してください。
DBFluteタスクである、JDBCタスク (manage.bat|sh で21番) を実行してください。実行の仕方は、ReplaceSchemaを実行したときと同じで、 manage.bat|sh はいつでも気軽に叩けるようにしておきましょう。
DBFluteクライアントの schema 配下に、テーブル構造の情報(スキーマのメタデータ)が XML 形式で出力されているはずです(Eclipse上で確認するなら、プロジェクトのリフレッシュが必要)。
Docタスクの実行
まず、DBFluteクライアントの output/doc 配下には、readme しかないことを確認してください。
Docタスク (manage.bat|sh で22番) を実行してください。DBFluteクライアントの output/doc 配下に、テーブル構造の情報(スキーマのメタデータ)が HTML 形式で出力されているはずです。
Generateタスクの実行
まず、src/main/java 配下には、何もクラスがないことを確認してください。
そして、Generateタスク (manage.bat|sh で23番) を実行してください。DBFluteタスクが正常終了していれば、src/main/java 配下にテーブル対応のクラスが自動生成されるはずです。 コンパイルが正常に通っていることを確認してください。
(...コンパイル確認中)
もし、コンパイルエラーであれば、DBFluteエンジンとDBFluteランタイムのバージョンを確認してみてください。 自動生成されたクラスとDBFluteランタイムのjarファイルのバージョンは一致していなければなりません。 食い違っていれば、DBFluteランタイムのバージョンを修正して合わせましょう。
これで本当にコンパイルエラーなくなれば、セクション１はおしまいです！
そういえば、先ほど Package Presentation (if Eclipse) がよくわからなかった人は、ここで Hierarchical に変更してみましょう。 src/main/java配下の表現の仕方がガラリと変わるはずです。
ディベロッパーのためのチュートリアル
さあ、ディベロッパーのためのチュートリアルをブックマークしましょう！
今後、何かとこのページを見ることになるかと思います。 DBFluteのさまざまなページを辿ることができるエントリページになっています。 まずは一度さらっと読んでみて、"ここにこういうことが書いてあるんだ" となんとなく理解してみて、そして、このあと困ったことがあったら、このページを開いて情報を探していくとよいでしょう。
jfluteのレビューポイント
以下、改めてチェックしてみてください。
- Encodingや改行コードの設定、プロジェクトの設定に入ってますか？ (if Eclipse)
- フォーマッターや自動化の設定、プロジェクトの入ってますか？ (if Eclipse)
- DBFluteクライアントのlogの ".log" ファイルたちは gitignore になってますか？
- そもそもコンパイルは通ってますか？ (エラーになってないですか？)
環境構築のような作業を抜けなくできる というのも、重宝されるスキルです。
次のセクション
さて、次のセクションへ
