Asakusa Gradle Plugin ユーザーガイド¶
この文書では、GradleにAsakusa Framework を使ったアプリケーションの開発やデプロイを行うための機能を追加するAsakusa Gradle Pluginについて説明します。
概要¶
Asakusa Gradle Pluginは、Asakusa Framework用のGradle拡張プラグイン群です。 このプラグインを利用することで、Gradleを利用してAsakusa Framework を使ったアプリケーションの開発やデプロイを行うことができます。
利用環境¶
Asakusa Gradle Pluginを利用するにはJava(JDK)がインストールされている必要があります。 これらの導入方法については、 Asakusa Framework スタートガイド - 開発環境の準備 などを参考にしてください。
なお、Gradleのインストールについては、本書では Gradleラッパー と呼ばれるGradleを利用するためのコマンドを使う方法を推奨しています。 この方法に沿ってGradleを利用する場合は前もってGradleをインストールする必要はありません。 詳しくは後述の Asakusa Gradle Pluginの導入 を参考にしてください。
Gradleについて¶
Gradle はオープンソースプロジェクトとして開発されている様々なプラットフォームに対応したビルドシステムです。 シンプルかつ拡張性の高いビルド定義を行うためのDSLやプラグイン機構を持ち、他のビルドシステムとの連携を含む様々な方式に対応した依存性管理のメカニズムを有しているなど多くの特徴を持っています。
Gradleに関する詳しい情報は、以下のドキュメントなどを参考にしてください。
- Gradle Documentation (Gradleの公式ドキュメントサイト)
- Gradle 日本語ドキュメント (公式ドキュメントの翻訳サイト)
関連プロダクト¶
Shafu¶
Shafu (車夫) は、 Asakusa Framework のバッチアプリケーション開発をサポートするEclipseプラグインです。
Shafuはバッチアプリケーション開発に Asakusa Gradle Plugin を利用する際に、Eclipseから透過的にビルドツール上の操作を行えます。 Shafuを使うことで、コマンドライン上でのビルドツールの操作が不要となり、Eclipse上でアプリケーション開発に必要なほとんどの作業を行うことができるようになります。
本書ではGradleを使った操作はコマンドライン上での利用手順として説明していますが、Eclipseを使った開発を行う場合は Shafu を利用してEclipse上からGradleの操作を行うことも可能です。
Asakusa Gradle Pluginの導入¶
Asakusa Gradle Plugin を利用する方法として、以下のいずれかの方法があります。
- Asakusa Gradle Plugin 用プロジェクトテンプレートを使用する
- ビルドスクリプトに個別にプラグイン利用に必要な設定を定義する
1)は、Asakusa Gradle Pluginの利用設定が行われたビルドスクリプト、及び標準的なプロジェクトレイアウトを含むプロジェクトテンプレートを利用する方法です。 Asakusa Gradle Pluginを使った標準的なアプリケーション開発環境を導入するにはこのテンプレートを使うと便利です。
このプロジェクトテンプレートには Gradleラッパー と呼ばれるGradleを利用するコマンドが含まれます。 このコマンドを利用することで、Gradle自体の導入設定は不要となり、すぐにこのプロジェクト上で開発を始めることができます。
現在のところ、プロジェクトテンプレートは利用するプラットフォームに応じた初期設定が導入された複数種類のテンプレートを公開しています。
2)は、テンプレートを使用せずフルスクラッチでビルドスクリプトの定義やプロジェクトレイアウトを作成する方法です。 この方法はGradleやAsakusa Gradle Pluginの利用に精通している必要がありますが、既存プロジェクトのマイグレーションなどで個別に設定を行う必要がある場合などでは、こちらの方法を検討してください。
以下では、1)のAsakusa Gradle Plugin 用プロジェクトテンプレートを利用した導入方法を解説します。 2)については、 Asakusa Gradle Plugin リファレンス を参照してください。
プロジェクトテンプレートのダウンロード¶
プロジェクトテンプレートは、以下リンクからダウンロードします。
| プロジェクトテンプレート | 説明 |
|---|---|
| asakusa-spark-template-0.10.2.tar.gz | Asakusa on Spark を利用するプロジェクトテンプレート |
| asakusa-m3bp-template-0.10.2.tar.gz | Asakusa on M3BP を利用するプロジェクトテンプレート |
| asakusa-mapreduce-template-0.10.2.tar.gz | Asakusa on MapReduce を利用するプロジェクトテンプレート |
また、Asakusa Frameworkの サンプルプログラム集 (GitHub) では、サンプルアプリケーションのソースコード一式を含むサンプルアプリケーションプロジェクトを公開しています。
プロジェクトの配置¶
ダウンロードしたプロジェクトテンプレートのアーカイブを展開すると、プロジェクトテンプレート名をディレクトリ名に持つプロジェクトファイル一式が作成されます。 このディレクトリを開発するアプリケーションを示すプロジェクト名に変更して、作業用ディレクトリに配置してください。 サンプルアプリケーションを利用する場合も同様です。
以降本書では、ビルドの流れを解説するために サンプルプログラム集 (GitHub) に公開されているサンプルアプリケーションプロジェクト example-basic-spark を使って説明します。
このサンプルアプリケーションは、Asakusa on Sparkのプロジェクトテンプレートをベースにして作成されています。
ここでは、ダウンロードしたサンプルアプリケーションプロジェクト example-basic-spark を $HOME/workspace に配置したものとします。
cd ~/Downloads
curl -OL https://github.com/asakusafw/asakusafw-examples/archive/0.10.2.tar.gz
tar xf 0.10.2.tar.gz
cp -a asakusafw-examples-0.10.2/example-basic-spark ~/workspace
プロジェクトレイアウト¶
プロジェクトテンプレートを使ったアプリケーションプロジェクトのディレクトリ構成とテンプレートに含まれるファイルについて説明します。
Tip
以降に示すプロジェクトレイアウトのディレクトリパスやファイル名は、Gradleの各プラグインやAsakusa Gradle Pluginの設定により変更可能です。詳しくはGradleのドキュメントや Asakusa Gradle Plugin リファレンス を参照してください。
プロジェクトルートディレクトリ¶
プロジェクトテンプレートから作成したプロジェクトディレクトリの直下には、以下のディレクトリ/ファイルが含まれます。
| ファイル/ディレクトリ | 説明 |
|---|---|
build.gradle |
Gradleビルドスクリプト |
src |
プロジェクトのソースディレクトリ |
build |
プロジェクトのビルドディレクトリ（ビルド時に生成） |
gradlew |
Gradleラッパーコマンド (Unix) |
gradlew.bat |
Gradleラッパーコマンド (Windows) |
.buildtools |
Gradleラッパーライブラリ (Gradle Version: 4.7) |
アプリケーション開発者は src ディレクトリ配下を編集することでアプリケーションを開発します。
build ディレクトリは src ディレクトリ配下のファイルをビルドすることで生成される成果物が配置されます。
build ディレクトリ配下のファイルはビルドの度に初期化、再作成されるため build ディレクトリ配下のファイルは直接編集しないようにしてください。
GradleラッパーはGradleを使ったビルドを実行するために使用します。 Gradleラッパーに関するディレクトリ及びファイルは、Gradleラッパー自体のマイグレーションを行う場合を除き編集しないようにしてください。
Attention
Gradleラッパーを使用せず、開発環境に対して個別にインストールしたGradleを使用することも出来ますが、この場合Asakusa Frameworkで未検証のバージョンのGradleを使用した場合に問題が発生する可能性があることに注意してください。 本書ではGradleラッパーを使ってGradleに関する操作を説明しています。
ビルドスクリプト¶
ビルドスクリプト( build.gradle )はプロジェクトのビルド設定を記述したGradle用のビルドスクリプトで、プロジェクトテンプレートに含まれるビルドスクリプトにはAsakusa Gradle Pluginを利用するための設定が記述されています。
group 'com.example'
buildscript {
repositories {
maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
}
dependencies {
classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.10.2'
}
}
apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'eclipse'
プロジェクトテンプレートに含まれるビルドスクリプトには、以下の機能を利用するための設定があらかじめ定義されています。
ソースディレクトリ¶
プロジェクトのソースディレクトリは大きくアプリケーション本体のコードを配置する src/main ディレクトリと、アプリケーションのテスト用のコードを配置する src/test ディレクトリに分かれます。
それぞれのディレクトリ/ファイルの構成を以下に示します。
| ファイル/ディレクトリ | 説明 |
|---|---|
src/main/java |
Asakusa DSLのソースディレクトリ [1] |
src/main/resources |
プロジェクトのリソースディレクトリ |
src/main/dmdl |
DMDLスクリプトディレクトリ |
src/main/libs |
プロジェクトの依存ライブラリディレクトリ [2] |
| [1] | ソースディレクトリ配下に配置するAsakusa DSLの推奨パッケージ名について、 Asakusa DSLスタートガイド に記載されています。 |
| [2] | このディレクトリ内に直接配置したライブラリファイル(.jar)のみ、バッチアプリケーション内で利用可能です。
サブディレクトリに配置したライブラリファイルは無視されます。
詳しくは、後述の ユーザー演算子で使用するライブラリの追加 を参照してください。 |
| ファイル/ディレクトリ | 説明 |
|---|---|
src/test/java |
Asakusa DSLのテスト用ソースディレクトリ |
src/test/resources |
プロジェクトのテスト用リソースディレクトリ |
src/test/resources/logback-test.xml |
ビルド/テスト実行時に使用されるログ定義ファイル |
ビルドディレクトリ¶
プロジェクトのビルドディレクトリはGradleの各プラグインが提供するタスクの実行に対応したビルド成果物が作成されます。
デフォルト設定のビルドディレクトリは build です。
ビルドディレクトリの主なディレクトリ/ファイルの構成を以下に示します [3] 。
| ファイル/ディレクトリ | 生成タスクの例 | 説明 |
|---|---|---|
generated-sources/modelgen |
compileDMDL | DMDLコンパイラによって生成されるデータモデルクラス用ソースディレクトリ |
generated-sources/annotations |
classes | Operator DSLコンパイラによって生成される演算子実装クラス/演算子ファクトリクラス用ソースディレクトリ |
excel |
generateTestbook | テストデータ定義シートを生成するディレクトリ |
reports/tests |
check | テストレポートファイルを生成するディレクトリ |
spark-batchapps |
compileBatchapp | Sparkコンパイラによるバッチアプリケーション生成ディレクトリ |
*-batchapp-*.jar |
jarBatchapp | バッチアプリケーションアーカイブファイル |
asakusafw-*.tar.gz |
assemble | デプロイメントアーカイブファイル |
| [3] | 各タスクが処理過程で生成するワークディレクトリについては割愛しています。 また、ここで示すディレクトリ以外にも、実行するGradleのタスクによって様々なディレクトリが生成されます。 |
基本的なプラグインの使用方法¶
ここでは、Asakusa Frameworkの開発の流れに沿ってAsakusa Gradle Plugin の基本的な使い方を紹介します。
以降の説明では、コマンドライン上のカレントディレクトリがサンプルアプリケーションを配置したディレクトリに設定されていることを前提とします。
cd ~/workspace/example-basic-spark
開発用のAsakusa Frameworkインストール¶
Asakusa Frameworkを開発環境にインストールします。
Asakusa Frameworkを開発環境にインストールするには、インストールディレクトリパスを環境変数 ASAKUSA_HOME に定義した上で installAsakusafw タスクを実行します。
プロジェクト上でタスクを実行するには、以下のように gradlew コマンドにタスク名を指定して実行します。
./gradlew installAsakusafw
このタスクは ASAKUSA_HOME のパス上に開発環境用の構成を持つAsakusa Frameworkをインストールします。
Attention
開発環境では、Asakusa DSLを使ってアプリケーションを記述するだけであればAsakusa Frameworkのインストールは不要ですが、テストドライバーを使ってFlow DSL、Batch DSLのテストを行う場合や、YAESSを使ってローカル環境でバッチアプリケーションを実行する場合など、Hadoopを実際に動作させる機能については、Asakusa Frameworkをインストールする必要があります。
データモデルクラスの生成¶
DMDLスクリプトから演算子の実装で使用するデータモデルクラスを生成します。 DMDLスクリプトの記述や配置方法については アプリケーションの実装 - Asakusa Data Model を参照してください。
データモデルクラスを生成するには、 compileDMDL タスクを実行します。
./gradlew compileDMDL
このタスクはDMDLコンパイラを実行し、DMDLスクリプトディレクトリ( src/main/dmdl )配下のDMDLスクリプトからデータモデルクラスをデータモデルクラス用ソースディレクトリ( build/generated-sources/modelgen )配下に生成します。
データモデルクラスに使われるJavaパッケージ名は、ビルドスクリプト( build.gradle ) の group で指定している値に .modelgen を加えた文字列になります。
プロジェクトテンプレートに含まれるビルドスクリプトの初期値は com.example となっているため、アプリケーションが使用する適切なパッケージ名に変更してください。
Attention
DMDLスクリプトでモデル名を変更した後に compileDMDL タスクを実行した場合、モデル名を変更する前のデータモデルクラスが出力ディレクトリに残ります。 データモデルクラス用のソースディレクトリを初期化する場合、cleanCompileDMDL タスクを合わせて実行します。
See also
group と データモデルクラスのパッケージの文字列を個別に設定することも可能です。
詳しくは後述の ビルド設定のカスタマイズ で説明します。
バッチアプリケーションのコンパイル¶
Batch DSLコンパイラを使ってバッチアプリケーションのコンパイルを行い、実行可能モジュールを生成します。 Asakusa DSLの記述や配置方法については アプリケーションの実装 - Asakusa DSL を参照してください。
バッチアプリケーションのコンパイルを行うには、 compileBatchapp タスクを実行します。
./gradlew compileBatchapp
このタスクは、ビルドスクリプトに適用されているプラグイン構成に従って、利用するBatch DSLコンパイラを実行します。 例えばAsakusa on Sparkのプロジェクトテンプレートに含まれるビルドスクリプトの構成ではSpark向けのDSLコンパイラが実行されます。
その他、バッチアプリケーションのコンパイルでは以下のようなタスクが利用できます。
| タスク | 説明 |
|---|---|
| compileBatchapp | プロジェクトのプラグイン構成に従って、それぞれのBatch DSLコンパイラを実行する [4] 。 |
| mapreduceCompileBatchapps | MapReduce向けのDSLコンパイラを実行し、 build/batchc 配下にコンパイル済みのバッチアプリケーションを配置する。
このタスクを実行するにはプロジェクトのプラグイン構成に Asakusa on MapReduce を含める必要がある。 |
| sparkCompileBatchapps | Spark向けのDSLコンパイラを実行し、 build/spark-batchapps 配下にコンパイル済みのバッチアプリケーションを配置する。
このタスクを実行するにはプロジェクトのプラグイン構成に Asakusa on Spark を含める必要がある。 |
| m3bpCompileBatchapps | M3 for Batch Processing 向けのDSLコンパイラを実行し、 build/m3bp-batchapps 配下にコンパイル済みのバッチアプリケーションを配置する。
このタスクを実行するにはプロジェクトのプラグイン構成に Asakusa on M3BP を含める必要がある。 |
| jarBatchapp | compileBatchapp タスクで生成したバッチアプリケーションを含むjarファイルを生成し build/${project}-batchapps.jar に配置します。 |
| [4] | 例えばAsakusa on Sparkのプロジェクトテンプレートの初期構成では compileBatchapp は sparkCompileBatchapps を実行します。 |
デプロイメントアーカイブの構成¶
Asakusa Frameworkのバッチアプリケーションをアプリケーション運用環境（Hadoopクラスターなど）で実行するには、DSLコンパイルによって作成したバッチアプリケーションとAsakusa Framework本体の実行モジュールをあわせて運用環境にデプロイします。
Asakusa Gradle Pluginでは運用環境にデプロイする必要がある実行モジュールを全て含めた「デプロイメントアーカイブ」と呼ばれるパッケージファイルを生成することができます。
デプロイメントアーカイブの作成には、assemble タスクを実行します。
./gradlew assemble
assemble タスクを実行すると、 build ディレクトリ配下に asakusafw-${project.name}.tar.gz というファイル名でデプロイメントアーカイブファイルが生成されます。
デプロイメントアーカイブファイルは運用環境上の $ASAKUSA_HOME 配下に展開してデプロイします。
運用環境へのデプロイメントや assemble タスクの具体的な使用例については、 Asakusa Framework デプロイメントガイド を参照してください。
See also
デプロイメントアーカイブファイル名やファイルに含まれる内容を個別に設定することも可能です。 詳しくは後述の ビルド設定のカスタマイズ で説明します。
アプリケーションのテスト¶
Asakusa DSLとして記述したバッチアプリケーションに対して、テストロジックを実行してテストを行います。 Asakusa DSLのテスト手法については、 アプリケーションのテスト - TestDriver などを参照してください。
Asakusa DSLのテストを実行するには、 check タスクを実行します。
./gradlew check
check タスクを実行すると、Asakusa DSLのテスト用ソースディレクトリ( src/test/java )に含まれるテストクラスを自動的に検出し、これを実行します。
テストの実行結果は build/reports/tests 配下にHTML形式のテストレポートが生成されます。
また、 build/test-results にはXML形式のテスト結果ファイルが生成されます。
このXMLファイルはCIサーバーなどのツールと連携して使用することができます。
テストドライバーの Excelによるテストデータ定義 を使用したテストを記述する場合、 generateTestbook タスクを実行することでテストデータ定義シート（テストデータテンプレート）を生成することができます。
./gradlew generateTestbook
generateTestbook タスクを実行すると、 build/excel 配下にDMDLで記述したデータモデルに対応するテストデータ定義シートが作成されます。
フルビルド¶
build タスクはプロジェクトのフルビルドを実行します。 実際には上記 assemble と check タスクを実行します。 CIサーバーなどでリリースビルドを行うような場合に、このタスクを利用するとよいでしょう。
./gradlew clean build
Hint
clean タスクはプロジェクトのビルドディレクトリ ( build )を初期化します。
リリースビルドを行うような場合は合わせて実行するとよいでしょう。
Eclipse定義ファイルの作成¶
アプリケーション開発用の統合開発環境(IDE)にEclipseを使用する場合、開発環境にEclipseをインストールした上で、プロジェクトに対してEclipseプロジェクト用の定義ファイルを追加します。
Eclipseプロジェクト用の定義ファイルを作成するには、 eclipse タスクを実行します。
./gradlew eclipse
このコマンドを実行することによって、プロジェクトディレクトリに対してEclipseプロジェクト用の定義ファイルやEclipse上のクラスパスに対応したソースディレクトリなどが追加されます。 これにより、Eclipseからプロジェクトをインポートすることが可能になります。
Tip
Eclipseからプロジェクトをインポートするには、Eclipseのメニューから を選択し、プロジェクトディレクトリを指定します。
ビルド設定のカスタマイズ¶
ビルドに関する設定をカスタマイズするには、基本的にはGradleのビルドスクリプトである build.gradle を編集します。
以下は、いくつかの基本的なカスタマイズをおこなったビルドスクリプトの例です。
group 'com.example'
version '1.0.0'
description 'Example application'
buildscript {
repositories {
maven { url 'http://asakusafw.s3.amazonaws.com/maven/releases' }
}
dependencies {
classpath group: 'com.asakusafw.gradle', name: 'asakusa-distribution', version: '0.10.2'
}
}
apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'eclipse'
asakusafw {
basePackage 'foo.bar'
spark {
option 'spark.input.direct', 'false'
}
}
asakusafwOrganizer {
windgate.retryableEnabled true
profiles.prod {
assembly.into('.') {
put 'src/dist/prod'
}
}
}
dependencies {
compile group: 'com.asakusafw.sandbox', name: 'asakusa-directio-dmdl-ext', version: asakusafw.core.version
}
標準プロジェクトプロパティ¶
標準的なプロジェクト情報は、以下のようにビルドスクリプトのトップレベルの階層に定義します。
group 'com.example'
version '1.0.0'
description 'Example application'
group プロパティはプラグインの各タスクでJavaソースコードの生成時に指定する基底Javaパッケージとして使用されます。
version プロパティはアーカイブファイル名に付加されたり、バッチアプリケーションのコンパイル時のビルド情報ファイルに含まれます。
指定可能なプロパティ一覧についてはGradleのドキュメントを参照してください。
プラグイン規約プロパティ¶
Asakusa Gradle Pluginが提供する各タスクの動作に関する設定は、プラグイン規約プロパティに設定します。
Asakusa Gradle Pluginのプラグイン規約プロパティは、以下に説明するビルドスクリプトの各ブロックに設定します。
asakusafw ブロックの設定¶
asakusafw ブロックにはプロジェクト内で開発、管理するバッチアプリケーションに関する設定情報を指定します。
asakusafw ブロックは設定のカテゴリ別にさらに階層化されています。
以下の例では、プロジェクトで使用するコード自動生成用の規定パッケージ名 を basePackage で指定し、続いてSpark向けのDSLコンパイルの設定に関する spark ブロックが指定されています。
ブロック内には複数のプロパティを指定することができます。
asakusafw {
basePackage 'foo.bar'
spark {
option 'spark.input.direct', 'false'
}
}
See also
asakusafw ブロックの設定に関する機能は、Asakusa Gradle Pluginに含まれる Batch Application Plugin が提供します。
Batch Application Pluginに関する説明や、 asakusafw ブロックで設定可能なプロパティについては Asakusa Gradle Plugin リファレンス - Batch Application Plugin を参照してください。
asakusafwOrganizer ブロックの設定¶
asakusafwOrganizer ブロックには開発環境や運用環境の構成に関する設定情報を指定します。
asakusafwOrganizer ブロックは設定のカテゴリ別にさらに階層化されています。
以下の例では、WindGateに対してリトライ処理を有効にする拡張コンポーネントを追加しています。
profiles から始まるブロックは、デプロイメントアーカイブの構成情報を管理するプロファイルに関する設定です。
プロファイルについては後述の プロファイルの管理 で詳しく説明します。
asakusafwOrganizer {
windgate.retryableEnabled true
profiles.prod {
assembly.into('.') {
put 'src/dist/prod'
}
}
}
See also
asakusafwOrganizer ブロックの設定に関する機能は、Asakusa Gradle Pluginに含まれる Framework Organizer Plugin が提供します。
Framework Organizer Pluginに関する説明や、 asakusafwOrganizer ブロックで設定可能なプロパティについては Asakusa Gradle Plugin リファレンス - Framework Organizer Plugin を参照してください。
依存ライブラリの管理¶
ここではアプリケーションプロジェクトが利用する拡張機能や追加ライブラリなどの依存ライブラリを管理する方法を説明します。
アプリケーションSDKライブラリ¶
Asakusa Frameworkではアプリケーションの開発で使用するAsakusa Frameworkのライブラリをグループ化した「アプリケーションSDKライブラリ」を提供しています。
Asakusa Gradle Pluginを適用したアプリケーションプロジェクトでは、標準的なアプリケーションSDKライブラリがプロジェクトの依存ライブラリに自動的に追加されます。
標準の設定では無効化されている試験的機能を有効にしたり、利用しないSDKライブラリを無効化するなどの場合には、アプリケーションSDKライブラリの設定を変更します。
アプリケーションSDKライブラリは、 ビルドスクリプトの asakusafw ブロック配下の sdk で指定します。
以下の例では、プロジェクトテンプレートに含まれるビルドスクリプトに対して Direct I/O Hive を利用するためのアプリケーションSDKライブラリを追加しています。
asakusafw {
sdk.hive true
}
See also
sdk に対して設定可能な全てのプロパティについては Asakusa Gradle Plugin リファレンス - Batch Application Plugin を参照してください。
ユーザー演算子で使用するライブラリの追加¶
バッチアプリケーションのユーザー演算子から任意のJavaライブラリを利用する場合は、以下に示すいずれかの方法でアプリケーション用依存ライブラリを追加します。
プロジェクトの依存ライブラリディレクトリへjarファイルを配置¶
プロジェクトディレクトリの「依存ライブラリディレクトリ」( src/main/libs ) 配下にjarファイルを配置すると、Javaソースファイルのコンパイル時にこのライブラリが依存関係に追加され、さらにDSLコンパイルの結果バッチアプリケーションの実行ファイルに自動的に含まれるようになります。
通常はこの方法でライブラリを追加することを推奨します。
Attention
src/main/libs ディレクトリの直下に配置したjarファイルのみ有効です。
サブディレクトリを作成してその中にjarファイルを配置してもそのファイルは無視されます。
Asakusaの拡張ライブラリディレクトリへjarファイルを配置¶
バッチアプリケーションの実行時に依存ライブラリを利用するもう一つの方法は、Asakusa Framework全体の「拡張ライブラリディレクトリ」( $ASAKUSA_HOME/ext/lib )に対象のjarファイルを直接配置します。
拡張ライブラリディレクトリに追加したjarファイルは、実行時に全てのバッチアプリケーションから参照できます。
この場合、Javaソースのコンパイル時にはこのライブラリは参照されないため、ビルドスクリプトの dependencies ブロックにも依存関係の追加を行う必要があることに注意してください。
Eclipse設定の更新¶
Eclipseを使用している場合は、上記の方法で依存ライブラリを追加した後に、Eclipseプロジェクト上のクラスパス設定を更新する必要があります。
以下は更新の実行例です。
./gradlew cleanEclipse eclipse
プロファイルの管理¶
Asakusa Gradle Pluginでは、特定の環境向けに個別にデプロイメントアーカイブの構成を設定するために「プロファイル」を定義することができます。
プロファイルの指定は、 asakusafwOrganizer ブロック内の参照名 profiles で定義します [5] 。プロファイルは複数設定することが可能です。
プロファイルを定義することで、 assemble タスクの実行時（後述の dev プロファイルを除く）にプロファイルごとの各設定に従ったデプロイメントアーカイブを生成します。
標準では、以下のプロファイルが設定されています。
| プロファイル名 | 説明 |
|---|---|
dev |
開発環境向けのデプロイ構成を定義するプロファイル |
prod |
運用環境向けのデプロイ構成を定義するプロファイル |
dev プロファイルは開発環境向けに用意された特殊なプロファイルです。テストドライバー用の構成が有効になるなど、開発環境向けの既定値が設定されています。他のプロファイルとは異なり、 installAsakusafw タスクの実行時に本プロファイルの設定が使用されます。
標準で設定されているプロファイルに加えて、 asakusafwOrganizer ブロック配下に profiles.<profile-name> という形式で任意のプロファイルを追加することができます。
以下は、ステージング環境用のデプロイ構成を持つプロファイル stage を定義する例です。
asakusafwOrganizer {
hive.enabled true
windgate.retryableEnabled true
profiles.prod {
assembly.into('.') {
put 'src/dist/prod'
}
}
profiles.stage {
archiveName 'asakusa-dist-stage.tar.gz'
assembly.into('.') {
put 'src/dist/stage'
}
}
}
デプロイメントアーカイブの生成を行うと、 build ディレクトリ配下に asakusafw-${project.name}-<profile-name>.tar.gz というファイル名 [6] で プロファイルに対応したデプロイメントアーカイブが生成されます。
プロファイル内では上記で説明したコンポーネントごとの規約プロパティや assembly プロパティを使ったデプロイメントアーカイブの編集機能を使うことができます。
asakusafwOrganizer 直下に設定されている設定は、すべてのプロファイルに反映されます。
同じプロパティが asakusafwOrganizer 直下とプロファイルの両方に指定されていた場合は、プロファイル側の設定が利用されます。
例えば上の例では、 asakusafwOrganizer 直下の hive.enabled true の設定はプロファイル prod と stage 、及び標準のプロフィルである dev に反映されます。
| [5] | これらの機能は com.asakusafw.gradle.plugins.AsakusafwOrganizerProfile が提供します。 |
| [6] | 標準の設定では、プロファイル prod のデプロイメントアーカイブは asakusafw-${project.name}.tar.gz というファイル名(プロファイル名が接尾辞につかない)で生成されます。
上記の stage プロファイルの例のように、プロパティ archiveName を設定することで任意のファイル名を指定することもできます。 |
Attention
dev というプロファイル名は開発環境向けのプロファイルとして予約されているため、運用環境向けのプロファイルとしては利用できないことに注意してください。
See also
asakusafwOrganizer ブロック や profiles ブロック内で利用可能な設定項目については Asakusa Gradle Plugin リファレンス - Framework Organizer Plugin を参照してください。
See also
プロファイルの設定例や、デプロイメントアーカイブを使った運用環境へのデプロイについては、Asakusa Framework デプロイメントガイド も参照してください。
その他のプラグイン機能¶
ここでは、Asakusa Gradle Pluginの利用方法をいくつか紹介します。 より詳しい情報は、Asakusa Gradle Plugin リファレンス や各タスクのGroovyDocを参照してください。
プラグイン構成の追加¶
プロジェクトテンプレートの初期構成に対して、プラグイン構成を後から追加、削除することができます。
プラグイン構成を追加するには、ビルドスクリプト上に apply plugin: <プラグインID> のように利用するプラグイン構成を追加します。
以下の設定例では、Asakusa on Spark向けのプロジェクトテンプレートに対して、 Asakusa on M3BP 用のプラグイン asakusafw-m3bp を追加しています。
apply plugin: 'asakusafw-sdk'
apply plugin: 'asakusafw-organizer'
apply plugin: 'asakusafw-spark'
apply plugin: 'asakusafw-m3bp'
apply plugin: 'eclipse'
See also
Asakusa Gradle Pluginが提供するプラグインの一覧は Asakusa Gradle Plugin リファレンス を参照してください。
デプロイメント構成に対するDSLコンパイラの無効化¶
ビルドスクリプトの構成で有効となっているDSLコンパイラに対して、 デプロイメント構成ごとにDSLコンパイラの生成物を含めないよう設定することができます。
以下の設定例では、すべてのデプロイメント構成に対して Asakusa on M3BP コンパイラを無効にしています。 この設定により、 assemble タスクの実行時に Asakusa on M3BP コンパイラのコンパイル処理がスキップされます。
asakusafwOrganizer {
spark.enabled true
m3bp.enabled false
}
これらの記述を省略した場合、各DSLコンパイラの利用は有効 ( true ) になります。
これらの設定はプロファイル単位でも設定することができます。
バッチコンパイル対象のフィルタリング¶
標準の構成では、バッチアプリケーションのコンパイルやデプロイメントの構成時にはプロジェクトに含まれる全てのバッチクラスがコンパイルの対象となりますが、 ビルドスクリプトの定義やコマンドラインの指定で、一部のバッチクラスのみをコンパイルすることができます。
ビルドスクリプトの指定によるフィルタリング¶
ビルドスクリプトの構成で有効となっている各DSLコンパイラに対して、コンパイル対象のバッチクラスを include/exclude することができます。
以下、ビルドスクリプトの設定例です。
asakusafw {
spark {
exclude 'com.example.batch.Hoge'
}
m3bp {
include 'com.example.batch.Hoge'
}
}
上記の設定例では、Asakusa on Sparkコンパイラに対してはバッチクラス com.example.batch.Hoge を除外しその他のバッチクラスを全て含めるよう指定しています。
また Asakusa on M3BP コンパイラに対してはバッチクラス com.example.batch.Hoge のみを含めるよう指定しています。
バッチクラス名の文字列には * をワイルドカードとして使用することもできます。
コマンドラインの指定によるフィルタリング¶
コマンドラインの指定によるフィルタリングは、ビルドスクリプトの設定に対してコマンドライン上でバッチコンパイルの対象をフィルタリングします。
コマンドラインの指定によるフィルタリングは、gradlew コマンドを実行する際に各DSLコンパイラの実行用タスクの後に --update <バッチクラス名> と指定します。
例えば、Asakusa on Sparkコンパイラに対してフィルタリングを指定するには、 sparkCompileBatchapps --update <バッチクラス名> と指定します。
バッチクラス名の文字列には * をワイルドカードとして使用することもできます。
以下の例では、パッケージ名に com.example.target.batch を含むバッチクラスのみをバッチコンパイルしてデプロイメントアーカイブを作成しています。
./gradlew sparkCompileBatchapps --update com.example.target.batch.* assemble
Attention
Asakusa Frameworkのバージョン 0.7.6 以前では compileBatchapp タスクに対して --update オプションを指定していましたが、
バージョン 0.8.0 以降は compileBatchapp タスクに --update オプションを指定することはできなくなりました。
代わりに、各DSLコンパイラの実行用タスク ( sparkCompileBatchapps など ) に --update オプションを指定します。
テストツールタスクの実行¶
Experimental
Asakusa Framework バージョン 0.10.2 では、 TestTookTask は試験的機能として提供しています。
TestToolTask [7] を使うことで、テストドライバーやバッチテストランナーが持つ機能を組み合わせてGradleのタスクとして実行することができます。
See also
テストツールタスクの利用例は テストドライバーユーザーガイド - テストツールタスク を参照してください。
| [7] | com.asakusafw.gradle.tasks.TestToolTask |
Hive用DDLファイルの生成¶
generateHiveDDL は Hive連携用の拡張属性を持つDMDLスクリプトからをHive用のDDLファイルを生成します。
generateHiveDDL タスクを実行すると、プロジェクトの build/hive-ddl ディレクトリ配下にHiveのテーブル作成用の CREATE TABLE 文を含むSQLファイルが生成されます。
generateHiveDDL タスクは gradlew コマンド実行時に以下のコマンドラインオプションを指定することができます。
-
--location/path/to/base-location¶ 生成する
CREATE TABLE文にLOCATION(テーブルに対応するファイルを配置するHDFS上のパス) を追加する (LOCATIONの値に'<指定したパス>/<table-name>'を追加)指定がない場合は
LOCATION句は未指定
-
--database-namedatabase-name¶ 生成する
CRATE TABLE文のテーブル名の前にデータベース名を付与する指定がない場合は データベース名は未指定
-
--includeregex-table-name-pattern¶ 指定した正規表現にマッチするテーブルに対してのみDDLを生成する
指定がない場合はすべてのテーブルに対してDDLを生成する
-
--output/path/to/ddloutput¶ 指定した出力先のパスにDDLファイルを生成する
指定がない場合のファイルパスは
${project.buildDir}/hive-ddl/${project.name}.sql
generateHiveDDL タスクの実行例は以下の通りです。
./gradlew generateHiveDDL --location /home/hadoop/target/testing/directio/tables --include item
See also
Hiveとの連携については、 Direct I/O Hive を参照してください。