Shafu - Asakusa Gradle Plug-in Helper for Eclipse -

Shafu (車夫) は、 Asakusa Framework のバッチアプリケーション開発をサポートするEclipseプラグインです。

Shafu は バッチアプリケーション開発にGradleを利用する際に、Eclipseから透過的にビルドツール上の操作を行えます。 Shafuを使うことで、ターミナル上でのビルドツールの操作が不要となり、Eclipse上でアプリケーション開発に必要なほとんどの作業を行うことができるようになります。

Shafu は Jinrikisha でセットアップしたEclipse環境ではもちろんのこと、単体でセットアップしたEclipse上での利用も可能です。

Note

Asakusa Frameworkが提供するGradle上のビルド機能についての詳細は、Asakusa Frameworkのドキュメント Asakusa Gradle Plugin ユーザガイド を参照してください。

リリースノート

Shafu 0.9.0

アップデート内容

• Gradle Tooling APIのバージョンを 4.9 から 4.10.1にアップデート
• 実行時に使用するGradleのデフォルトバージョンを 4.3.1 から 4.7 にアップデート
• メッセージ文言の修正

特記事項

1. EclipseをJava11以降の環境で起動する場合、shafu 0.9.0 以降のバージョンを利用する必要があります。
   • Eclipse 2020-09 以降はJava11以降のバージョンが必須であるため、Shafu 0.8.0 およびこれ以前のバージョンは利用できません。
   • Eclipse 2020-06 以前のバージョンでも、Java11以降を利用する場合はShafu 0.8.0 およびこれ以前のバージョンは利用できません。
2. Java11以降のEclipse環境でshafuを利用する場合、実行時に使用するGradleのバージョンを4.7以降に指定してください。これ以前のGradleバージョンを指定した場合は正常に動作しません。
   • なおshafuは標準の設定では、実行時に使用するGradleのバージョンはプロジェクトのGradleラッパーのバージョンから取得するようになっています。この設定でAsaksua Frameworkのプロジェクトを扱う場合、Asakusa 0.10.1 以降のバージョンでGradle 4.7が利用されます。
   • Asakusa 0.10.0 およびそれ以前のバージョンのプロジェクトをshafuで扱う場合、EclipseをJava8環境で利用してください。

対応プラットフォーム

Shafu 0.9.0 は以下のプラットフォームで動作を検証しています。

プラットフォーム	ソフトウェア	バージョン	備考
IDE	Eclipse	2019-03 / 2021-09
Java	Oracle JDK	JDK8
Java	Open JDK	JDK8

Attention

Asakusa Frameworkのバッチアプリケーションのコンパイルやテストの実行にはJDKが必要です。 JREのみがインストールされている環境では利用できません。

環境変数の設定

Shafuから利用する一部の機能は、以下の環境変数が必要です。

変数名	説明
ASAKUSA_HOME	Asakusa Frameworkのインストールディレクトリ

Eclipseの設定

Asakusa Frameworkの開発環境向けにEclipseの設定を行います。

以降の設定はEclipseの設定画面から行います。 Eclipseのメニューバーから Window ‣ Preferences で設定画面を表示します。

JDKの登録

Eclipse経由で実行するJavaにJREが設定されている場合は、これをJDKに設定します。

Attention

Asakusa Frameworkのバッチアプリケーションのコンパイルやテストの実行にはJDKを使用する必要があります。 JREでは一部の機能が利用できないため、必ずこの設定を行ってください。

1. Eclipseの設定画面から Java ‣ Installed JREs を選択します。
2. Installed JREs ダイアログにJDK以外のJava定義が表示されている場合 (例えば jre8 のような項目が表示されている場合)、これら項目を削除します。 削除する項目を選択して、 Remove ボタンを押下します。
3. JDKを追加します。 Installed JREs ダイアログで Add ボタンを押下します。
4. JRE Type ダイアログで Standard VM を選択し、 Next > ボタンを押下します。
5. JRE Definition ダイアログで JRE home: の項目右の Directory... ボタンを押下し、JDKのフォルダを指定します。
6. JRE Definition ダイアログの各項目にインストールしたJDKの情報が設定されたことを確認して Finish ボタンを押下します。
7. Installed JREs ダイアログに追加したJDKの項目が表示されるので、その項目の Name 欄に表示されているチェックボックスを ON にします。JDKの項目が jdk1.8.0_XX (default) のような表示になれば設定完了です。

ネットワークプロキシの設定

オンラインとの接続にプロキシサーバを経由する必要がある場合は、Eclipseのプロキシ設定画面でプロキシの設定を行います。

1. メインメニューから Window ‣ Preferences を選択します。
2. プリファレンス画面のサイドメニューから General ‣ Network Connections を選択します。
3. プロキシ設定画面で、 Active Provider: を Manual に変更し、 Proxy entries や Proxy bypass の内容を編集して OK ボタンを押します。

Shafuのインストール

Eclipse上でShafu のアップデートサイトを利用したインストール手順例を説明します。

1. Eclipseのメニューから Help ‣ Install New Software... を選択します。
2. Install ダイアログで Work with: の項目右の Add ボタンを押下します。
3. Add Repository ダイアログに以下の値を入力します。

Name:	Jinrikisha
Location:	https://www.asakusafw.com/eclipse/jinrikisha/updates/

4. Install ダイアログに表示された [Jinrikisha (人力車)] カテゴリを展開して [Asakusa Gradle プラグインサポート] を選択し、 Next > ボタンを押下します。

5. 以降、画面の指示に従いインストールを進めます。Eclipseの再起動を促されたら Yes を選択します。
6. Eclipse再起動が完了したら、Javaパースペクティブを表示して メニューバーから Window ‣ Perspective ‣ Reset Perspective.. を選択して Java パースペクティブを初期化します。

Attention

Shafuのインストール後にJavaパースペクティブの初期化を行わないと、Shafuのメニューが表示されないことがあります。

Shafuの使い方

Shafu が提供する各機能の使い方を説明します。

Gradleプロジェクトをテンプレートから生成

オンライン上に公開されているAsakusa Frameworkのプロジェクトテンプレートや、ローカルに配置したプロジェクトテンプレートを利用して、Eclipse上に新規プロジェクトを作成することができます。

1. Javaパースペクティブ上のメインメニューなどから File ‣ New ‣ Gradleプロジェクトをテンプレートから生成 を選択します。
2. 新規プロジェクト情報ダイアログで、プロジェクト名などを入力します。
3. プロジェクトテンプレートの選択ダイアログで、オンラインまたはローカルのテンプレートファイルを指定します。URL入力ボックス右の 選択 ボタンを押すと、オンラインに公開されているプロジェクトテンプレートを一覧から選択することができます。

4. Finish ボタンを押すと選択したプロジェクトテンプレートを読み込み、Eclipseプロジェクトとして新規プロジェクトが作成されます。

Gradleプロジェクトのインポート

ローカルに配置したGradleベースのプロジェクトをEclipseワークスペース上にインポートすることができます。 単体のプロジェクトをインポートするほか、複数のプロジェクトから構成されるマルチプロジェクト構成のプロジェクトを一括してインポートすることもできます。

1. Javaパースペクティブ上のメインメニューなどから File ‣ Import を選択します。
2. インポート選択画面で Jinrikisha (人力車) ‣ Gradle プロジェクト を選択して Next > ボタンを押します。
3. プロジェクトディレクトリーの選択ダイアログで、ローカルに配置されているGradleプロジェクトのディレクトリーパスを選択して Next > ボタンを押します。
4. インポート対象のプロジェクト選択で、インポート対象のプロジェクトを選択して Finish ボタンを押します。

コンテキストメニュー

プロジェクトのデータモデルクラスの生成やAsakusa DSLのコンパイルなど、Asakusa FrameworkがGradleを利用する各ビルド機能をコンテキストメニュー実行することができます。

1. プロジェクトを選択してコンテキストメニュー(右クリックなどで表示されるメニュー)を表示します。
2. コンテキストメニューの Jinrikisha (人力車) を選択し、サブメニューとして表示される以下の各ビルド機能を選択します。

Jinrikisha (人力車) メニュー

メニュー名	説明	Gradleタスク [1]
タスク名を指定してビルド	任意のGradleタスクを入力して実行する	-
DMDLからデータモデルクラスを生成	DMDLスクリプトからデータモデルクラスを生成	compileDMDL
テストデータ・テンプレートを生成	DMDLスクリプトからTestDriverのテストデータを定義するExcelブックを生成する	generateTestbook
Asakusaバッチアプリケーションを生成	Asakusa DSLをバッチコンパイルして、バッチアプリケーションアーカイブファイルを生成する	jarBatchapp
Asakusaデプロイメントアーカイブを生成	Asakusa Frameworkの実行環境一式を含むデプロイメントアーカイブファイルを生成する	assemble
Asakusa開発環境の構成	Asakusa Frameworkの開発環境をセットアップするためのサブメニューを表示する	-
Eclipseプロジェクト情報を再構成	Eclipseのプロジェクト定義ファイルを再作成する [2]	eclipse

Asakusa開発環境の構成 サブメニュー

メニュー名	説明	Gradleタスク
Asakusa Frameworkのインストール	開発用のAsakusa Frameworkをインストールする	installAsakusafw
バッチアプリケーションの配備	プロジェクトのビルドディレクトリからバッチコンパイルの生成物をローカルの $ASAKUSA_HOME/batchapps に配置する	-

[1]	各メニューの選択時に実行されるAsakusa Gradle PluginのGradleタスクです。 詳しくはAsakusa Frameworkのドキュメント Asakusa Gradle Plugin ユーザガイド を参照してください。

[2]	Asakusa Frameworkのバージョンアップやアプリケーションライブラリの追加などで、Eclipseプロジェクトのクラスパス情報を更新する場合に使用します。

アプリケーションの開発

Shafu上で Asakusa Frameworkのバッチアプリケーションを開発する方法を見ていきます。

プロジェクトの作成

まずはEclipse上にAsakusa Frameworkアプリケーション開発用のプロジェクトを作成します。

新規プロジェクトの作成

Shafuを導入した開発環境では、オンライン上に公開されているAsakusa Frameworkのプロジェクトテンプレートを利用して、Asakusa Frameworkの開発に必要な設定が導入済みのプロジェクトを作成することができます。

標準の設定では、以下のプロジェクトテンプレートを選択することができます。

Asakusa Project Template

新規プロジェクト開発用のプロジェクトテンプレート

Asakusa Example Projects

Asakusa Frameworkの サンプルプログラム集 (GitHub) で公開されているサンプルアプリケーションプロジェクト

ここでは、サンプルアプリケーション example-basic-spark をベースにしたプロジェクトを生成します。

1. Javaパースペクティブ上のメニューバーから File ‣ New ‣ Gradleプロジェクトをテンプレートから生成 を選択します。
   • このメニューが表示されない場合は、巻末の トラブルシューティング - プロジェクト生成メニューが表示されない を確認してください。
2. 新規プロジェクト情報 ダイアログで、プロジェクト名などを入力します。
3. プロジェクトテンプレートの選択 ダイアログで URLを指定してプロジェクトテンプレートをダウンロードする が選択状態になっていることを確認して、画面右の 選択 ボタンを押下します。
4. プロジェクトテンプレート ダイアログにオンラインに公開されている、利用可能なプロジェクトテンプレートの一覧が表示されます。ここでは Asakusa Example Projects - 0.10.4 を選択します。
5. Finish ボタンを押すと選択したプロジェクトテンプレートを読み込み、Eclipseプロジェクトとして新規プロジェクトが作成されます。
6. テンプレートからプロジェクトを作成 ダイアログでテンプレートとするサンプルプロジェクト（例えば example-basic-spark ）を選択して OK ボタンを押下します。

Attention

開発環境で初めてAsakusa Frameworkのプロジェクトを作成する際にはリモートからプロジェクトに必要なライブラリをダウンロードするため、初回のプロジェクト作成には時間がかかることがあります。

開発用Asakusa Frameworkのインストール

Asakusa Frameworkのアプリケーションのテストを行うには、開発用のAsakusa Frameworkを開発環境にインストールする必要があります。

1. Javaパースペクティブ上のプロジェクトを選択してコンテキストメニュー(右クリックなどで表示されるメニュー)を表示します。
2. コンテキストメニューから Jinrikisha (人力車) ‣ Asakusa開発環境の構成 ‣ Asakusa Frameworkのインストール を選択します。
3. インストールが成功した場合、Eclipseのコンソールに以下のように表示され、環境変数 ASAKUSA_HOME で指定したフォルダ配下にAsakusa Frameworkがインストールされます。

...
:installAsakusafw
Asakusa Framework is successfully installed: C:\Users\asakusa\asakusa

BUILD SUCCESSFUL

Total time: 4.352 secs

アプリケーションの実装

データモデル定義DSL(DMDL)やAsakusa DSLなどを作成してアプリケーションを実装します。

データモデル定義DSL(DMDL)からAsakusa DSLの演算子の実装に必要なデータモデルクラスを作成する際には、コンテキストメニューから Jinrikisha (人力車) ‣ DMDLからデータモデルクラスを作成 を選択します。

See also

Asakusa Frameworkのアプリケーションの実装については、Asakusa Frameworkのドキュメントを参照してください。 Asakusa Frameworkをはじめて利用する場合、以下のドキュメントなどが参考になります。

• Asakusa Framework 入門 - 開発の流れ
• DMDLスタートガイド
• Asakusa DSLスタートガイド

アプリケーションのテスト

アプリケーションのテストは通常のJavaアプリケーションのテストと同様にJUnitを使ってテストケースを作成し、Eclipseのテスト実行メニューからテストを実行します。

例えばプロジェクトに含まれるすべてのテストケースを実行する場合は、コンテキストメニューから Run As ‣ JUnit Test を実行します。

テストが失敗する場合は、巻末の トラブルシューティング - テスト実行に失敗する を確認してください。

See also

Asakusa Frameworkのアプリケーションテストの実装については、Asakusa Frameworkのドキュメントを参照してください。 Asakusa Frameworkをはじめて利用する場合、以下のドキュメントなどが参考になります。

• アプリケーションテストスタートガイド

デプロイメントアーカイブの作成

Windows上の開発環境で作成したアプリケーションを運用環境上で実行するには、まずアプリケーションをパッケージングして「デプロイメントアーカイブ」を作成します。

デプロイメントアーカイブを生成するには、コンテキストメニューから Jinrikisha (人力車) ‣ Asakusaデプロイメントアーカイブを生成 を選択します。

デプロイメントアーカイブの生成に成功した場合、Eclipseのコンソールに以下のように表示され、プロジェクトの build フォルダ配下にデプロイメントアーカイブファイル asakusafw-{project.name}.tar.gz が生成されます。

...
:assemble

BUILD SUCCESSFUL

Total time: 4.804 secs

See also

Asakusa Frameworkのアプリケーションを運用環境にデプロイする方法については、Asakusa Frameworkのドキュメントを参照してください。 Asakusa Frameworkをはじめて利用する場合、以下のドキュメントなどが参考になります。

• Asakusa Framework デプロイメントガイド

Shafuの設定

Eclipseの設定画面からShafuの設定を変更することができます。

1. メニューバーから Window ‣ Preferences を選択します。
2. Eclipse設定画面のサイドメニューから Jinrikisha (人力車) を選択します。

Jinrikisha (人力車) プリファレンスページ

Jinrikisha (人力車) プリファレンスページでは、主にShafuが実行するGradleの設定を編集することができます。

このプリファレンスページには以下3つのタブによって各設定画面を切り替えます。

• [基本] タブ
• [プロジェクト] タブ
• [Java VM] タブ

また、Jinrikisha (人力車) のサブ階層として Asakusa Framework プリファレンスページがあります。

[基本]タブ

Gradleのログレベルやバージョン、オフラインモードの設定など、Gradleの動作に関する設定を行います。

ログレベル

Shafu経由で実行するGradleタスクのログレベルを指定します。

スタックトレース

Shafu経由で実行するGradleタスクが失敗した時のスタックトレースの表示方法を指定します。

Gradleのバージョン

Shafu経由で実行するGradleのバージョンを指定します。

後述の Gradleのバージョンをラッパーの設定情報から取得 の設定有効になっている場合、そちらの設定が優先されます。

ネットワークモード

Shafu経由で実行するGradleのオンラインモード|オフラインモードを切り替えます。

Gradle User Home ディレクトリー

Shafu経由で実行するGradleのGradle User Home ディレクトリーを指定します。

未指定の場合、Gradle標準のディレクトリーが使用されます。 詳しくは、次のGradleドキュメントを参照してください。

• Gradle User Manual - Build Environment

Gradleのバージョンをラッパーの設定情報から取得

この設定が有効になっている場合、プロジェクトに含まれるGradleラッパーの設定情報に基づいてShafu経由で実行するGradleバージョンを決定します。

Note

この設定はShafu バージョン 0.7.0から追加されました。 特別な理由がない限り、この設定を有効した状態でShafuを利用することを推奨します。

ラッパーの設定ファイルの位置

上述の Gradleのバージョンをラッパーの設定情報から取得 を有効にした場合に使用する、 Gradleラッパーの設定情報のパスをプロジェクトルートからの相対パスで指定します。 パスはカンマ区切りで複数指定することができます。

通常、この設定を変更する必要はありません。

[プロジェクト]タブ

Gradleのプロジェクトビルド時に使用するプロジェクトプロパティーの設定を行います。

プロジェクトプロパティー

Shafu経由で実行するGradleのプロジェクトプロパティーを追加|変更|削除します。

プロジェクトプロパティーについて詳しくは、次のGradleドキュメントを参照してください。

• Gradle User Manual - Build Environment

[Java VM]タブ

Gradleのビルドで使用するJava VMやJavaプロセスに対する設定を行います。

Java Home ディレクトリー

後述の デフォルトのJavaランタイムにプロジェクトのJavaランタイム環境を利用する 設定を無効にした場合に使用する、 Javaのインストールディレクトリを指定します。

デフォルトのJavaランタイムにプロジェクトのJavaランタイム環境を利用する

この設定が有効になっている場合、プロジェクトのJavaランタイム設定に基づいて、先述の JDKの登録 で登録した設定からJava実行環境を決定します。

通常、この設定を変更する必要はありません。

システムプロパティー

Shafu経由で実行するGradleのJavaプロセスに設定するシステムプロパティーを追加|変更|削除します。

Gradleに設定するシステムプロパティーについて詳しくは、次のGradleドキュメントを参照してください。

• Gradle User Manual - Build Environment

環境変数

Shafu経由で実行するGradleのJavaプロセスに設定する環境変数を追加|変更|削除します。 この設定を利用する場合、実行するGradleのバージョンが3.5以上である必要があります。

Gradleに設定する環境変数について詳しくは、次のGradleドキュメントを参照してください。

• Gradle User Manual - Build Environment

Asakusa Framework プリファレンスページ

プロジェクトテンプレートカタログURL

Gradleプロジェクトをテンプレートから生成 でプロジェクトテンプレートを選択する際に使用する、プロジェクトテンプレートの一覧を定義したテンプレートカタログファイルを指定します。 デフォルトでは Asakusa Frameworkが公開しているリリースバージョンの一覧を含むテンプレートカタログが指定されています。

Tip

Asakusa Frameworkが公開しているテスト用のバージョン (スナップショットビルドやRC版）を使用したい場合は、テンプレートカタログURLを以下のURLに変更します。

https://www.asakusafw.com/download/gradle-plugin/template-catalog-develop.txt

フレームワークのインストール先 (ASAKUSA_HOME)

現在の環境で設定されている環境変数 ASAKUSA_HOME の値を表示します。

この項目は表示のみです。このプリファレンスページから編集することはできません。

Hadoopコマンドの場所

現在の環境で使用するHadoopコマンドのパスを表示します。

この項目は表示のみです。このプリファレンスページから編集することはできません。

トラブルシューティング

Asakusa Frameworkの開発環境の作成、アプリケーション実行に関するトラブルシューティングです。

プロジェクト生成メニューが表示されない

発生する事象

新規プロジェクトの作成 の手順で、Javaパースペクティブ上のメニューバーから File ‣ New を選択してもサブメニューに Gradleプロジェクトをテンプレートから生成 が表示されない。

原因

Shafuのインストール後にJavaパースペクティブが初期化されていない可能性があります。 メニューバーから Window ‣ Perspective ‣ Reset Perspective.. を選択後、再度メニューを表示してください。

それでも表示されない場合は、以下の手順でメニューの設定を行なってください。

1. メニューバーから Window ‣ Perspective ‣ Customize Perspective.. を選択します。
2. Customize Perspectiveダイアログから Shortcuts タブを選択します。
3. 画面左上の Submenus: が New になっていることを確認後、 Shortcut Categories: のリストから Jinrikisha (人力車） を選択します。
4. OK ボタンを押下して設定を保存した後、再度メニューを表示してください。

上記の手順で Jinrikisha (人力車） が表示されない場合はShafuがインストールされていない可能性があります。 Shafuのインストール の内容を確認してください。

プロジェクトの作成に失敗する

発生する事象

新規プロジェクトの作成 の手順を実行すると、以下のエラーメッセージが表示されプロジェクトの作成に失敗する。

...
:compileJava FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':compileJava'.
> Cannot find System Java Compiler. Ensure that you have installed a JDK (not just a JRE) and configured your JAVA_HOME system variable to point to the according directory.
...

原因

Eclipseがデフォルトで利用するJavaにJDKが登録されていない可能性があります。 JDKの登録 の手順を確認し、JDKが登録されていることを確認してください。

複数のJava環境が登録されている場合、Eclipse設定画面の Installed JREs ‣ Execution-Environments の JavaSE-1.8 の項目にJDKが表示されていること、およびJDKにチェックがON(デフォルトで利用する)になっていることを確認してください。

Asakusa Frameworkのインストールに失敗する

発生する事象

開発用Asakusa Frameworkのインストール の手順を実行すると、以下のエラーメッセージが表示されインストールに失敗する。

...
:updateAsakusafw FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':updateAsakusafw'.
> ASAKUSA_HOME is not defined
...

原因

環境変数 ASAKUSA_HOME が設定されていない可能性があります。 環境変数の設定 の手順を確認し、環境変数が追加されていることを確認してください。

Eclipseを起動中に環境変数を追加した場合は、Eclipseの再起動が必要です。

テスト実行に失敗する

発生する事象

アプリケーションのテスト の手順を実行すると、以下のエラーメッセージが表示されテストが失敗する。

...
java.lang.AssertionError: 環境変数"ASAKUSA_HOME"が未設定です
  at com.asakusafw.testdriver.inprocess.InProcessJobExecutor.validateEnvironment(InProcessJobExecutor.java:108)
...

原因

環境変数 ASAKUSA_HOME が設定されていない可能性があります。 環境変数の設定 の手順を確認し、環境変数が追加されていることを確認してください。

Eclipseを起動中に環境変数を追加した場合は、Eclipseの再起動が必要です。

発生する事象

アプリケーションのテスト の手順を実行すると、以下のエラーメッセージが表示されテストが失敗する。

...
java.lang.AssertionError: この環境ではJavaコンパイラを利用できません（JDKを利用してテストを実行してください）
    at com.asakusafw.testdriver.TestDriverContext.validateCompileEnvironment(TestDriverContext.java:227)
...

原因

Eclipseがデフォルトで利用するJavaにJDKが登録されていない可能性があります。 JDKの登録 の手順を確認し、JDKが登録されていることを確認してください。

複数のJava環境が登録されている場合、Eclipse設定画面の Installed JREs ‣ Execution-Environments の JavaSE-1.8 の項目にJDKが表示されていること、およびJDKにチェックがON(デフォルトで利用する)になっていることを確認してください。

発生する事象

アプリケーションのテスト の手順を実行すると、以下のエラーメッセージが表示されテストが失敗する。

...
java.lang.IllegalStateException: java.io.IOException: Asakusa Framework is not installed: C:\Users\asakusa\asakusa
  at com.asakusafw.testdriver.JobFlowTester.runTest(JobFlowTester.java:105)
...

原因

開発環境の ASAKUSA_HOME フォルダにAsakusa Frameworkがインストールされていない可能性があります。 開発用Asakusa Frameworkのインストール が正しく行われているかを確認してください。

リソース

• ソースリポジトリ (GitHub)