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は以下のプラットフォームで動作を検証しています。

プラットフォーム ソフトウェア バージョン 備考
IDE Eclipse 4.7.1a  
Java Oracle JDK JDK7 / JDK8 推奨環境
Java Open JDK JDK7 / JDK8 基本的な動作確認のみ
OS Ubuntu Desktop 16.04.3 推奨環境
OS CentOS 7.2  
OS MacOSX 10.13  
OS Windows 10 (1709)  

Attention

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

環境変数の設定

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

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

Eclipseの設定

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

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

JDKの登録

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

  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) のような表示になれば設定完了です。
_images/installed-jre-jdk8.png

Attention

Asakusa Frameworkのバッチアプリケーションのコンパイルやテストの実行にはJDKを使用する必要があります。 JREを使用することはできないため、ここで示す手順以外でJDKの設定を行う場合、誤ってJREが使用されるような設定にならないよう注意してください。

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

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

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

Shafuのインストール

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

  1. Eclipseのメニューから Help ‣ Install New Software... を選択します。
  2. Install ダイアログで Work with: の項目右の Add ボタンを押下します。
  3. Add Repository ダイアログに以下の値を入力します。
Name: Jinrikisha
Location: http://www.asakusafw.com/eclipse/jinrikisha/updates/
  1. Install ダイアログに表示された [Jinrikisha (人力車)] カテゴリを展開して [Asakusa Gradle プラグインサポート] を選択し、 Next > ボタンを押下します。
_images/install-shafu.png
  1. 以降、画面の指示に従いインストールを進めます。Eclipseの再起動を促されたら Yes を選択します。
  2. 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入力ボックス右の 選択 ボタンを押すと、オンラインに公開されているプロジェクトテンプレートを一覧から選択することができます。
_images/create-project-select-template.png
  1. 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プロジェクトのクラスパス情報を更新する場合に使用します。
_images/shafu-build-project.png

アプリケーションの開発

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.0 を選択します。
  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
_images/shafu-install-asakusafw.png

アプリケーションの実装

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

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

_images/shafu-build-project.png

See also

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

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

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

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

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

_images/eclipse-junit.png

See also

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

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

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

デプロイメントアーカイブを生成するには、コンテキストメニューから 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をはじめて利用する場合、以下のドキュメントなどが参考になります。

Shafuの設定

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

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

Jinrikisha (人力車) ページ

基本
Gradleのログレベルやバージョン、オフラインモードの設定など、Gradleの動作に関する設定を行います。
プロジェクト
Gradleのプロジェクトビルド時に使用するプロジェクトプロパティーを設定することができます。
Java VM
Gradleのビルドで使用するJava VMやJavaプロセスに対するシステムプロパティーを指定します。

Asakusa Framework ページ

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

Tip

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

http://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-EnvironmentsJavaSE-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-EnvironmentsJavaSE-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のインストール が正しく行われているかを確認してください。