ハンズオンセクション 1

• 概要
• まず読みましょう
  • DBFluteのこと
  • jfluteによるレビューのこと
• 前提環境
  • JDKのインストール (もし、なければ)
  • Mavenのインストール (もし、なければ)
  • IDE, Eclipse/IntelliJの用意
• 環境準備
  • workspaceの作成
  • プロジェクトのcloneとimport
  • MySQLのセットアップ
  • Eclipseプラグインのセットアップ (if Eclipse)
• プロジェクトのセットアップ
  • pom.xmlの作成
  • プロジェクトの作成
  • ワークスペース設定とプロジェクト設定 (if Eclipse)
  • ハンズオンのワークスペース設定 (if Eclipse)
  • ハンズオンのプロジェクト設定 (if Eclipse)
  • IntelliJでも補完テンプレート (if IntelliJ)
  • .ideaディレクトリでの設定共有は？ (if IntelliJ)
• DBFluteのセットアップ
  • DBFluteクライアントの作成 ※Java6, 7
  • DBFluteクライアントの作成 ※Java8
  • DBFluteプロパティ(dfprop)の調整
  • ReplaceSchemaの実行
  • JDBCタスクの実行
  • Docタスクの実行
  • Generateタスクの実行
• ディベロッパーのためのチュートリアル
• jfluteのレビューポイント
• 次のセクション

概要

まずは 環境構築、そして、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

EMechaプラグイン

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の補完テンプレートが用意されています。これを設定しておいてください。

設定エクササイズ

IntelliJ - DBFlute な Live Template

.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配下の表現の仕方がガラリと変わるはずです。

次のセクション

さて、次のセクションへ

SiteMap Author's BlogBTS